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:
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().
Name | Location | Description |
---|---|---|
_menu_update_parental_status |
drupal/ |
Checks and updates the 'has_children' status for the parent of a link. |
_menu_tree_data |
drupal/ |
Builds the data representing a menu tree. |
_menu_tree_check_access |
drupal/ |
Sorts the menu tree and recursively checks access for each item. |
_menu_translate |
drupal/ |
Handles dynamic path translation and menu access control. |
_menu_site_is_offline |
drupal/ |
Checks whether the site is in maintenance mode. |
_menu_set_expanded_menus |
drupal/ |
Updates a list of menus with expanded items. |
_menu_router_save |
drupal/ |
Saves data from menu_router_build() to the router table. |
_menu_router_cache |
drupal/ |
Stores the menu router if we have it in memory. |
_menu_router_build |
drupal/ |
Builds the router table based on the data from hook_menu(). |
_menu_navigation_links_rebuild |
drupal/ |
Builds menu links for the items in the menu router. |
_menu_load_objects |
drupal/ |
Loads objects into the map as defined in the $item['load_functions']. |
_menu_link_translate |
drupal/ |
Provides menu link access control, translation, and argument handling. |
_menu_link_parents_set |
drupal/ |
Sets the p1 through p9 values for a menu link being saved. |
_menu_link_move_children |
drupal/ |
Updates the children of a menu link that is being moved. |
_menu_link_map_translate |
drupal/ |
Translates the path elements in the map using any to_arg helper function. |
_menu_link_find_parent |
drupal/ |
Finds a possible parent for a given menu link. |
_menu_link_build |
drupal/ |
Builds a link from a router item. |
_menu_item_localize |
drupal/ |
Localizes the router item title using t() or another callback. |
_menu_find_router_path |
drupal/ |
Finds the router path which will serve this path. |
_menu_delete_item |
drupal/ |
Deletes a single menu link. |
_menu_clear_page_cache |
drupal/ |
Clears the page and block caches at most twice per page load. |
_menu_check_rebuild |
drupal/ |
Checks whether a menu_rebuild() is necessary. |
_menu_check_access |
drupal/ |
Checks access to a menu item using the access callback. |
_menu_build_tree |
drupal/ |
Builds a menu tree. |
theme_menu_tree |
drupal/ |
Returns HTML for a wrapper for a menu sub-tree. |
theme_menu_local_tasks |
drupal/ |
Returns HTML for primary and secondary local tasks. |
theme_menu_local_task |
drupal/ |
Returns HTML for a single local task link. |
theme_menu_local_action |
drupal/ |
Returns HTML for a single local action link. |
theme_menu_link |
drupal/ |
Returns HTML for a menu link and submenu. |
template_preprocess_menu_tree |
drupal/ |
Implements template_preprocess_HOOK() for theme_menu_tree(). |
menu_unserialize |
drupal/ |
Unserializes menu data, using a map to replace path elements. |
menu_tree_set_path |
drupal/ |
Sets the path for determining the active trail of the specified menu tree. |
menu_tree_page_data |
drupal/ |
Gets the data structure for a named menu tree, based on the current page. |
menu_tree_output |
drupal/ |
Returns an output structure for rendering a menu tree. |
menu_tree_get_path |
drupal/ |
Gets the path for determining the active trail of the specified menu tree. |
menu_tree_data |
drupal/ |
Sorts and returns the built data representing a menu tree. |
menu_tree_collect_node_links |
drupal/ |
Collects node links from a given menu tree recursively. |
menu_tree_check_access |
drupal/ |
Checks access and performs dynamic operations for each link in the tree. |
menu_tree_all_data |
drupal/ |
Gets the data structure representing a named menu tree. |
menu_tree |
drupal/ |
Renders a menu tree based on the current path. |
menu_tail_to_arg |
drupal/ |
Returns a string containing the path relative to the current index. |
menu_tail_load |
drupal/ |
Loads the path as one string relative to the current index. |
menu_tab_root_path |
drupal/ |
Returns the router path, or the path for a default local task's parent. |
menu_set_item |
drupal/ |
Replaces the statically cached item for a given path. |
menu_set_custom_theme |
drupal/ |
Sets a custom theme for the current page, if there is one. |
menu_set_active_trail |
drupal/ |
Sets the active trail (path to the menu tree root) of the current page. |
menu_set_active_menu_names |
drupal/ |
Sets (or gets) the active menu for the current page. |
menu_set_active_item |
drupal/ |
Sets the active path, which determines which page is loaded. |
menu_secondary_menu |
drupal/ |
Returns an array of links to be rendered as the Secondary links. |
menu_secondary_local_tasks |
drupal/ |
Returns the rendered local tasks at the second level. |
menu_router_build |
drupal/ |
Collects and alters the menu definitions. |
menu_reset_static_cache |
drupal/ |
Resets the menu system static cache. |
menu_rebuild |
drupal/ |
Populates the database tables used by various menu functions. |
menu_primary_local_tasks |
drupal/ |
Returns the rendered local tasks at the top level. |
menu_navigation_links |
drupal/ |
Returns an array of links for a navigation menu. |
menu_main_menu |
drupal/ |
Returns an array of links to be rendered as the Main menu. |
menu_local_tasks |
drupal/ |
Collects the local tasks (tabs), action links, and the root path. |
menu_local_tabs |
drupal/ |
Returns a renderable element for the primary and secondary tabs. |
menu_local_actions |
drupal/ |
Returns the rendered local actions at the current level. |
menu_load_links |
drupal/ |
Returns an array containing all links for a menu. |
menu_list_system_menus |
drupal/ |
Returns an array containing the names of system-defined (default) menus. |
menu_link_save |
drupal/ |
Saves a menu link. |
menu_link_maintain |
drupal/ |
Inserts, updates, or deletes an uncustomized menu link related to a module. |
menu_link_load |
drupal/ |
Gets a translated, access-checked menu link that is ready for rendering. |
menu_link_get_preferred |
drupal/ |
Looks up the preferred menu link for a given system path. |
menu_link_delete |
drupal/ |
Delete one or several menu links. |
menu_link_children_relative_depth |
drupal/ |
Finds the depth of an item's children relative to its depth. |
menu_links_clone |
drupal/ |
Clones an array of menu links. |
menu_get_router |
drupal/ |
Gets the menu router. |
menu_get_object |
drupal/ |
Gets a loaded object from a router item. |
menu_get_names |
drupal/ |
Build a list of named menus. |
menu_get_item |
drupal/ |
Gets a router item. |
menu_get_custom_theme |
drupal/ |
Gets the custom theme for the current page, if there is one. |
menu_get_ancestors |
drupal/ |
Returns the ancestors (and relevant placeholders) for any given path. |
menu_get_active_trail |
drupal/ |
Gets the active trail (path to root menu root) of the current page. |
menu_get_active_title |
drupal/ |
Gets the title of the current page, as determined by the active trail. |
menu_get_active_menu_names |
drupal/ |
Gets the active menu for the current page. |
menu_get_active_help |
drupal/ |
Returns the help associated with the active menu item. |
menu_get_active_breadcrumb |
drupal/ |
Gets the breadcrumb for the current page, as determined by the active trail. |
menu_execute_active_handler |
drupal/ |
Execute the page callback associated with the current path. |
menu_delete_links |
drupal/ |
Deletes all links for a menu. |
menu_contextual_links |
drupal/ |
Retrieves contextual links for a path based on registered local tasks. |
menu_cache_clear_all |
drupal/ |
Clears all cached menu data. |
menu_cache_clear |
drupal/ |
Clears the cached data for a single named menu. |
menu_build_tree |
drupal/ |
Builds a menu tree, translates links, and checks access. |
drupal_help_arg |
drupal/ |
Generates elements for the $arg array in the help hook. |
Name | Location | Description |
---|---|---|
MENU_VISIBLE_IN_TREE |
drupal/ |
Internal menu flag -- menu item is visible in the menu tree. |
MENU_VISIBLE_IN_BREADCRUMB |
drupal/ |
Internal menu flag -- menu item is visible in the breadcrumb. |
MENU_SUGGESTED_ITEM |
drupal/ |
Menu type -- A normal menu item, hidden until enabled by an administrator. |
MENU_SITE_ONLINE |
drupal/ |
Internal menu status code -- Everything is working fine. |
MENU_SITE_OFFLINE |
drupal/ |
Internal menu status code -- Menu item inaccessible because site is offline. |
MENU_PREFERRED_LINK |
drupal/ |
Reserved key to identify the most specific menu link for a given path. |
MENU_NOT_FOUND |
drupal/ |
Menu status code -- Not found. |
MENU_NORMAL_ITEM |
drupal/ |
Menu type -- A "normal" menu item that's shown in menu and breadcrumbs. |
MENU_MODIFIED_BY_ADMIN |
drupal/ |
Internal menu flag -- menu item can be modified by administrator. |
MENU_MAX_PARTS |
drupal/ |
The maximum number of path elements for a menu callback |
MENU_MAX_DEPTH |
drupal/ |
The maximum depth of a menu links tree - matches the number of p columns. |
MENU_LOCAL_TASK |
drupal/ |
Menu type -- A task specific to the parent item, usually rendered as a tab. |
MENU_LOCAL_ACTION |
drupal/ |
Menu type -- An action specific to the parent, usually rendered as a link. |
MENU_LINKS_TO_PARENT |
drupal/ |
Internal menu flag -- menu item links back to its parent. |
MENU_IS_ROOT |
drupal/ |
Internal menu flag -- menu item is the root of the menu tree. |
MENU_IS_LOCAL_TASK |
drupal/ |
Internal menu flag -- menu item is a local task. |
MENU_IS_LOCAL_ACTION |
drupal/ |
Internal menu flag -- menu item is a local action. |
MENU_FOUND |
drupal/ |
Internal menu status code -- Menu item was found. |
MENU_DEFAULT_LOCAL_TASK |
drupal/ |
Menu type -- The "default" local task, which is initially active. |
MENU_CREATED_BY_ADMIN |
drupal/ |
Internal menu flag -- menu item was created by administrator. |
MENU_CONTEXT_PAGE |
drupal/ |
Internal menu flag: Local task should be displayed in page context. |
MENU_CONTEXT_NONE |
drupal/ |
Internal menu flag: Invisible local task. |
MENU_CONTEXT_INLINE |
drupal/ |
Internal menu flag: Local task should be displayed inline. |
MENU_CALLBACK |
drupal/ |
Menu type -- A hidden, internal callback, typically used for API calls. |
MENU_ACCESS_DENIED |
drupal/ |
Menu status code -- Access denied. |
Name | Location | Description |
---|---|---|
Menu tree parameters |
drupal/ |
Parameters for a menu tree. |
Menu status codes |
drupal/ |
Status codes for menu callbacks. |
Menu item types |
drupal/ |
Definitions for various menu item types. |
Menu flags |
drupal/ |
Flags for use in the "type" attribute of menu items. |
Menu context types |
drupal/ |
Flags for use in the "context" attribute of menu router items. |