1. 8.3.x core/lib/Drupal/Core/Menu/menu.api.php menu
  2. 8.0.x core/lib/Drupal/Core/Menu/menu.api.php menu
  3. 8.1.x core/lib/Drupal/Core/Menu/menu.api.php menu
  4. 8.2.x core/lib/Drupal/Core/Menu/menu.api.php menu
  5. 8.4.x core/lib/Drupal/Core/Menu/menu.api.php menu
  6. 4.6.x includes/menu.inc menu
  7. 4.7.x includes/menu.inc menu
  8. 5.x includes/menu.inc menu
  9. 6.x includes/menu.inc menu
  10. 7.x includes/menu.inc menu

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
  • 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

Namesort descending Location Description
drupal_help_arg includes/menu.inc Generates elements for the $arg array in the help hook.
menu_cache_clear includes/menu.inc Clears the cached cached data for a single named menu.
menu_cache_clear_all includes/menu.inc 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_execute_active_handler includes/menu.inc Execute the page callback associated with the current path
menu_get_active_breadcrumb includes/menu.inc Get the breadcrumb for the current page, as determined by the active trail.
menu_get_active_help includes/menu.inc Returns the help associated with the active menu item.
menu_get_active_menu_name includes/menu.inc Get the active menu for the current page - determines the active trail.
menu_get_active_title includes/menu.inc Get the title of the current page, as determined by the active trail.
menu_get_active_trail includes/menu.inc Gets the active trail (path to root menu root) of the current page.
menu_get_ancestors includes/menu.inc Returns the ancestors (and relevant placeholders) for any given path.
menu_get_item includes/menu.inc Get a router item.
menu_get_names includes/menu.inc Build a list of named menus.
menu_get_object includes/menu.inc Get a loaded object from a router item.
menu_link_children_relative_depth includes/menu.inc Find the depth of an item's children relative to its depth.
menu_link_delete includes/menu.inc Delete one or several menu links.
menu_link_load includes/menu.inc Get a menu link by its mlid, access checked and link translated for rendering.
menu_link_maintain includes/menu.inc Insert, update or delete an uncustomized menu link related to a module.
menu_link_save includes/menu.inc Save a menu link.
menu_list_system_menus includes/menu.inc Return an array containing the names of system-defined (default) menus.
menu_local_tasks includes/menu.inc Collects the local tasks (tabs) for a given level.
menu_navigation_links includes/menu.inc Return an array of links for a navigation menu.
menu_primary_links includes/menu.inc Return an array of links to be rendered as the Primary links.
menu_primary_local_tasks includes/menu.inc Returns the rendered local tasks at the top level.
menu_rebuild includes/menu.inc (Re)populate the database tables used by various menu functions.
menu_router_build includes/menu.inc Collect, alter and store the menu definitions.
menu_secondary_links includes/menu.inc Return an array of links to be rendered as the Secondary links.
menu_secondary_local_tasks includes/menu.inc Returns the rendered local tasks at the second level.
menu_set_active_item includes/menu.inc Set the active path, which determines which page is loaded.
menu_set_active_menu_name includes/menu.inc Set (or get) the active menu for the current page - determines the active trail.
menu_set_active_trail includes/menu.inc Sets or gets the active trail (path to root menu root) of the current page.
menu_set_item includes/menu.inc Replaces the statically cached item for a given path.
menu_tab_root_path includes/menu.inc Returns the router path, or the path of the parent tab of a default local task.
menu_tail_to_arg includes/menu.inc
menu_tree includes/menu.inc Render a menu tree based on the current path.
menu_tree_all_data includes/menu.inc Get the data structure representing a named menu tree.
menu_tree_check_access includes/menu.inc Check access and perform other dynamic operations for each link in the tree.
menu_tree_collect_node_links includes/menu.inc Recursive helper function - collect node links.
menu_tree_data includes/menu.inc Build the data representing a menu tree.
menu_tree_output includes/menu.inc Returns a rendered menu tree.
menu_tree_page_data includes/menu.inc Get the data structure representing a named menu tree, based on the current page.
menu_unserialize includes/menu.inc 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_valid_path includes/menu.inc Validates the path of a menu link being created or edited.
theme_menu_item includes/menu.inc Generate the HTML output for a menu item and submenu.
theme_menu_item_link includes/menu.inc Generate the HTML output for a single menu link.
theme_menu_local_task includes/menu.inc Generate the HTML output for a single local task link.
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 output for a menu tree
_menu_check_access includes/menu.inc Check access to a menu item using the access callback
_menu_clear_page_cache includes/menu.inc Helper function to clear the page and block caches at most twice per page load.
_menu_delete_item includes/menu.inc Helper function for menu_link_delete; deletes a single menu link.
_menu_find_router_path includes/menu.inc Find the router path which will serve this path.
_menu_item_localize includes/menu.inc Localize the router item title using t() or another callback.
_menu_link_build includes/menu.inc Builds a link from a router item.
_menu_link_map_translate includes/menu.inc 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_move_children includes/menu.inc Update the children of a menu link that's being moved.
_menu_link_parents_set includes/menu.inc Helper function that sets the p1..p9 values for a menu link being saved.
_menu_link_translate includes/menu.inc This function is similar to _menu_translate() but does link-specific preparation such as always calling to_arg functions.
_menu_load_objects includes/menu.inc Loads objects into the map as defined in the $item['load_functions'].
_menu_navigation_links_rebuild includes/menu.inc Helper function to build menu links for the items in the menu router.
_menu_router_build includes/menu.inc Helper function to build the router table based on the data from hook_menu.
_menu_router_cache includes/menu.inc Helper function to store the menu router if we have it in memory.
_menu_set_expanded_menus includes/menu.inc Helper function to update a list of menus with expanded items
_menu_site_is_offline includes/menu.inc Checks whether the site is off-line for maintenance.
_menu_translate includes/menu.inc Handles dynamic path translation and menu access control.
_menu_tree_check_access includes/menu.inc Recursive helper function for menu_tree_check_access()
_menu_tree_cid includes/menu.inc Helper function - compute the real cache ID for menu tree data.
_menu_tree_data includes/menu.inc Recursive helper function to build the data representing a menu tree.
_menu_update_parental_status includes/menu.inc Check and update the has_children status for the parent of a link.

