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.
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
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
Name | Location | Description |
|---|---|---|
| MENU_CALLBACK | includes/menu.inc | 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_CUSTOM_ITEM | includes/menu.inc | Custom items are those defined by the administrator. Reserved for internal use; do not return from hook_menu() implementations. |
| MENU_CUSTOM_MENU | includes/menu.inc | Custom menus are those defined by the administrator. Reserved for internal use; do not return from hook_menu() implementations. |
| MENU_DEFAULT_LOCAL_TASK | includes/menu.inc | Every set of local tasks should provide one "default" task, that links to the same path as its parent when clicked. |
| MENU_DYNAMIC_ITEM | includes/menu.inc | Dynamic menu items change frequently, and so should not be stored in the database for administrative customization. |
| MENU_ITEM_GROUPING | includes/menu.inc | 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_LOCAL_TASK | includes/menu.inc | 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_NORMAL_ITEM | includes/menu.inc | 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_SUGGESTED_ITEM | includes/menu.inc | 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. |
Functions
| Name | Location | Description |
|---|---|---|
| menu_execute_active_handler | includes/menu.inc | Execute the handler associated with the active menu item. |
| menu_get_active_breadcrumb | includes/menu.inc | Returns an array of rendered menu items in the active breadcrumb trail. |
| menu_get_active_help | includes/menu.inc | Returns the help associated with the active menu item. |
| menu_get_active_item | includes/menu.inc | Returns the ID of the active menu item. |
| menu_get_active_nontask_item | includes/menu.inc | 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/menu.inc | Returns the title of the active menu item. |
| menu_get_item | includes/menu.inc | Retrieves the menu item specified by $mid, or by $path if $mid is not given. |
| menu_get_local_tasks | includes/menu.inc | Return the local task tree. |
| menu_get_menu | includes/menu.inc | Return the menu data structure. |
| menu_get_root_menus | includes/menu.inc | Retrieves the menu ID and title of all root menus. |
| menu_in_active_trail | includes/menu.inc | Returns TRUE when the menu item is in the active trail. |
| menu_in_active_trail_in_submenu | includes/menu.inc | Returns TRUE when the menu item is in the active trail within a specific subsection of the menu tree. |
| menu_item_link | includes/menu.inc | Returns the rendered link to a menu item. |
| menu_primary_links | includes/menu.inc | Returns 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_tasks | includes/menu.inc | Returns the rendered HTML of the primary local tasks. |
| menu_rebuild | includes/menu.inc | Populate the database representation of the menu. |
| menu_secondary_links | includes/menu.inc | Returns 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_tasks | includes/menu.inc | Returns the rendered HTML of the secondary local tasks. |
| menu_set_active_item | includes/menu.inc | Sets the path of the active menu item. |
| menu_set_location | includes/menu.inc | Change the current menu location of the user. |
| menu_tree | includes/menu.inc | Returns a rendered menu tree. |
| theme_menu_item | includes/menu.inc | Generate the HTML output for a single menu item. |
| theme_menu_item_link | includes/menu.inc | Generate the HTML representing a given menu item ID. |
| theme_menu_links | includes/menu.inc | Returns 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_task | includes/menu.inc | Generate the HTML representing a given menu item ID as a tab. |
| theme_menu_local_tasks | includes/menu.inc | Returns the rendered local tasks. The default implementation renders them as tabs. |
| theme_menu_tree | includes/menu.inc | Generate the HTML for a menu tree. |