Drupal的组成部分 3.菜单系统

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 ofhook_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. 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().

Constants

名称	位置	描述
MENU_ACCESS_DENIED	includes/menu.inc	Internal menu status code -- Menu item access is denied.
MENU_CALLBACK	includes/menu.inc	Menu type -- A hidden, internal callback, typically used for API calls.
MENU_CREATED_BY_ADMIN	includes/menu.inc	Internal menu flag -- menu item was created by administrator.
MENU_DEFAULT_LOCAL_TASK	includes/menu.inc	Menu type -- The "default" local task, which is initially active.
MENU_FOUND	includes/menu.inc	Internal menu status code -- Menu item was found.
MENU_IS_LOCAL_TASK	includes/menu.inc	Internal menu flag -- menu item is a local task.
MENU_IS_ROOT	includes/menu.inc	Internal menu flag -- menu item is the root of the menu tree.
MENU_LINKS_TO_PARENT	includes/menu.inc	Internal menu flag -- menu item links back to its parnet.
MENU_LOCAL_TASK	includes/menu.inc	Menu type -- A task specific to the parent item, usually rendered as a tab.
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	Internal menu flag -- menu item can be modified by administrator.
MENU_NORMAL_ITEM	includes/menu.inc	Menu type -- A "normal" menu item that's shown in menu and breadcrumbs.
MENU_NOT_FOUND	includes/menu.inc	Internal menu status code -- Menu item was not found.
MENU_SITE_OFFLINE	includes/menu.inc	Internal menu status code -- Menu item inaccessible because site is offline.
MENU_SUGGESTED_ITEM	includes/menu.inc	Menu type -- A normal menu item, hidden until enabled by an administrator.
MENU_VISIBLE_IN_BREADCRUMB	includes/menu.inc	Internal menu flag -- menu item is visible in the breadcrumb.
MENU_VISIBLE_IN_TREE	includes/menu.inc	Internal menu flag -- menu item is visible in the menu tree.

函数

名称	位置	描述
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	Get the active trail for the current page - the path to root in the menu tree.
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_main_menu	includes/menu.inc	Return an array of links to be rendered as the Main menu.
menu_navigation_links	includes/menu.inc	Return an array of links for a navigation menu.
menu_path_is_external	includes/menu.inc	Returns TRUE if a path is external (e.g. http://example.com).
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_local_tasks	includes/menu.inc	Returns the rendered local tasks at the second level.
menu_secondary_menu	includes/menu.inc	Return an array of links to be rendered as the Secondary links.
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	Set (or get) the active trail for the current page - the path to root in the menu tree.
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_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_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 offline 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 formenu_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.