Constants

Namesort descending Location Description
MENU_ACCESS_DENIED includes/menu.inc
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_CREATED_BY_ADMIN includes/menu.inc
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_FOUND includes/menu.inc
MENU_IS_LOCAL_TASK includes/menu.inc
MENU_IS_ROOT includes/menu.inc
MENU_LINKS_TO_PARENT includes/menu.inc
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_MAX_DEPTH includes/menu.inc The maximum depth of a menu links tree - matches the number of p columns.
MENU_MAX_PARTS includes/menu.inc The maximum number of path elements for a menu callback
MENU_MODIFIED_BY_ADMIN includes/menu.inc
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_NOT_FOUND includes/menu.inc
MENU_SITE_OFFLINE includes/menu.inc
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. Note for the value: 0x0010 was a flag which is no longer used, but this way the values…
MENU_VISIBLE_IN_BREADCRUMB includes/menu.inc
MENU_VISIBLE_IN_TREE includes/menu.inc

Sub-Topics

Namesort descending Location Description
Menu flags includes/menu.inc Flags for use in the "type" attribute of menu items.
Menu item types includes/menu.inc Definitions for various menu item types.
Menu status codes includes/menu.inc Status codes for menu callbacks.
Menu tree parameters includes/menu.inc Parameters for a menu tree.

Comments

goatvirus’s picture

