Menu system

  1. 7.x drupal/includes/menu.inc menu
  2. 5.x drupal/includes/menu.inc menu
  3. 6.x drupal/includes/menu.inc menu
  4. 8.x drupal/core/includes/menu.inc menu

Define the navigation menus, and route page requests to code based on URLs.

The Drupal menu system drives both the navigation system from a user perspective and the callback system that Drupal uses to respond to URLs passed from the browser. For this reason, a good understanding of the menu system is fundamental to the creation of complex modules.

Drupal's menu system follows a simple hierarchy defined by paths. Implementations of hook_menu() define menu items and assign them to paths (which should be unique). The menu system aggregates these items and determines the menu hierarchy from the paths. For example, if the paths defined were a, a/b, e, a/b/c/d, f/g, and a/b/h, the menu system would form the structure:

  • a

    • a/b

      • a/b/c/d
      • a/b/h
  • e
  • f/g

Note that the number of elements in the path does not necessarily determine the depth of the menu item in the tree.

When responding to a page request, the menu system looks to see if the path requested by the browser is registered as a menu item with a callback. If not, the system searches up the menu tree for the most complete match with a callback it can find. If the path a/b/i is requested in the tree above, the callback for a/b would be used.

The found callback function is called with any arguments specified in the "callback arguments" attribute of its menu item. The attribute must be an array. After these arguments, any remaining components of the path are appended as further arguments. In this way, the callback for a/b above could respond to a request for a/b/i differently than a request for a/b/j.

For an illustration of this process, see page_example.module.

Access to the callback functions is also protected by the menu system. The "access" attribute of each menu item is checked as the search for a callback proceeds. If this attribute is TRUE, then access is granted; if FALSE, then access is denied. The first found "access" attribute determines the accessibility of the target. Menu items may omit this attribute to use the value provided by an ancestor item.

In the default Drupal interface, you will notice many links rendered as tabs. These are known in the menu system as "local tasks", and they are rendered as tabs by default, though other presentations are possible. Local tasks function just as other menu items in most respects. It is convention that the names of these tasks should be short verbs if possible. In addition, a "default" local task should be provided for each set. When visiting a local task's parent menu item, the default local task will be rendered as if it is selected; this provides for a normal tab user experience. This default task is special in that it links not to its provided path, but to its parent item's path instead. The default task's path is only used to place it appropriately in the menu hierarchy.

Functions

Namesort descending Location Description
menu_execute_active_handler drupal/includes/menu.inc Execute the handler associated with the active menu item.
menu_get_active_breadcrumb drupal/includes/menu.inc Returns an array of rendered menu items in the active breadcrumb trail.
menu_get_active_help drupal/includes/menu.inc Returns the help associated with the active menu item.
menu_get_active_item drupal/includes/menu.inc Returns the ID of the active menu item.
menu_get_active_nontask_item drupal/includes/menu.inc Returns the ID of the current menu item or, if the current item is a local task, the menu item to which this task is attached.
menu_get_active_title drupal/includes/menu.inc Returns the title of the active menu item.
menu_get_item drupal/includes/menu.inc Retrieves the menu item specified by $mid, or by $path if $mid is not given.
menu_get_local_tasks drupal/includes/menu.inc Return the local task tree.
menu_get_menu drupal/includes/menu.inc Return the menu data structure.
menu_get_root_menus drupal/includes/menu.inc Retrieves the menu ID and title of all root menus.
menu_in_active_trail drupal/includes/menu.inc Returns TRUE when the menu item is in the active trail.
menu_in_active_trail_in_submenu drupal/includes/menu.inc Returns TRUE when the menu item is in the active trail within a specific subsection of the menu tree.
menu_item_link drupal/includes/menu.inc Returns the rendered link to a menu item.
menu_primary_links drupal/includes/menu.inc Returns an array containing the primary links. Can optionally descend from the root of the Primary links menu towards the current node for a specified number of levels and return that submenu. Used to generate a primary/secondary menu from different…
menu_primary_local_tasks drupal/includes/menu.inc Returns the rendered HTML of the primary local tasks.
menu_rebuild drupal/includes/menu.inc Populate the database representation of the menu.
menu_secondary_links drupal/includes/menu.inc Returns an array containing the secondary links. Secondary links can be either a second level of the Primary links menu or generated from their own menu.
menu_secondary_local_tasks drupal/includes/menu.inc Returns the rendered HTML of the secondary local tasks.
menu_set_active_item drupal/includes/menu.inc Sets the path of the active menu item.
menu_set_location drupal/includes/menu.inc Change the current menu location of the user.
menu_tree drupal/includes/menu.inc Returns a rendered menu tree.
theme_menu_item drupal/includes/menu.inc Generate the HTML output for a single menu item.
theme_menu_item_link drupal/includes/menu.inc Generate the HTML representing a given menu item ID.
theme_menu_links drupal/includes/menu.inc Returns the themed HTML for primary and secondary links. Note that this function is overridden by most core themes because those themes display links in "link | link" format, not from a list. Also note that by default links rendered with…
theme_menu_local_task drupal/includes/menu.inc Generate the HTML representing a given menu item ID as a tab.
theme_menu_local_tasks drupal/includes/menu.inc Returns the rendered local tasks. The default implementation renders them as tabs.
theme_menu_tree drupal/includes/menu.inc Generate the HTML for a menu tree.

Constants

