Home       Trees       Indices       Help   
Package base :: Package includes :: Module menu
[hide private]

Module menu

source code

API for the Drupal menu system.
See Also:
Drupy Homepage, Drupal Homepage
Notes:

Author: Brendon Crawford

Copyright: 2008 Brendon Crawford

Contact: message144 at users dot sourceforge dot net

Version: 0.1

Functions [hide private]
 
get_ancestors(parts)
Returns the ancestors (and relevant placeholders) for any given path.		 source code
 
unserialize(data, map)
The menu system uses serialized arrays stored in the database for arguments.		 source code
 
set_item(path, router_item)
Replaces the statically cached item for a given path.		 source code
 
get_item(path=None, router_item=None)
Get a router item.		 source code
 
execute_active_handler(path=None)
Execute the page callback associated with the current path		 source code
 
_load_objects(item, map_)
Loads objects into the map as defined in the item['load_functions'].		 source code
 
_check_access(item, map_)
Check access to a menu item using the access callback		 source code
 
_item_localize(item, map_, link_translate=False)
Localize the router item title using t() or another callback.		 source code
 
_translate(router_item, map_, to_arg=False)
Handles dynamic path translation and menu access control.		 source code
 
_link_map_translate(map_, to_arg_functions)
This function translates the path elements in the map using any to_arg helper function.		 source code
 
tail_to_arg(arg, map_, index) source code
 
_link_translate(item)
This function is similar to menu_translate_() but does link-specific...		 source code
 
get_object(type_='node', position=1, path=None)
Get a loaded object from a router item.		 source code
 
tree(menu_name='navigation')
Render a menu tree based on the current path.		 source code
 
tree_output(tree)
Returns a rendered menu tree.		 source code
 
tree_all_data(menu_name='navigation', item=None)
Get the data structure representing a named menu tree.		 source code
 
tree_page_data(menu_name='navigation')
Get the data structure representing a named menu tree, based on the current page.		 source code
 
_tree_cid(menu_name, data)
Helper function - compute the real cache ID for menu tree data.		 source code
 
tree_collect_node_links(tree, node_links)
Recursive helper function - collect node links.		 source code
 
tree_check_access(tree, node_links={})
Check access and perform other dynamic operations for each link in the tree.		 source code
 
_tree_check_access(tree)
Recursive helper function for menu_tree_check_access()		 source code
 
tree_data(result=None, parents={}, depth=1)
Build the data representing a menu tree.		 source code
 
_tree_data(result, parents, depth, previous_element='')
Recursive helper function to build the data representing a menu tree.		 source code
 
theme_menu_item_link(link)
Generate the HTML output for a single menu link.		 source code
 
theme_menu_tree(tree)
Generate the HTML output for a menu tree		 source code
 
theme_menu_item(link, has_children, menu='', in_active_trail=False, extra_class=None)
Generate the HTML output for a menu item and submenu.		 source code
 
theme_menu_local_task(link, active=False)
Generate the HTML output for a single local task link.		 source code
 
drupal_help_arg(arg=[])
Generates elements for the arg array in the help hook.		 source code
 
get_active_help()
Returns the help associated with the active menu item.		 source code
 
get_names(reset=False)
Build a list of named menus.		 source code
 
list_system_menus()
Return an array containing the names of system-defined (default) menus.		 source code
 
main_menu()
Return an array of links to be rendered as the Main menu.		 source code
 
secondary_menu()
Return an array of links to be rendered as the Secondary links.		 source code
 
navigation_links(menu_name, level=0)
Return an array of links for a navigation menu.		 source code
 
local_tasks(level=0, return_root=False)
Collects the local tasks (tabs) for a given level.		 source code
 
primary_local_tasks()
Returns the rendered local tasks at the top level.		 source code
 
secondary_local_tasks()
Returns the rendered local tasks at the second level.		 source code
 
tab_root_path()
Returns the router path, or the path of the parent tab of a default local task.		 source code
 
theme_menu_local_tasks()
Returns the rendered local tasks.		 source code
 
set_active_menu_name(menu_name=None)
Set (or get) the active menu for the current page - determines the active trail.		 source code
 
get_active_menu_name()
Get the active menu for the current page - determines the active trail.		 source code
 
set_active_item(path)
Set the active path, which determines which page is loaded.		 source code
 
set_active_trail(new_trail=None)
Set (or get) the active trail for the current page - the path to root in the menu tree.		 source code
 
get_active_trail()
Get the active trail for the current page - the path to root in the menu tree.		 source code
 
get_active_breadcrumb()
Get the breadcrumb for the current page, as determined by the active trail.		 source code
 
get_active_title()
Get the title of the current page, as determined by the active trail.		 source code
 
link_load(mlid)
Get a menu link by its mlid, access checked and link translated for rendering.		 source code
 
cache_clear(menu_name='navigation')
Clears the cached cached data for a single named menu.		 source code
 
cache_clear_all()
Clears all cached menu data.		 source code
 
rebuild()
(Re)populate the database tables used by various menu functions.		 source code
 
router_build(reset=False)
Collect, alter and store the menu definitions.		 source code
 
