Menu system

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. As a note, this is related to, but separate from menu.module, which allows menus (which in this context are hierarchical lists of links) to be customized from the Drupal administrative interface.

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 "page 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 callback" with an optional "access arguments" of each menu item is called before the page callback proceeds. If this returns TRUE, then access is granted; if FALSE, then access is denied. Default local task menu items (see next paragraph) may omit this attribute to use the value provided by the parent 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.

Everything described so far is stored in the menu_router table. The menu_links table holds the visible menu links. By default these are derived from the same hook_menu definitions, however you are free to add more with menu_link_save().

Functions & methods

NameLocationDescription
drupal_help_argincludes/menu.incGenerates elements for the $arg array in the help hook.
menu_build_treeincludes/menu.incBuild a menu tree, translate links, and check access.
menu_cache_clearincludes/menu.incClears the cached cached data for a single named menu.
menu_cache_clear_allincludes/menu.incClears all cached menu data. This should be called any time broad changes might have been made to the router items or menu links.
menu_contextual_linksincludes/menu.incRetrieve contextual links for a system object based on registered local tasks.
menu_delete_linksincludes/menu.incDeletes all links for a menu.
menu_execute_active_handlerincludes/menu.incExecute the page callback associated with the current path.
menu_get_active_breadcrumbincludes/menu.incGet the breadcrumb for the current page, as determined by the active trail.
menu_get_active_helpincludes/menu.incReturns the help associated with the active menu item.
menu_get_active_menu_namesincludes/menu.incGet the active menu for the current page - determines the active trail.
menu_get_active_titleincludes/menu.incGet the title of the current page, as determined by the active trail.
menu_get_active_trailincludes/menu.incGets the active trail (path to root menu root) of the current page.
menu_get_ancestorsincludes/menu.incReturns the ancestors (and relevant placeholders) for any given path.
menu_get_custom_themeincludes/menu.incGets the custom theme for the current page, if there is one.
menu_get_itemincludes/menu.incGet a router item.
menu_get_namesincludes/menu.incBuild a list of named menus.
menu_get_objectincludes/menu.incGet a loaded object from a router item.
menu_get_routerincludes/menu.incGet the menu router.
menu_links_cloneincludes/menu.incClone an array of menu links.
menu_link_children_relative_depthincludes/menu.incFind the depth of an item's children relative to its depth.
menu_link_deleteincludes/menu.incDelete one or several menu links.
menu_link_get_preferredincludes/menu.incLookup the preferred menu link for a given system path.
menu_link_loadincludes/menu.incGet a menu link by its mlid, access checked and link translated for rendering.
menu_link_maintainincludes/menu.incInsert, update or delete an uncustomized menu link related to a module.
menu_link_saveincludes/menu.incSaves a menu link.
menu_list_system_menusincludes/menu.incReturn an array containing the names of system-defined (default) menus.
menu_load_linksincludes/menu.incReturns an array containing all links for a menu.
menu_local_actionsincludes/menu.incReturns the rendered local actions at the current level.
menu_local_tabsincludes/menu.incReturns a renderable element for the primary and secondary tabs.
menu_local_tasksincludes/menu.incCollects the local tasks (tabs), action links, and the root path.
menu_main_menuincludes/menu.incReturn an array of links to be rendered as the Main menu.
menu_navigation_linksincludes/menu.incReturn an array of links for a navigation menu.
menu_primary_local_tasksincludes/menu.incReturns the rendered local tasks at the top level.
menu_rebuildincludes/menu.inc(Re)populate the database tables used by various menu functions.
menu_reset_static_cacheincludes/menu.incResets the menu system static cache.
menu_router_buildincludes/menu.incCollect and alter the menu definitions.
menu_secondary_local_tasksincludes/menu.incReturns the rendered local tasks at the second level.
menu_secondary_menuincludes/menu.incReturn an array of links to be rendered as the Secondary links.
menu_set_active_itemincludes/menu.incSet the active path, which determines which page is loaded.
menu_set_active_menu_namesincludes/menu.incSet (or get) the active menu for the current page - determines the active trail.
menu_set_active_trailincludes/menu.incSets the active trail (path to menu tree root) of the current page.
menu_set_custom_themeincludes/menu.incSets a custom theme for the current page, if there is one.
menu_set_itemincludes/menu.incReplaces the statically cached item for a given path.
menu_tab_root_pathincludes/menu.incReturns the router path, or the path of the parent tab of a default local task.
menu_tail_loadincludes/menu.incLoads path as one string from the argument we are currently at.
menu_tail_to_argincludes/menu.incReturns path as one string from the argument we are currently at.
menu_treeincludes/menu.incRenders a menu tree based on the current path.
menu_tree_all_dataincludes/menu.incGet the data structure representing a named menu tree.
menu_tree_check_accessincludes/menu.incCheck access and perform other dynamic operations for each link in the tree.
menu_tree_collect_node_linksincludes/menu.incRecursive helper function - collect node links.
menu_tree_dataincludes/menu.incBuilds the data representing a menu tree.
menu_tree_get_pathincludes/menu.incGet the path for determining the active trail of the specified menu tree.
menu_tree_outputincludes/menu.incReturns a rendered menu tree.
menu_tree_page_dataincludes/menu.incGet the data structure representing a named menu tree, based on the current page.
menu_tree_set_pathincludes/menu.incSet the path for determining the active trail of the specified menu tree.
menu_unserializeincludes/menu.incUnserializes menu data, using a map to replace path elements.
template_preprocess_menu_treeincludes/menu.incPreprocesses the rendered tree for theme_menu_tree().
theme_menu_linkincludes/menu.incReturns HTML for a menu link and submenu.
theme_menu_local_actionincludes/menu.incReturns HTML for a single local action link.
theme_menu_local_taskincludes/menu.incReturns HTML for a single local task link.
theme_menu_local_tasksincludes/menu.incReturns HTML for primary and secondary local tasks.
theme_menu_treeincludes/menu.incReturns HTML for a wrapper for a menu sub-tree.
_menu_build_treeincludes/menu.incBuild a menu tree.
_menu_check_accessincludes/menu.incCheck access to a menu item using the access callback
_menu_clear_page_cacheincludes/menu.incHelper function to clear the page and block caches at most twice per page load.
_menu_delete_itemincludes/menu.incHelper function for menu_link_delete; deletes a single menu link.
_menu_find_router_pathincludes/menu.incFind the router path which will serve this path.
_menu_item_localizeincludes/menu.incLocalize the router item title using t() or another callback.
_menu_link_buildincludes/menu.incBuilds a link from a router item.
_menu_link_find_parentincludes/menu.incFind a possible parent for a given menu link.
_menu_link_map_translateincludes/menu.incThis function translates the path elements in the map using any to_arg helper function. These functions take an argument and return an object. See http://drupal.org/node/109153 for more information.
_menu_link_move_childrenincludes/menu.incUpdate the children of a menu link that's being moved.
_menu_link_parents_setincludes/menu.incHelper function that sets the p1..p9 values for a menu link being saved.
_menu_link_translateincludes/menu.incThis function is similar to _menu_translate() but does link-specific preparation such as always calling to_arg functions
_menu_load_objectsincludes/menu.incLoads objects into the map as defined in the $item['load_functions'].
_menu_navigation_links_rebuildincludes/menu.incHelper function to build menu links for the items in the menu router.
_menu_router_buildincludes/menu.incHelper function to build the router table based on the data from hook_menu.
_menu_router_cacheincludes/menu.incHelper function to store the menu router if we have it in memory.
_menu_router_saveincludes/menu.incHelper function to save data from menu_router_build() to the router table.
_menu_set_expanded_menusincludes/menu.incHelper function to update a list of menus with expanded items
_menu_site_is_offlineincludes/menu.incChecks whether the site is in maintenance mode.
_menu_translateincludes/menu.incHandles dynamic path translation and menu access control.
_menu_tree_check_accessincludes/menu.incRecursive helper function for menu_tree_check_access()
_menu_tree_dataincludes/menu.incRecursive helper function to build the data representing a menu tree.
_menu_update_parental_statusincludes/menu.incCheck and update the has_children status for the parent of a link.

