Same name and namespace in other branches
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
- a/b
- 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().
File
- includes/
menu.inc, line 8 - API for the Drupal menu system.
Functions
Name | Location | Description |
---|---|---|
_menu_update_parental_status |
includes/ |
Check and update the has_children status for the parent of a link. |
_menu_tree_data |
includes/ |
Recursive helper function to build the data representing a menu tree. |
_menu_tree_cid |
includes/ |
Helper function - compute the real cache ID for menu tree data. |
_menu_tree_check_access |
includes/ |
Recursive helper function for menu_tree_check_access() |
_menu_translate |
includes/ |
Handles dynamic path translation and menu access control. |
_menu_site_is_offline |
includes/ |
Checks whether the site is off-line for maintenance. |
_menu_set_expanded_menus |
includes/ |
Helper function to update a list of menus with expanded items |
_menu_router_cache |
includes/ |
Helper function to store the menu router if we have it in memory. |
_menu_router_build |
includes/ |
Helper function to build the router table based on the data from hook_menu. |
_menu_navigation_links_rebuild |
includes/ |
Helper function to build menu links for the items in the menu router. |
_menu_load_objects |
includes/ |
Loads objects into the map as defined in the $item['load_functions']. |
_menu_link_translate |
includes/ |
This function is similar to _menu_translate() but does link-specific preparation such as always calling to_arg functions. |
_menu_link_parents_set |
includes/ |
Helper function that sets the p1..p9 values for a menu link being saved. |
_menu_link_move_children |
includes/ |
Update the children of a menu link that's being moved. |
_menu_link_map_translate |
includes/ |
This 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_build |
includes/ |
Builds a link from a router item. |
_menu_item_localize |
includes/ |
Localize the router item title using t() or another callback. |
_menu_find_router_path |
includes/ |
Find the router path which will serve this path. |
_menu_delete_item |
includes/ |
Helper function for menu_link_delete; deletes a single menu link. |
_menu_clear_page_cache |
includes/ |
Helper function to clear the page and block caches at most twice per page load. |
_menu_check_access |
includes/ |
Check access to a menu item using the access callback |
theme_menu_tree |
includes/ |
Generate the HTML output for a menu tree |
theme_menu_local_tasks |
includes/ |
Returns the rendered local tasks. The default implementation renders them as tabs. |
theme_menu_local_task |
includes/ |
Generate the HTML output for a single local task link. |
theme_menu_item_link |
includes/ |
Generate the HTML output for a single menu link. |
theme_menu_item |
includes/ |
Generate the HTML output for a menu item and submenu. |
menu_valid_path |
includes/ |
Validates the path of a menu link being created or edited. |
menu_unserialize |
includes/ |
The menu system uses serialized arrays stored in the database for arguments. However, often these need to change according to the current path. This function unserializes such an array and does the necessary change. |
menu_tree_page_data |
includes/ |
Get the data structure representing a named menu tree, based on the current page. |
menu_tree_output |
includes/ |
Returns a rendered menu tree. |
menu_tree_data |
includes/ |
Build the data representing a menu tree. |
menu_tree_collect_node_links |
includes/ |
Recursive helper function - collect node links. |
menu_tree_check_access |
includes/ |
Check access and perform other dynamic operations for each link in the tree. |
menu_tree_all_data |
includes/ |
Get the data structure representing a named menu tree. |
menu_tree |
includes/ |
Render a menu tree based on the current path. |
menu_tail_to_arg |
includes/ |
|
menu_tab_root_path |
includes/ |
Returns the router path, or the path of the parent tab of a default local task. |
menu_set_item |
includes/ |
Replaces the statically cached item for a given path. |
menu_set_active_trail |
includes/ |
Sets or gets the active trail (path to root menu root) of the current page. |
menu_set_active_menu_name |
includes/ |
Set (or get) the active menu for the current page - determines the active trail. |
menu_set_active_item |
includes/ |
Set the active path, which determines which page is loaded. |
menu_secondary_local_tasks |
includes/ |
Returns the rendered local tasks at the second level. |
menu_secondary_links |
includes/ |
Return an array of links to be rendered as the Secondary links. |
menu_router_build |
includes/ |
Collect, alter and store the menu definitions. |
menu_rebuild |
includes/ |
(Re)populate the database tables used by various menu functions. |
menu_primary_local_tasks |
includes/ |
Returns the rendered local tasks at the top level. |
menu_primary_links |
includes/ |
Return an array of links to be rendered as the Primary links. |
menu_navigation_links |
includes/ |
Return an array of links for a navigation menu. |
menu_local_tasks |
includes/ |
Collects the local tasks (tabs) for a given level. |
menu_list_system_menus |
includes/ |
Return an array containing the names of system-defined (default) menus. |
menu_link_save |
includes/ |
Save a menu link. |
menu_link_maintain |
includes/ |
Insert, update or delete an uncustomized menu link related to a module. |
menu_link_load |
includes/ |
Get a menu link by its mlid, access checked and link translated for rendering. |
menu_link_delete |
includes/ |
Delete one or several menu links. |
menu_link_children_relative_depth |
includes/ |
Find the depth of an item's children relative to its depth. |
menu_get_object |
includes/ |
Get a loaded object from a router item. |
menu_get_names |
includes/ |
Build a list of named menus. |
menu_get_item |
includes/ |
Get a router item. |
menu_get_ancestors |
includes/ |
Returns the ancestors (and relevant placeholders) for any given path. |
menu_get_active_trail |
includes/ |
Gets the active trail (path to root menu root) of the current page. |
menu_get_active_title |
includes/ |
Get the title of the current page, as determined by the active trail. |
menu_get_active_menu_name |
includes/ |
Get the active menu for the current page - determines the active trail. |
menu_get_active_help |
includes/ |
Returns the help associated with the active menu item. |
menu_get_active_breadcrumb |
includes/ |
Get the breadcrumb for the current page, as determined by the active trail. |
menu_execute_active_handler |
includes/ |
Execute the page callback associated with the current path |
menu_cache_clear_all |
includes/ |
Clears all cached menu data. This should be called any time broad changes might have been made to the router items or menu links. |
menu_cache_clear |
includes/ |
Clears the cached cached data for a single named menu. |
drupal_help_arg |
includes/ |
Generates elements for the $arg array in the help hook. |
Constants
Name | Location | Description |
---|---|---|
MENU_VISIBLE_IN_TREE |
includes/ |
|
MENU_VISIBLE_IN_BREADCRUMB |
includes/ |
|
MENU_SUGGESTED_ITEM |
includes/ |
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. Note for the value: 0x0010 was a flag which is no longer used, but this way the values… |
MENU_SITE_OFFLINE |
includes/ |
|
MENU_NOT_FOUND |
includes/ |
|
MENU_NORMAL_ITEM |
includes/ |
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_MAX_PARTS |
includes/ |
The maximum number of path elements for a menu callback |
MENU_MAX_DEPTH |
includes/ |
The maximum depth of a menu links tree - matches the number of p columns. |
MENU_LOCAL_TASK |
includes/ |
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_IS_ROOT |
includes/ |
|
MENU_IS_LOCAL_TASK |
includes/ |
|
MENU_FOUND |
includes/ |
|
MENU_DEFAULT_LOCAL_TASK |
includes/ |
Every set of local tasks should provide one "default" task, that links to the same path as its parent when clicked. |
MENU_CREATED_BY_ADMIN |
includes/ |
|
MENU_CALLBACK |
includes/ |
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/ |
Sub-Topics
Name | Location | Description |
---|---|---|
Menu tree parameters |
includes/ |
Parameters for a menu tree. |
Menu status codes |
includes/ |
Status codes for menu callbacks. |
Menu item types |
includes/ |
Definitions for various menu item types. |
Menu flags |
includes/ |
Flags for use in the "type" attribute of menu items. |