_link_build(item)
Builds a link from a router item.		 source code
 
_navigation_links_rebuild(menu)
Helper function to build menu links for the items in the menu router.		 source code
 
link_delete(mlid, path=None)
Delete one or several menu links.		 source code
 
_delete_item(item, force=False)
Helper function for menu_link_delete; deletes a single menu link.		 source code
 
link_save(item)
Save a menu link.		 source code
 
_clear_page_cache()
Helper function to clear the page and block caches at most twice per page load.		 source code
 
_set_expanded_menus()
Helper function to update a list of menus with expanded items		 source code
 
_find_router_path(menu, link_path)
Find the router path which will serve this path.		 source code
 
link_maintain(plugin, op, link_path, link_title)
Insert, update or delete an uncustomized menu link related to a plugin.		 source code
 
link_children_relative_depth(item)
Find the depth of an item's children relative to its depth.		 source code
 
_link_move_children(item, existing_item)
Update the children of a menu link that's being moved.		 source code
 
_update_parental_status(item, exclude=False)
Check and update the has_children status for the parent of a link.		 source code
 
_link_parents_set(item, parent)
Helper function that sets the p1..p9 values for a menu link being saved.		 source code
 
_router_build(callbacks)
Helper function to build the router table based on the data from hook_menu.		 source code
 
path_is_external(path) source code
 
_site_is_offline()
Checks whether the site is off-line for maintenance.		 source code
 
valid_path(form_item)
Validates the path of a menu link being created or edited.		 source code
Variables [hide private]
  __version__ = '$Revision: 1 $'
  MENU_IS_ROOT = 1
  MENU_VISIBLE_IN_TREE = 2
  MENU_VISIBLE_IN_BREADCRUMB = 4
  MENU_LINKS_TO_PARENT = 8
  MENU_MODIFIED_BY_ADMIN = 32
  MENU_CREATED_BY_ADMIN = 64
  MENU_IS_LOCAL_TASK = 128
  MENU_NORMAL_ITEM = 6
  MENU_CALLBACK = 4
  MENU_SUGGESTED_ITEM = 20
  MENU_LOCAL_TASK = 128
  MENU_DEFAULT_LOCAL_TASK = 136
  MENU_FOUND = 1
  MENU_NOT_FOUND = 2
  MENU_ACCESS_DENIED = 3
  MENU_SITE_OFFLINE = 4
  MENU_MAX_PARTS = 7
  MENU_MAX_DEPTH = 9
Function Details [hide private]

get_ancestors(parts)

source code 
@ End of "Menu tree parameters". Returns the ancestors (and relevant placeholders) for any given path. For example, the ancestors of node/12345/edit are: - node/12345/edit - node/12345/% - node/%/edit - node/%/% - node/12345 - node/% - node 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().
Parameters:
  • parts - An array of path parts, for the above example array('node', '12345', 'edit').
Returns:
An array which contains the ancestors and placeholders. Placeholder simply contain as many '%s' as the ancestors.

unserialize(data, map)

source code 
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 php.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').
Parameters:
  • @data - A serialized array.
  • @map - An array of potential replacements.
Returns:
The data array unserialized and mapped.

set_item(path, router_item)

source code 
Replaces the statically cached item for a given path.
Parameters:
  • 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.

get_item(path=None, router_item=None)

source code 
Get a router item.
Parameters:
  • path - The path, for example node/5. The function will find the corresponding node/% item and return that.
  • router_item - Internal use only.
Returns:
The router item, an associate array corresponding to one row in the menu_router table. The value of key map holds the loaded objects. The value of key access is True if the current user can access this page. The values for key title, page_arguments, access_arguments will be filled in based on the database values and the objects loaded.

_load_objects(item, map_)

source code 
Loads objects into the map as defined in the item['load_functions'].
Parameters:
  • item - A menu router or menu link item
  • map - An array of path arguments (ex: array('node', '5'))
Returns:
Returns True for success, False if an object cannot be loaded. Names of object loading functions are placed in item['load_functions']. Loaded objects are placed in map[]; keys are the same as keys in the item['load_functions'] array. item['access'] is set to False if an object cannot be loaded.

_check_access(item, map_)

source code 
Check access to a menu item using the access callback
Parameters:
  • item - A menu router or menu link item
  • map - An array of path arguments (ex: array('node', '5'))
Returns:
item['access'] becomes True if the item is accessible, False otherwise.

_item_localize(item, map_, link_translate=False)

source code 
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.
Parameters:
  • 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.
Returns:
No return value. item['title'] is localized according to item['title_callback']. If an item's callback is check_plain(), item['options']['html'] becomes True. item['description'] is translated using t(). When doing link translation and the item['options']['attributes']['title'] (link title attribute) matches the description, it is translated as well.

_translate(router_item, map_, to_arg=False)

source code 
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
Parameters:
  • 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.
