Same name and namespace in other branches
  1. 10 core/lib/Drupal/Core/Menu/menu.api.php \menu
  2. 4.6.x includes/menu.inc \menu
  3. 5.x includes/menu.inc \menu
  4. 6.x includes/menu.inc \menu
  5. 7.x includes/menu.inc \menu
  6. 8.9.x core/lib/Drupal/Core/Menu/menu.api.php \menu
  7. 9 core/lib/Drupal/Core/Menu/menu.api.php \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.

File

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

Functions

Namesort ascending Location Description
theme_menu_tree includes/menu.inc Generate the HTML for a menu tree.
theme_menu_local_tasks includes/menu.inc Returns the rendered local tasks. The default implementation renders them as tabs.
theme_menu_local_task includes/menu.inc Generate the HTML representing a given menu item ID as a tab.
theme_menu_links 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_item_link includes/menu.inc Generate the HTML representing a given menu item ID.
theme_menu_item includes/menu.inc Generate the HTML output for a single menu item.
menu_tree includes/menu.inc Returns a rendered menu tree.
menu_set_location includes/menu.inc Change the current menu location of the user.
menu_set_active_item includes/menu.inc Sets the path of the active menu item.
menu_secondary_local_tasks includes/menu.inc Returns the rendered HTML of the secondary local tasks.
menu_secondary_links 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_rebuild includes/menu.inc Populate the database representation of the menu.
menu_primary_local_tasks includes/menu.inc Returns the rendered HTML of the primary local tasks.
menu_primary_links 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_item_link includes/menu.inc Returns the rendered link to a menu item.
menu_in_active_trail_in_submenu includes/menu.inc Returns true when the menu item is in the active trail within a specific subsection of the menu tree.
menu_in_active_trail includes/menu.inc Returns true when the menu item is in the active trail.
menu_get_root_menus includes/menu.inc Retrieves the menu ID and title of all root menus.
menu_get_menu includes/menu.inc Return the menu data structure.
menu_get_local_tasks includes/menu.inc Return the local task tree.
menu_get_item includes/menu.inc Retrieves the menu item specified by $mid, or by $path if $mid is not given.
menu_get_active_title includes/menu.inc Returns the title of the active menu item.
menu_get_active_nontask_item 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_item includes/menu.inc Returns the ID of the active menu item.
menu_get_active_help includes/menu.inc Returns the help associated with the active menu item.
menu_get_active_breadcrumb includes/menu.inc Returns an array of rendered menu items in the active breadcrumb trail.
menu_execute_active_handler includes/menu.inc Execute the handler associated with the active menu item.

Constants

Namesort ascending Location Description
MENU_VISIBLE_IN_TREE includes/menu.inc
MENU_VISIBLE_IN_TREE includes/menu.inc
MENU_VISIBLE_IN_BREADCRUMB includes/menu.inc
MENU_VISIBLE_IN_BREADCRUMB includes/menu.inc
MENU_VISIBLE_IF_HAS_CHILDREN includes/menu.inc
MENU_VISIBLE_IF_HAS_CHILDREN includes/menu.inc
MENU_SUGGESTED_ITEM 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 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_SITE_OFFLINE includes/menu.inc
MENU_SITE_OFFLINE includes/menu.inc
MENU_NOT_FOUND includes/menu.inc
MENU_NOT_FOUND includes/menu.inc
MENU_NORMAL_ITEM 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 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_MODIFIED_BY_ADMIN includes/menu.inc
MENU_MODIFIED_BY_ADMIN includes/menu.inc
MENU_MODIFIABLE_BY_ADMIN includes/menu.inc
MENU_MODIFIABLE_BY_ADMIN includes/menu.inc
MENU_LOCAL_TASK 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 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_LINKS_TO_PARENT includes/menu.inc
MENU_LINKS_TO_PARENT includes/menu.inc
MENU_ITEM_GROUPING 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 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_IS_ROOT includes/menu.inc @name Menu flags
MENU_IS_LOCAL_TASK includes/menu.inc
MENU_IS_LOCAL_TASK includes/menu.inc
MENU_FOUND includes/menu.inc @name Menu status codes
MENU_EXPANDED includes/menu.inc
MENU_EXPANDED includes/menu.inc
MENU_DYNAMIC_ITEM includes/menu.inc Dynamic menu items change frequently, and so should not be stored in the database for administrative customization.
MENU_DYNAMIC_ITEM includes/menu.inc Dynamic menu items change frequently, and so should not be stored in the database for administrative customization.
MENU_DEFAULT_LOCAL_TASK 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 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_CUSTOM_MENU 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 includes/menu.inc Custom menus are those defined by the administrator. Reserved for internal use; do not return from hook_menu() implementations.
MENU_CUSTOM_ITEM 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 includes/menu.inc Custom items are those defined by the administrator. Reserved for internal use; do not return from hook_menu() implementations.
MENU_CREATED_BY_ADMIN includes/menu.inc
MENU_CREATED_BY_ADMIN includes/menu.inc
MENU_CALLBACK 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 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_ACCESS_DENIED includes/menu.inc
MENU_ACCESS_DENIED includes/menu.inc