Menu system

  1. drupal
    1. 5
    2. 6
    3. 7
    4. 8

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.

Constants

NameDescription
MENU_ACCESS_DENIED
MENU_CALLBACKCallbacks 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
MENU_CUSTOM_ITEMCustom items are those defined by the administrator. Reserved for internal use; do not return from hook_menu() implementations.
MENU_CUSTOM_MENUCustom menus are those defined by the administrator. Reserved for internal use; do not return from hook_menu() implementations.
MENU_DEFAULT_LOCAL_TASKEvery set of local tasks should provide one "default" task, that links to the same path as its parent when clicked.
MENU_DYNAMIC_ITEMDynamic menu items change frequently, and so should not be stored in the database for administrative customization.
MENU_EXPANDED
MENU_FOUND
MENU_IS_LOCAL_TASK
MENU_IS_ROOT
MENU_ITEM_GROUPINGItem 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
MENU_LOCAL_TASKLocal 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
MENU_MODIFIED_BY_ADMIN
MENU_NORMAL_ITEMNormal 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
MENU_SITE_OFFLINE
MENU_SUGGESTED_ITEMModules 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
MENU_VISIBLE_IN_BREADCRUMB
MENU_VISIBLE_IN_TREE

Functions & methods

NameDescription
menu_execute_active_handlerExecute the handler associated with the active menu item.
menu_get_active_breadcrumbReturns an array of rendered menu items in the active breadcrumb trail.
menu_get_active_helpReturns the help associated with the active menu item.
menu_get_active_itemReturns the ID of the active menu item.
menu_get_active_nontask_itemReturns 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_titleReturns the title of the active menu item.
menu_get_itemRetrieves the menu item specified by $mid, or by $path if $mid is not given.
menu_get_local_tasksReturn the local task tree.
menu_get_menuReturn the menu data structure.
menu_get_root_menusRetrieves the menu ID and title of all root menus.
menu_in_active_trailReturns TRUE when the menu item is in the active trail.
menu_in_active_trail_in_submenuReturns TRUE when the menu item is in the active trail within a specific subsection of the menu tree.
menu_item_linkReturns the rendered link to a menu item.
menu_primary_linksReturns 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_tasksReturns the rendered HTML of the primary local tasks.
menu_rebuildPopulate the database representation of the menu.
menu_secondary_linksReturns 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_tasksReturns the rendered HTML of the secondary local tasks.
menu_set_active_itemSets the path of the active menu item.
menu_set_locationChange the current menu location of the user.
menu_treeReturns a rendered menu tree.
theme_menu_itemGenerate the HTML output for a single menu item.
theme_menu_item_linkGenerate the HTML representing a given menu item ID.
theme_menu_linksReturns 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_taskGenerate the HTML representing a given menu item ID as a tab.
theme_menu_local_tasksReturns the rendered local tasks. The default implementation renders them as tabs.
theme_menu_treeGenerate the HTML for a menu tree.

includes/menu.inc, line 8