Returns:
Returns the map with objects loaded as defined in the item['load_functions. item['access'] becomes True if the item is accessible, False otherwise. item['href'] is set according to the map. If an error occurs during calling the load_functions (like trying to load a non existing node) then this function return False.

_link_map_translate(map_, to_arg_functions)

source code 
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.
Parameters:
  • 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'))

_link_translate(item)

source code 
This function is similar to menu_translate_() but does link-specific preparation such as always calling to_arg functions
Parameters:
  • item - A menu link
Returns:
Returns the map of path arguments with objects loaded as defined in the item['load_functions']. item['access'] becomes True if the item is accessible, False otherwise. item['href'] is generated from link_path, possibly by to_arg functions. item['title'] is generated from link_title, and may be localized. item['options'] is unserialized; it is also changed within the call here to item['localized_options'] by _menu_item_localize().

get_object(type_='node', position=1, path=None)

source code 
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.
Parameters:
  • 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.

tree(menu_name='navigation')

source code 
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).
Parameters:
  • menu_name - The name of the menu.
Returns:
The rendered HTML of that menu on the current page.

tree_output(tree)

source code 
Returns a rendered menu tree.
Parameters:
  • tree - A data structure representing the tree as returned from menu_tree_data.
Returns:
The rendered HTML of that data structure.

tree_all_data(menu_name='navigation', item=None)

source code 
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.
Parameters:
  • menu_name - The named menu links to return
  • item - A fully loaded menu link, or None. 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.
Returns:
An tree of menu links in an array, in the order they should be rendered.

tree_page_data(menu_name='navigation')

source code 
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.
Parameters:
  • menu_name - The named menu links to return
Returns:
An array of menu links, in the order they should be rendered. The array is a list of associative arrays -- these have two keys, link and below. link is a menu item, ready for theming as a link. Below represents the submenu below the link if there is one, and it is a subtree that has the same structure described for the top-level array.

tree_data(result=None, parents={}, depth=1)

source code 
Build the data representing a menu tree.
Parameters:
  • 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.
Returns:
See menu_tree_page_data for a description of the data structure.

_tree_data(result, parents, depth, previous_element='')

source code 
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.

navigation_links(menu_name, level=0)

source code 
Return an array of links for a navigation menu.
Parameters:
  • menu_name - The name of the menu.
  • level - Optional, the depth of the menu to be returned.
Returns:
An array of links of the specified menu and level.

local_tasks(level=0, return_root=False)

source code 
Collects the local tasks (tabs) for a given level.
Parameters:
  • 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.
Returns:
Themed output corresponding to the tabs of the requested level, or router path if return_root == True. This router path corresponds to a parent tab, if the current page is a default local task.

theme_menu_local_tasks()

source code 
Returns the rendered local tasks. The default implementation renders them as tabs.

set_active_item(path)

source code 
Set the active path, which determines which page is loaded.
Parameters:
  • path - A Drupal path - not a path alias. Note that this may not have the desired effect unless invoked very early in the page load, such as during hook_boot, or unless you call menu_execute_active_handler() to generate your page output.

link_load(mlid)

source code 
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.
Parameters:
  • mlid - The mlid of the menu item.
Returns:
A menu link, with item['access'] filled and link translated for rendering.

cache_clear_all()

source code 
Clears all cached menu data. This should be called any time broad changes might have been made to the router items or menu links.

rebuild()

source code 
(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.

link_delete(mlid, path=None)

source code 
Delete one or several menu links.
Parameters:
  • mlid - A valid menu link mlid or None. If None, path is used.
  • path - The path to the menu items to be deleted. mlid must be None.

_delete_item(item, force=False)

source code 
Helper function for menu_link_delete; deletes a single menu link.
Parameters:
  • item - Item to be deleted.
  • force - Forces deletion. Internal use only, setting to True is discouraged.

link_save(item)

source code 
Save a menu link.
Parameters:
  • item - An array representing a menu link item. The only mandatory keys are link_path and link_title. Possible keys are: - menu_name default is navigation - weight default is 0 - expanded whether the item is expanded. - options An array of options, @see l for more. - mlid Set to an existing value, or 0 or None to insert a new link. - plid The mlid of the parent. - router_path The path of the relevant router item.

_find_router_path(menu, link_path)

source code 
Find the router path which will serve this path.
Parameters:
  • menu - The full built menu.
  • link_path - The path for we are looking up its router path.
Returns:
A path from menu keys or empty if link_path points to a nonexisting place.

link_maintain(plugin, op, link_path, link_title)

source code 
Insert, update or delete an uncustomized menu link related to a plugin.
Parameters:
  • plugin - The name of the plugin.
  • 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.
Returns:
The insert op returns the mlid of the new item. Others op return None.

link_children_relative_depth(item)

source code 
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.
Parameters:
  • item - An array representing a menu link item.
Returns:
The relative depth, or zero.

_link_move_children(item, existing_item)

source code 
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.

_site_is_offline()

source code 
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.
Returns:
False if the site is not off-line or its the login page or the user has 'administer site configuration' permission. True for anonymous users not on the login page if the site is off-line.

valid_path(form_item)

source code 
Validates the path of a menu link being created or edited.
Returns:
True if it is a valid path AND the current user has access permission, False otherwise.

   Home       Trees       Indices       Help   
Generated by Epydoc 3.0.1 on Fri Sep 19 19:58:41 2008 http://epydoc.sourceforge.net