this is mentioned on the hook_menu page (http://api.drupal.org/api/function/hook_menu/6) and should be mentioned here too:

"For comprehensive documentation on the menu system, see http://drupal.org/node/102338 ."

Peter Fisera
http://earthangelconsulting.com

sabrawy’s picture

i think we need new MENU Constants MENU_LOCAL_TASK_AFTER_OPENED

we need to assign MENU_LOCAL_TASK under conditions ,
for example it's taking us to write more code to just make some URLS
relative

if i have a module and i can add somthing in my database so the main page will be a table getting my data in it and i also i can add MENU_LOCAL_TASK to the add form

but the Edit or delete or event more complix function like configering this data with others with his relation

i want to add those as MENU_LOCAL_TASK but only if i opened the page because i'm making that page like Using %

$items['admin/build/mymodule/%/edit'] = array(								   
	'title'=> t('Edit item'),
	'description'=>t('testing'),
	'page callback'=> 'mymodule_admin_edit',
	'page arguments'=> array(3),
	'access callback'=> 'user_access',
	'access arguments'=>array('administer site configuration'),
	'type' =>MENU_CALLBACK,
	
);

so i just want after opening the edit item i can see the main list tap and add tap and edit tap took my dynamic link.

i couldn't achieve that with any MENU Constants .

Thanks

sabrawy’s picture

Sorry guys i didn't know we can do it with making our own access callback function it will make us define the menu as menu_local_task and only make it visible when out access callback function conditions are TRUE.

AndrewBoag’s picture

shouldn't menu_get_menus() be here as well?

AndrewBoag’s picture

and menu_parent_options()

djg_tram’s picture

I really don't know where to put this in the documentation but it seems to be a recurring topic: how to create a two-level tab structure. It is a bit convoluted but not as bad as it sounds. I have a boilerplate code:

$items['admin/base'] = array(
  'title' => 'Base',
  'page arguments' => array('tab1_subtab1'),
);

$items['admin/base/tab1'] = array(
  'title' => 'Tab 1',
  'type' => MENU_DEFAULT_LOCAL_TASK,
  'page arguments' => array('tab1_subtab1'),
  'weight' => 0,
);
$items['admin/base/tab1/subtab1'] = array(
  'title' => 'Subtab 1',
  'type' => MENU_DEFAULT_LOCAL_TASK,
  'page arguments' => array('tab1_subtab1'),
);
$items['admin/base/tab1/subtab1'] = array(
  'title' => 'Subtab 1',
  'type' => MENU_LOCAL_TASK,
  'page arguments' => array('tab1_subtab1'),
  'weight' => 0,
);
$items['admin/base/tab1/subtab2'] = array(
  'title' => 'Subtab 2',
  'type' => MENU_LOCAL_TASK,
  'page arguments' => array('tab1_subtab2'),
  'weight' => 1,
);

$items['admin/base/tab2'] = array(
  'title' => 'Tab 2',
  'type' => MENU_LOCAL_TASK,
  'page arguments' => array('tab2_subtab1'),
  'weight' => 1,
);
$items['admin/base/tab2/subtab1'] = array(
  'title' => 'Subtab 1',
  'type' => MENU_DEFAULT_LOCAL_TASK,
  'page arguments' => array('tab2_subtab1'),
);
$items['admin/base/tab2/subtab1'] = array(
  'title' => 'Subtab 1',
  'type' => MENU_LOCAL_TASK,
  'page arguments' => array('tab2_subtab1'),
  'weight' => 0,
);
$items['admin/base/tab2/subtab2'] = array(
  'title' => 'Subtab 2',
  'type' => MENU_LOCAL_TASK,
  'page arguments' => array('tab2_subtab2'),
  'weight' => 1,
);

$items['admin/base/tab3'] = array(
  'title' => 'Tab 3',
  'type' => MENU_LOCAL_TASK,
  'page arguments' => array('tab3_subtab1'),
  'weight' => 2,
);
$items['admin/base/tab3/subtab1'] = array(
  'title' => 'Subtab 1',
  'type' => MENU_DEFAULT_LOCAL_TASK,
  'page arguments' => array('tab3_subtab1'),
);
$items['admin/base/tab3/subtab1'] = array(
  'title' => 'Subtab 1',
  'type' => MENU_LOCAL_TASK,
  'page arguments' => array('tab3_subtab1'),
  'weight' => 0,
);
$items['admin/base/tab3/subtab2'] = array(
  'title' => 'Subtab 2',
  'type' => MENU_LOCAL_TASK,
  'page arguments' => array('tab3_subtab2'),
  'weight' => 1,
);

Not that the code has been stripped down, it is not functional as it is. Page and access callbacks, possible file references are missing. The intention was to show the structure, without too many details. Just add them and it will work all right.

Basically, the structure is very simple. All you have to note are two things: first, for each level, you need both a MENU_DEFAULT_LOCAL_TASK and a MENU_LOCAL_TASK pointing to the same first subtab (the first item will be used when the user lands on that tab, the second when it clicks on the tab). The second: while the first primary tab will be a MENU_DEFAULT_LOCAL_TASK, all subsequent primary tabs are only MENU_LOCAL_TASK. That's all there is to it, really.