Constants

NameLocationDescription
MENU_ACCESS_DENIEDincludes/menu.incInternal menu status code -- Menu item access is denied.
MENU_CALLBACKincludes/menu.incMenu type -- A hidden, internal callback, typically used for API calls.
MENU_CONTEXT_INLINEincludes/menu.incInternal menu flag: Local task should be displayed inline.
MENU_CONTEXT_NONEincludes/menu.incInternal menu flag: Invisible local task.
MENU_CONTEXT_PAGEincludes/menu.incInternal menu flag: Local task should be displayed in page context.
MENU_CREATED_BY_ADMINincludes/menu.incInternal menu flag -- menu item was created by administrator.
MENU_DEFAULT_LOCAL_TASKincludes/menu.incMenu type -- The "default" local task, which is initially active.
MENU_FOUNDincludes/menu.incInternal menu status code -- Menu item was found.
MENU_IS_LOCAL_ACTIONincludes/menu.incInternal menu flag -- menu item is a local action.
MENU_IS_LOCAL_TASKincludes/menu.incInternal menu flag -- menu item is a local task.
MENU_IS_ROOTincludes/menu.incInternal menu flag -- menu item is the root of the menu tree.
MENU_LINKS_TO_PARENTincludes/menu.incInternal menu flag -- menu item links back to its parent.
MENU_LOCAL_ACTIONincludes/menu.incMenu type -- An action specific to the parent, usually rendered as a link.
MENU_LOCAL_TASKincludes/menu.incMenu type -- A task specific to the parent item, usually rendered as a tab.
MENU_MAX_DEPTHincludes/menu.incThe maximum depth of a menu links tree - matches the number of p columns.
MENU_MAX_PARTSincludes/menu.incThe maximum number of path elements for a menu callback
MENU_MODIFIED_BY_ADMINincludes/menu.incInternal menu flag -- menu item can be modified by administrator.
MENU_NORMAL_ITEMincludes/menu.incMenu type -- A "normal" menu item that's shown in menu and breadcrumbs.
MENU_NOT_FOUNDincludes/menu.incInternal menu status code -- Menu item was not found.
MENU_PREFERRED_LINKincludes/menu.incReserved key to identify the most specific menu link for a given path.
MENU_SITE_OFFLINEincludes/menu.incInternal menu status code -- Menu item inaccessible because site is offline.
MENU_SITE_ONLINEincludes/menu.incInternal menu status code -- Everything is working fine.
MENU_SUGGESTED_ITEMincludes/menu.incMenu type -- A normal menu item, hidden until enabled by an administrator.
MENU_VISIBLE_IN_BREADCRUMBincludes/menu.incInternal menu flag -- menu item is visible in the breadcrumb.
MENU_VISIBLE_IN_TREEincludes/menu.incInternal menu flag -- menu item is visible in the menu tree.

Groups

NameLocationDescription
Menu context typesincludes/menu.incFlags for use in the "context" attribute of menu router items.
Menu flagsincludes/menu.incFlags for use in the "type" attribute of menu items.
Menu item typesincludes/menu.incDefinitions for various menu item types.
Menu status codesincludes/menu.incStatus codes for menu callbacks.
Menu tree parametersincludes/menu.incParameters for a menu tree.

File

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