Namesort descending Location Description
MENU_ACCESS_DENIED drupal/includes/menu.inc
MENU_ACCESS_DENIED drupal/includes/menu.inc
MENU_CALLBACK drupal/includes/menu.inc Callbacks simply register a path so that the correct function is fired when the URL is accessed. They are not shown in the menu.
MENU_CALLBACK drupal/includes/menu.inc Callbacks simply register a path so that the correct function is fired when the URL is accessed. They are not shown in the menu.
MENU_CREATED_BY_ADMIN drupal/includes/menu.inc
MENU_CREATED_BY_ADMIN drupal/includes/menu.inc
MENU_CUSTOM_ITEM drupal/includes/menu.inc Custom items are those defined by the administrator. Reserved for internal use; do not return from hook_menu() implementations.
MENU_CUSTOM_ITEM drupal/includes/menu.inc Custom items are those defined by the administrator. Reserved for internal use; do not return from hook_menu() implementations.
MENU_CUSTOM_MENU drupal/includes/menu.inc Custom menus are those defined by the administrator. Reserved for internal use; do not return from hook_menu() implementations.
MENU_CUSTOM_MENU drupal/includes/menu.inc Custom menus are those defined by the administrator. Reserved for internal use; do not return from hook_menu() implementations.
MENU_DEFAULT_LOCAL_TASK drupal/includes/menu.inc Every set of local tasks should provide one "default" task, that links to the same path as its parent when clicked.
MENU_DEFAULT_LOCAL_TASK drupal/includes/menu.inc Every set of local tasks should provide one "default" task, that links to the same path as its parent when clicked.
MENU_DYNAMIC_ITEM drupal/includes/menu.inc Dynamic menu items change frequently, and so should not be stored in the database for administrative customization.
MENU_DYNAMIC_ITEM drupal/includes/menu.inc Dynamic menu items change frequently, and so should not be stored in the database for administrative customization.
MENU_EXPANDED drupal/includes/menu.inc
MENU_EXPANDED drupal/includes/menu.inc
MENU_FOUND drupal/includes/menu.inc
MENU_FOUND drupal/includes/menu.inc
MENU_IS_LOCAL_TASK drupal/includes/menu.inc
MENU_IS_LOCAL_TASK drupal/includes/menu.inc
MENU_IS_ROOT drupal/includes/menu.inc
MENU_IS_ROOT drupal/includes/menu.inc
MENU_ITEM_GROUPING drupal/includes/menu.inc Item groupings are used for pages like "node/add" that simply list subpages to visit. They are distinguished from other pages in that they will disappear from the menu if no subpages exist.
MENU_ITEM_GROUPING drupal/includes/menu.inc Item groupings are used for pages like "node/add" that simply list subpages to visit. They are distinguished from other pages in that they will disappear from the menu if no subpages exist.
MENU_LINKS_TO_PARENT drupal/includes/menu.inc
MENU_LINKS_TO_PARENT drupal/includes/menu.inc
MENU_LOCAL_TASK drupal/includes/menu.inc Local tasks are rendered as tabs by default. Use this for menu items that describe actions to be performed on their parent item. An example is the path "node/52/edit", which performs the "edit" task on "node/52".
MENU_LOCAL_TASK drupal/includes/menu.inc Local tasks are rendered as tabs by default. Use this for menu items that describe actions to be performed on their parent item. An example is the path "node/52/edit", which performs the "edit" task on "node/52".
MENU_MODIFIABLE_BY_ADMIN drupal/includes/menu.inc
MENU_MODIFIABLE_BY_ADMIN drupal/includes/menu.inc
MENU_MODIFIED_BY_ADMIN drupal/includes/menu.inc
MENU_MODIFIED_BY_ADMIN drupal/includes/menu.inc
MENU_NORMAL_ITEM drupal/includes/menu.inc Normal menu items show up in the menu tree and can be moved/hidden by the administrator. Use this for most menu items. It is the default value if no menu item type is specified.
MENU_NORMAL_ITEM drupal/includes/menu.inc Normal menu items show up in the menu tree and can be moved/hidden by the administrator. Use this for most menu items. It is the default value if no menu item type is specified.
MENU_NOT_FOUND drupal/includes/menu.inc
MENU_NOT_FOUND drupal/includes/menu.inc
MENU_SITE_OFFLINE drupal/includes/menu.inc
MENU_SITE_OFFLINE drupal/includes/menu.inc
MENU_SUGGESTED_ITEM drupal/includes/menu.inc Modules may "suggest" menu items that the administrator may enable. They act just as callbacks do until enabled, at which time they act like normal items.
MENU_SUGGESTED_ITEM drupal/includes/menu.inc Modules may "suggest" menu items that the administrator may enable. They act just as callbacks do until enabled, at which time they act like normal items.
MENU_VISIBLE_IF_HAS_CHILDREN drupal/includes/menu.inc
MENU_VISIBLE_IF_HAS_CHILDREN drupal/includes/menu.inc
MENU_VISIBLE_IN_BREADCRUMB drupal/includes/menu.inc
MENU_VISIBLE_IN_BREADCRUMB drupal/includes/menu.inc
MENU_VISIBLE_IN_TREE drupal/includes/menu.inc
MENU_VISIBLE_IN_TREE drupal/includes/menu.inc

File

drupal/includes/menu.inc, line 8
API for the Drupal menu system.