Functions | |
| menu_get_ancestors ($parts) | |
| menu_unserialize ($data, $map) | |
| menu_set_item ($path, $router_item) | |
| menu_get_item ($path=NULL, $router_item=NULL) | |
| menu_execute_active_handler ($path=NULL) | |
| _menu_load_objects (&$item, &$map) | |
| _menu_check_access (&$item, $map) | |
| _menu_item_localize (&$item, $map, $link_translate=FALSE) | |
| _menu_translate (&$router_item, $map, $to_arg=FALSE) | |
| _menu_link_map_translate (&$map, $to_arg_functions) | |
| menu_tail_to_arg ($arg, $map, $index) | |
| _menu_link_translate (&$item) | |
| menu_get_object ($type= 'node', $position=1, $path=NULL) | |
| menu_tree ($menu_name= 'navigation') | |
| menu_tree_output ($tree) | |
| menu_tree_all_data ($menu_name= 'navigation', $item=NULL) | |
| menu_tree_page_data ($menu_name= 'navigation') | |
| _menu_tree_cid ($menu_name, $data) | |
| menu_tree_collect_node_links (&$tree, &$node_links) | |
| menu_tree_check_access (&$tree, $node_links=array()) | |
| _menu_tree_check_access (&$tree) | |
| menu_tree_data ($result=NULL, $parents=array(), $depth=1) | |
| _menu_tree_data ($result, $parents, $depth, $previous_element= '') | |
| drupal_help_arg ($arg=array()) | |
| menu_get_active_help () | |
| menu_get_names ($reset=FALSE) | |
| menu_list_system_menus () | |
| menu_primary_links () | |
| menu_secondary_links () | |
| menu_navigation_links ($menu_name, $level=0) | |
| menu_local_tasks ($level=0, $return_root=FALSE) | |
| menu_primary_local_tasks () | |
| menu_secondary_local_tasks () | |
| menu_tab_root_path () | |
| menu_set_active_menu_name ($menu_name=NULL) | |
| menu_get_active_menu_name () | |
| menu_set_active_item ($path) | |
| menu_set_active_trail ($new_trail=NULL) | |
| menu_get_active_trail () | |
| menu_get_active_breadcrumb () | |
| menu_get_active_title () | |
| menu_link_load ($mlid) | |
| menu_cache_clear ($menu_name= 'navigation') | |
| menu_cache_clear_all () | |
| menu_rebuild () | |
| menu_router_build ($reset=FALSE) | |
| _menu_router_cache ($new_menu=NULL) | |
| _menu_link_build ($item) | |
| _menu_navigation_links_rebuild ($menu) | |
| menu_link_delete ($mlid, $path=NULL) | |
| _menu_delete_item ($item, $force=FALSE) | |
| menu_link_save (&$item) | |
| _menu_clear_page_cache () | |
| _menu_set_expanded_menus () | |
| _menu_find_router_path ($link_path) | |
| menu_link_maintain ($module, $op, $link_path, $link_title) | |
| menu_link_children_relative_depth ($item) | |
| _menu_link_move_children ($item, $existing_item) | |
| _menu_update_parental_status ($item, $exclude=FALSE) | |
| _menu_link_parents_set (&$item, $parent) | |
| _menu_router_build ($callbacks) | |
| menu_path_is_external ($path) | |
| _menu_site_is_offline () | |
| menu_valid_path ($form_item) | |
Menu flags | |
| Flags for use in the "type" attribute of menu items. | |
| enum | MENU_IS_ROOT |
| enum | MENU_VISIBLE_IN_TREE |
| enum | MENU_VISIBLE_IN_BREADCRUMB |
| enum | MENU_LINKS_TO_PARENT |
| enum | MENU_MODIFIED_BY_ADMIN |
| enum | MENU_CREATED_BY_ADMIN |
| enum | MENU_IS_LOCAL_TASK |
Menu item types | |
| End of "Menu flags".
Menu item definitions provide one of these constants, which are shortcuts for combinations of the above flags. | |
| enum | MENU_NORMAL_ITEM |
| enum | MENU_CALLBACK |
| enum | MENU_SUGGESTED_ITEM |
| enum | MENU_LOCAL_TASK |
| enum | MENU_DEFAULT_LOCAL_TASK |
Menu status codes | |
| End of "Menu item types".
Status codes for menu callbacks. | |
| enum | MENU_FOUND |
| enum | MENU_NOT_FOUND |
| enum | MENU_ACCESS_DENIED |
| enum | MENU_SITE_OFFLINE |
| enum | MENU_MAX_PARTS |
| enum | MENU_MAX_DEPTH |
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:
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. 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.
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().
| enum MENU_CALLBACK |
Callbacks simply register a path so that the correct function is fired when the URL is accessed. They are not shown in the menu.
Every set of local tasks should provide one "default" task, that links to the same path as its parent when clicked.
| enum MENU_LOCAL_TASK |
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".
| enum MENU_MAX_DEPTH |
The maximum depth of a menu links tree - matches the number of p columns.
| enum MENU_MAX_PARTS |
End of "Menu status codes". Menu tree parameters
Menu tree The maximum number of path elements for a menu callback
| enum MENU_NORMAL_ITEM |
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.
| enum MENU_SUGGESTED_ITEM |
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 of MENU_CALLBACK and MENU_SUGGESTED_ITEM are separate.
| _menu_check_access | ( | &$ | item, | |
| $ | map | |||
| ) |
Check access to a menu item using the access callback
| $item | A menu router or menu link item | |
| $map | An array of path arguments (ex: array('node', '5')) |
| _menu_clear_page_cache | ( | ) |
Helper function to clear the page and block caches at most twice per page load.
| _menu_delete_item | ( | $ | item, | |
| $ | force = FALSE | |||
| ) |
Helper function for menu_link_delete; deletes a single menu link.
| $item | Item to be deleted. | |
| $force | Forces deletion. Internal use only, setting to TRUE is discouraged. |
| _menu_find_router_path | ( | $ | link_path | ) |
Find the router path which will serve this path.
| $link_path | The path for we are looking up its router path. |
| _menu_item_localize | ( | &$ | item, | |
| $ | map, | |||
| $ | link_translate = FALSE | |||
| ) |
Localize the router item title using t() or another callback.
Translate the title and description to allow storage of English title strings in the database, yet display of them in the language required by the current user.
| $item | A menu router item or a menu link item. | |
| $map | The path as an array with objects already replaced. E.g., for path node/123 $map would be array('node', $node) where $node is the node object for node 123. | |
| $link_translate | TRUE if we are translating a menu link item; FALSE if we are translating a menu router item. |
| _menu_link_build | ( | $ | item | ) |
Builds a link from a router item.
| _menu_link_map_translate | ( | &$ | map, | |
| $ | to_arg_functions | |||
| ) |
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.
| map | An array of path arguments (ex: array('node', '5')) | |
| $to_arg_functions | An array of helper function (ex: array(2 => 'menu_tail_to_arg')) |
| _menu_link_move_children | ( | $ | item, | |
| $ | existing_item | |||
| ) |
Update the children of a menu link that's being moved.
The menu name, parents (p1 - p6), and depth are updated for all children of the link, and the has_children status of the previous parent is updated.
| _menu_link_parents_set | ( | &$ | item, | |
| $ | parent | |||
| ) |
Helper function that sets the p1..p9 values for a menu link being saved.
| _menu_link_translate | ( | &$ | item | ) |
This function is similar to _menu_translate() but does link-specific preparation such as always calling to_arg functions.
| $item | A menu link |
| _menu_load_objects | ( | &$ | item, | |
| &$ | map | |||
| ) |
Loads objects into the map as defined in the $item['load_functions'].
| $item | A menu router or menu link item | |
| $map | An array of path arguments (ex: array('node', '5')) |
| _menu_navigation_links_rebuild | ( | $ | menu | ) |
Helper function to build menu links for the items in the menu router.
| _menu_router_build | ( | $ | callbacks | ) |
Helper function to build the router table based on the data from hook_menu.
| _menu_router_cache | ( | $ | new_menu = NULL |
) |
Helper function to store the menu router if we have it in memory.
| _menu_set_expanded_menus | ( | ) |
Helper function to update a list of menus with expanded items
| _menu_site_is_offline | ( | ) |
Checks whether the site is off-line for maintenance.
This function will log the current user out and redirect to front page if the current user has no 'administer site configuration' permission.
| _menu_translate | ( | &$ | router_item, | |
| $ | map, | |||
| $ | to_arg = FALSE | |||
| ) |
Handles dynamic path translation and menu access control.
When a user arrives on a page such as node/5, this function determines what "5" corresponds to, by inspecting the page's menu path definition, node/node. This will call node_load(5) to load the corresponding node object.
It also works in reverse, to allow the display of tabs and menu items which contain these dynamic arguments, translating node/node to node/5.
Translation of menu item titles and descriptions are done here to allow for storage of English strings in the database, and translation to the language required to generate the current page
| $router_item | A menu router item | |
| $map | An array of path arguments (ex: array('node', '5')) | |
| $to_arg | Execute $item['to_arg_functions'] or not. Use only if you want to render a path from the menu table, for example tabs. |
| _menu_tree_check_access | ( | &$ | tree | ) |
Recursive helper function for menu_tree_check_access()
| _menu_tree_cid | ( | $ | menu_name, | |
| $ | data | |||
| ) |
Helper function - compute the real cache ID for menu tree data.
| _menu_tree_data | ( | $ | result, | |
| $ | parents, | |||
| $ | depth, | |||
| $ | previous_element = '' | |||
| ) |
Recursive helper function to build the data representing a menu tree.
The function is a bit complex because the rendering of an item depends on the next menu item. So we are always rendering the element previously processed not the current one.
| _menu_update_parental_status | ( | $ | item, | |
| $ | exclude = FALSE | |||
| ) |
Check and update the has_children status for the parent of a link.
| drupal_help_arg | ( | $ | arg = array() |
) |
Generates elements for the $arg array in the help hook.
| menu_cache_clear | ( | $ | menu_name = 'navigation' |
) |
Clears the cached cached data for a single named menu.
| menu_cache_clear_all | ( | ) |
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 | ( | $ | path = NULL |
) |
Execute the page callback associated with the current path
| menu_get_active_breadcrumb | ( | ) |
Get the breadcrumb for the current page, as determined by the active trail.
| menu_get_active_help | ( | ) |
Returns the help associated with the active menu item.
| menu_get_active_menu_name | ( | ) |
Get the active menu for the current page - determines the active trail.
| menu_get_active_title | ( | ) |
Get the title of the current page, as determined by the active trail.
| menu_get_active_trail | ( | ) |
Get the active trail for the current page - the path to root in the menu tree.
| menu_get_ancestors | ( | $ | parts | ) |
End of "Menu tree parameters". Returns the ancestors (and relevant placeholders) for any given path.
For example, the ancestors of node/12345/edit are:
To generate these, we will use binary numbers. Each bit represents a part of the path. If the bit is 1, then it represents the original value while 0 means wildcard. If the path is node/12/edit/foo then the 1011 bitstring represents node//edit/foo where % means that any argument matches that part. We limit ourselves to using binary numbers that correspond the patterns of wildcards of router items that actually exists. This list of 'masks' is built in menu_rebuild().
| $parts | An array of path parts, for the above example array('node', '12345', 'edit'). |
| menu_get_item | ( | $ | path = NULL, |
|
| $ | router_item = NULL | |||
| ) |
Get a router item.
| $path | The path, for example node/5. The function will find the corresponding node/% item and return that. | |
| $router_item | Internal use only. |
| menu_get_names | ( | $ | reset = FALSE |
) |
Build a list of named menus.
| menu_get_object | ( | $ | type = 'node', |
|
| $ | position = 1, |
|||
| $ | path = NULL | |||
| ) |
Get a loaded object from a router item.
menu_get_object() will provide you the current node on paths like node/5, node/5/revisions/48 etc. menu_get_object('user') will give you the user account on user/5 etc. Note - this function should never be called within a _to_arg function (like user_current_to_arg()) since this may result in an infinite recursion.
| $type | Type of the object. These appear in hook_menu definitons as type. Core provides aggregator_feed, aggregator_category, contact, filter_format, forum_term, menu, menu_link, node, taxonomy_vocabulary, user. See the relevant {$type}_load function for more on each. Defaults to node. | |
| $position | The expected position for $type object. For node/node this is 1, for comment/reply/node this is 2. Defaults to 1. | |
| $path | See menu_get_item() for more on this. Defaults to the current path. |
| menu_link_children_relative_depth | ( | $ | item | ) |
Find the depth of an item's children relative to its depth.
For example, if the item has a depth of 2, and the maximum of any child in the menu link tree is 5, the relative depth is 3.
| $item | An array representing a menu link item. |
| menu_link_delete | ( | $ | mlid, | |
| $ | path = NULL | |||
| ) |
Delete one or several menu links.
| $mlid | A valid menu link mlid or NULL. If NULL, $path is used. | |
| $path | The path to the menu items to be deleted. $mlid must be NULL. |
| menu_link_load | ( | $ | mlid | ) |
Get a menu link by its mlid, access checked and link translated for rendering.
This function should never be called from within node_load() or any other function used as a menu object load function since an infinite recursion may occur.
| $mlid | The mlid of the menu item. |
| menu_link_maintain | ( | $ | module, | |
| $ | op, | |||
| $ | link_path, | |||
| $ | link_title | |||
| ) |
Insert, update or delete an uncustomized menu link related to a module.
| $module | The name of the module. | |
| $op | Operation to perform: insert, update or delete. | |
| $link_path | The path this link points to. | |
| $link_title | Title of the link to insert or new title to update the link to. Unused for delete. |
| menu_link_save | ( | &$ | item | ) |
Save a menu link.
| $item | An array representing a menu link item. The only mandatory keys are link_path and link_title. Possible keys are:
|
| menu_list_system_menus | ( | ) |
Return an array containing the names of system-defined (default) menus.
| menu_local_tasks | ( | $ | level = 0, |
|
| $ | return_root = FALSE | |||
| ) |
Collects the local tasks (tabs) for a given level.
| $level | The level of tasks you ask for. Primary tasks are 0, secondary are 1. | |
| $return_root | Whether to return the root path for the current page. |
| menu_navigation_links | ( | $ | menu_name, | |
| $ | level = 0 | |||
| ) |
Return an array of links for a navigation menu.
| $menu_name | The name of the menu. | |
| $level | Optional, the depth of the menu to be returned. |
| menu_path_is_external | ( | $ | path | ) |
Returns TRUE if a path is external (e.g. http://example.com).
| menu_primary_links | ( | ) |
Return an array of links to be rendered as the Primary links.
| menu_primary_local_tasks | ( | ) |
Returns the rendered local tasks at the top level.
| menu_rebuild | ( | ) |
(Re)populate the database tables used by various menu functions.
This function will clear and populate the {menu_router} table, add entries to {menu_links} for new router items, then remove stale items from {menu_links}. If called from update.php or install.php, it will also schedule a call to itself on the first real page load from menu_execute_active_handler(), because the maintenance page environment is different and leaves stale data in the menu tables.
| menu_router_build | ( | $ | reset = FALSE |
) |
Collect, alter and store the menu definitions.
| menu_secondary_links | ( | ) |
Return an array of links to be rendered as the Secondary links.
| menu_secondary_local_tasks | ( | ) |
Returns the rendered local tasks at the second level.
| menu_set_active_item | ( | $ | path | ) |
Set the active path, which determines which page is loaded.
| $path | A Drupal path - not a path alias. |
| menu_set_active_menu_name | ( | $ | menu_name = NULL |
) |
Set (or get) the active menu for the current page - determines the active trail.
| menu_set_active_trail | ( | $ | new_trail = NULL |
) |
Set (or get) the active trail for the current page - the path to root in the menu tree.
| menu_set_item | ( | $ | path, | |
| $ | router_item | |||
| ) |
Replaces the statically cached item for a given path.
| $path | The path. | |
| $router_item | The router item. Usually you take a router entry from menu_get_item and set it back either modified or to a different path. This lets you modify the navigation block, the page title, the breadcrumb and the page help in one call. |
| menu_tab_root_path | ( | ) |
Returns the router path, or the path of the parent tab of a default local task.
| menu_tree | ( | $ | menu_name = 'navigation' |
) |
Render a menu tree based on the current path.
The tree is expanded based on the current path and dynamic paths are also changed according to the defined to_arg functions (for example the 'My account' link is changed from user/% to a link with the current user's uid).
| $menu_name | The name of the menu. |
| menu_tree_all_data | ( | $ | menu_name = 'navigation', |
|
| $ | item = NULL | |||
| ) |
Get the data structure representing a named menu tree.
Since this can be the full tree including hidden items, the data returned may be used for generating an an admin interface or a select.
| $menu_name | The named menu links to return | |
| $item | A fully loaded menu link, or NULL. If a link is supplied, only the path to root will be included in the returned tree- as if this link represented the current page in a visible menu. |
| menu_tree_check_access | ( | &$ | tree, | |
| $ | node_links = array() | |||
| ) |
Check access and perform other dynamic operations for each link in the tree.
| $tree | The menu tree you wish to operate on. | |
| $node_links | A collection of node link references generated from $tree by menu_tree_collect_node_links(). |
| menu_tree_collect_node_links | ( | &$ | tree, | |
| &$ | node_links | |||
| ) |
Recursive helper function - collect node links.
| $tree | The menu tree you wish to collect node links from. | |
| $node_links | An array in which to store the collected node links. |
| menu_tree_data | ( | $ | result = NULL, |
|
| $ | parents = array(), |
|||
| $ | depth = 1 | |||
| ) |
Build the data representing a menu tree.
| $result | The database result. | |
| $parents | An array of the plid values that represent the path from the current page to the root of the menu tree. | |
| $depth | The depth of the current menu tree. |
| menu_tree_output | ( | $ | tree | ) |
Returns a rendered menu tree.
| $tree | A data structure representing the tree as returned from menu_tree_data. |
| menu_tree_page_data | ( | $ | menu_name = 'navigation' |
) |
Get the data structure representing a named menu tree, based on the current page.
The tree order is maintained by storing each parent in an individual field, see http://drupal.org/node/141866 for more.
| $menu_name | The named menu links to return |
| menu_unserialize | ( | $ | data, | |
| $ | map | |||
| ) |
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.
Integer values are mapped according to the $map parameter. For example, if unserialize($data) is array('view', 1) and $map is array('node', '12345') then 'view' will not be changed because it is not an integer, but 1 will as it is an integer. As $map[1] is '12345', 1 will be replaced with '12345'. So the result will be array('node_load', '12345').
| @data | A serialized array. | |
| @map | An array of potential replacements. |
| menu_valid_path | ( | $ | form_item | ) |
Validates the path of a menu link being created or edited.