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 "callback arguments" attribute of its menu item. 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
| Name |
Location |
Description |
|---|---|---|
| menu_get_menu |
includes/ |
Return the menu data structure. |
| menu_get_local_tasks |
includes/ |
Return the local task tree. |
| menu_set_location |
includes/ |
Change the current menu location of the user. |
| menu_execute_active_handler |
includes/ |
Execute the handler associated with the active menu item. |
| menu_get_active_item |
includes/ |
Returns the ID of the active menu item. |
| menu_set_active_item |
includes/ |
Sets the path of the active menu item. |
| menu_get_active_nontask_item |
includes/ |
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_title |
includes/ |
Returns the title of the active menu item. |
| menu_get_active_help |
includes/ |
Returns the help associated with the active menu item. |
| menu_get_active_breadcrumb |
includes/ |
Returns an array of rendered menu items in the active breadcrumb trail. |
| menu_in_active_trail |
includes/ |
Returns true when the menu item is in the active trail. |
| menu_rebuild |
includes/ |
Populate the database representation of the menu. |
| theme_menu_tree |
includes/ |
Generate the HTML for a menu tree. |
| menu_tree |
includes/ |
Returns a rendered menu tree. |
| theme_menu_item |
includes/ |
Generate the HTML output for a single menu item. |
| theme_menu_item_link |
includes/ |
Generate the HTML representing a given menu item ID. |
| menu_item_link |
includes/ |
Returns the rendered link to a menu item. |
| theme_menu_local_tasks |
includes/ |
Returns the rendered local tasks. The default implementation renders them as tabs. |
| menu_primary_local_tasks |
includes/ |
Returns the rendered HTML of the primary local tasks. |
| menu_secondary_local_tasks |
includes/ |
Returns the rendered HTML of the secondary local tasks. |
| theme_menu_local_task |
includes/ |
Generate the HTML representing a given menu item ID as a tab. |
Constants
| Name |
Location |
Description |
|---|---|---|
| MENU_IS_ROOT |
includes/ |
@name Menu flags |
| MENU_VISIBLE_IN_TREE |
includes/ |
|
| MENU_VISIBLE_IN_TREE |
includes/ |
|
| MENU_VISIBLE_IN_BREADCRUMB |
includes/ |
|
| MENU_VISIBLE_IN_BREADCRUMB |
includes/ |
|
| MENU_VISIBLE_IF_HAS_CHILDREN |
includes/ |
|
| MENU_VISIBLE_IF_HAS_CHILDREN |
includes/ |
|
| MENU_MODIFIABLE_BY_ADMIN |
includes/ |
|
| MENU_MODIFIABLE_BY_ADMIN |
includes/ |
|
| MENU_MODIFIED_BY_ADMIN |
includes/ |
|
| MENU_MODIFIED_BY_ADMIN |
includes/ |
|
| MENU_CREATED_BY_ADMIN |
includes/ |
|
| MENU_CREATED_BY_ADMIN |
includes/ |
|
| MENU_IS_LOCAL_TASK |
includes/ |
|
| MENU_IS_LOCAL_TASK |
includes/ |
|
| MENU_EXPANDED |
includes/ |
|
| MENU_EXPANDED |
includes/ |
|
| MENU_LINKS_TO_PARENT |
includes/ |
|
| MENU_LINKS_TO_PARENT |
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_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_ITEM_GROUPING |
includes/ |
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/ |
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_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_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_DYNAMIC_ITEM |
includes/ |
Dynamic menu items change frequently, and so should not be stored in the database for administrative customization. |
| MENU_DYNAMIC_ITEM |
includes/ |
Dynamic menu items change frequently, and so should not be stored in the database for administrative customization. |
| 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. |
| 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. |
| 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_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_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_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_CUSTOM_ITEM |
includes/ |
Custom items are those defined by the administrator. Reserved for internal use; do not return from hook_menu() implementations. |
| MENU_CUSTOM_ITEM |
includes/ |
Custom items are those defined by the administrator. Reserved for internal use; do not return from hook_menu() implementations. |
| MENU_CUSTOM_MENU |
includes/ |
Custom menus are those defined by the administrator. Reserved for internal use; do not return from hook_menu() implementations. |
| MENU_CUSTOM_MENU |
includes/ |
Custom menus are those defined by the administrator. Reserved for internal use; do not return from hook_menu() implementations. |
| MENU_FOUND |
includes/ |
@name Menu status codes |
| MENU_NOT_FOUND |
includes/ |
|
| MENU_NOT_FOUND |
includes/ |
|
| MENU_ACCESS_DENIED |
includes/ |
|
| MENU_ACCESS_DENIED |
includes/ |
