From 5c5bd8034915fd81fc292251949479ab3f69ce20 Mon Sep 17 00:00:00 2001 From: Angie Byron Date: Wed, 28 Apr 2010 05:08:24 +0000 Subject: #394534 by aspilicious, BruceBGordon: Move Menu API documentation contents to system.api.php. --- modules/menu/menu.api.php | 493 ---------------------------------------------- 1 file changed, 493 deletions(-) (limited to 'modules/menu') diff --git a/modules/menu/menu.api.php b/modules/menu/menu.api.php index 3bd182240..0abb1c546 100644 --- a/modules/menu/menu.api.php +++ b/modules/menu/menu.api.php @@ -11,393 +11,6 @@ * @{ */ -/** - * Define menu items and page callbacks. - * - * This hook enables modules to register paths in order to define how URL - * requests are handled. Paths may be registered for URL handling only, or they - * can register a link to be placed in a menu (usually the Navigation menu). A - * path and its associated information is commonly called a "menu router item". - * This hook is rarely called (for example, when modules are enabled), and - * its results are cached in the database. - * - * hook_menu() implementations return an associative array whose keys define - * paths and whose values are an associative array of properties for each - * path. (The complete list of properties is in the return value section below.) - * - * The definition for each path may include a page callback function, which is - * invoked when the registered path is requested. If there is no other - * registered path that fits the requested path better, any further path - * components are passed to the callback function. For example, your module - * could register path 'abc/def': - * @code - * function mymodule_menu() { - * $items['abc/def'] = array( - * 'page callback' => 'mymodule_abc_view', - * ); - * } - * - * function mymodule_abc_view($ghi = 0, $jkl = '') { - * // ... - * } - * @endcode - * When path 'abc/def' is requested, no further path components are in the - * request, and no additional arguments are passed to the callback function (so - * $ghi and $jkl would take the default values as defined in the function - * signature). When 'abc/def/123/foo' is requested, $ghi will be '123' and - * $jkl will be 'foo'. Note that this automatic passing of optional path - * arguments applies only to page and theme callback functions. - * - * In addition to optional path arguments, the page callback and other callback - * functions may specify argument lists as arrays. These argument lists may - * contain both fixed/hard-coded argument values and integers that correspond - * to path components. When integers are used and the callback function is - * called, the corresponding path components will be substituted for the - * integers. That is, the integer 0 in an argument list will be replaced with - * the first path component, integer 1 with the second, and so on (path - * components are numbered starting from zero). This substitution feature allows - * you to re-use a callback function for several different paths. For example: - * @code - * function mymodule_menu() { - * $items['abc/def'] = array( - * 'page callback' => 'mymodule_abc_view', - * 'page arguments' => array(1, 'foo'), - * ); - * } - * @endcode - * When path 'abc/def' is requested, the page callback function will get 'def' - * as the first argument and (always) 'foo' as the second argument. - * - * Note that if a page or theme callback function has an argument list array, - * these arguments will be passed first to the function, followed by any - * any arguments generated by optional path arguments as described above. - * - * Special care should be taken for the page callback drupal_get_form(), because - * your specific form callback function will always receive $form and - * &$form_state as the first function arguments: - * @code - * function mymodule_abc_form($form, &$form_state) { - * // ... - * return $form; - * } - * @endcode - * See @link form_api Form API documentation @endlink for details. - * - * Wildcards within paths also work with integer substitution. For example, - * your module could register path 'my-module/%/edit': - * @code - * $items['my-module/%/edit'] = array( - * 'page callback' => 'mymodule_abc_edit', - * 'page arguments' => array(1), - * ); - * @endcode - * When path 'my-module/foo/edit' is requested, integer 1 will be replaced - * with 'foo' and passed to the callback function. - * - * Registered paths may also contain special "auto-loader" wildcard components - * in the form of '%mymodule_abc', where the '%' part means that this path - * component is a wildcard, and the 'mymodule_abc' part defines the prefix for a - * load function, which here would be named mymodule_abc_load(). When a matching - * path is requested, your load function will receive as its first argument the - * path component in the position of the wildcard; load functions may also be - * passed additional arguments (see "load arguments" in the return value - * section below). For example, your module could register path - * 'my-module/%mymodule_abc/edit': - * @code - * $items['my-module/%mymodule_abc/edit'] = array( - * 'page callback' => 'mymodule_abc_edit', - * 'page arguments' => array(1), - * ); - * @endcode - * When path 'my-module/123/edit' is requested, your load function - * mymodule_abc_load() will be invoked with the argument '123', and should - * load and return an "abc" object with internal id 123: - * @code - * function mymodule_abc_load($abc_id) { - * return db_query("SELECT * FROM {mymodule_abc} WHERE abc_id = :abc_id", array(':abc_id' => $abc_id))->fetchObject(); - * } - * @endcode - * This 'abc' object will then be passed into the page callback function - * mymodule_abc_edit() to replace the integer 1 in the page arguments. - * - * You can also make groups of menu items to be rendered (by default) as tabs - * on a page. To do that, first create one menu item of type MENU_NORMAL_ITEM, - * with your chosen path, such as 'foo'. Then duplicate that menu item, using a - * subdirectory path, such as 'foo/tab1', and changing the type to - * MENU_DEFAULT_LOCAL_TASK to make it the default tab for the group. Then add - * the additional tab items, with paths such as "foo/tab2" etc., with type - * MENU_LOCAL_TASK. Example: - * @code - * // Make "Foo settings" appear on the admin Config page - * $items['admin/config/foo'] = array( - * 'title' => 'Foo settings', - * 'type' => MENU_NORMAL_ITEM, - * // page callback, etc. need to be added here - * ); - * // Make "Global settings" the main tab on the "Foo settings" page - * $items['admin/config/foo/global'] = array( - * 'title' => 'Global settings', - * 'type' => MENU_DEFAULT_LOCAL_TASK, - * // access callback, page callback, and theme callback will be inherited - * // from 'admin/config/foo', if not specified here to override - * ); - * // Make an additional tab called "Node settings" on "Foo settings" - * $items['admin/config/foo/node'] = array( - * 'title' => 'Node settings', - * 'type' => MENU_LOCAL_TASK, - * // access callback, page callback, and theme callback will be inherited - * // from 'admin/config/foo', if not specified here to override - * ); - * @endcode - * - * @return - * An array of menu items. Each menu item has a key corresponding to the - * Drupal path being registered. The corresponding array value is an - * associative array that may contain the following key-value pairs: - * - "title": Required. The untranslated title of the menu item. - * - "title callback": Function to generate the title; defaults to t(). - * If you require only the raw string to be output, set this to FALSE. - * - "title arguments": Arguments to send to t() or your custom callback, - * with path component substitution as described above. - * - "description": The untranslated description of the menu item. - * - "page callback": The function to call to display a web page when the user - * visits the path. If omitted, the parent menu item's callback will be used - * instead. - * - "page arguments": An array of arguments to pass to the page callback - * function, with path component substitution as described above. - * - "delivery callback": The function to call to package the result of the - * page callback function and send it to the browser. Defaults to - * drupal_deliver_html_page() unless a value is inherited from a parent menu - * item. - * - "access callback": A function returning a boolean value that determines - * whether the user has access rights to this menu item. Defaults to - * user_access() unless a value is inherited from a parent menu item. - * - "access arguments": An array of arguments to pass to the access callback - * function, with path component substitution as described above. - * - "theme callback": Optional. A function returning the machine-readable - * name of the default theme that will be used to render the page. If this - * function is provided, it is expected to return a currently-active theme - * on the site (otherwise, the main site theme will be used instead). If no - * function is provided, the main site theme will also be used, unless a - * value is inherited from a parent menu item. In all cases, the results of - * this function can be dynamically overridden for a particular page - * request by modules which implement hook_custom_theme(). - * - "theme arguments": An array of arguments to pass to the theme callback - * function, with path component substitution as described above. - * - "file": A file that will be included before the page callback is called; - * this allows page callback functions to be in separate files. The file - * should be relative to the implementing module's directory unless - * otherwise specified by the "file path" option. Does not apply to other - * callbacks (only page callback). - * - "file path": The path to the directory containing the file specified in - * "file". This defaults to the path to the module implementing the hook. - * - "load arguments": An array of arguments to be passed to each of the - * wildcard object loaders in the path, after the path argument itself. - * For example, if a module registers path node/%node/revisions/%/view - * with load arguments set to array(3), the '%node' in the path indicates - * that the loader function node_load() will be called with the second - * path component as the first argument. The 3 in the load arguments - * indicates that the fourth path component will also be passed to - * node_load() (numbering of path components starts at zero). So, if path - * node/12/revisions/29/view is requested, node_load(12, 29) will be called. - * There are also two "magic" values that can be used in load arguments. - * "%index" indicates the index of the wildcard path component. "%map" - * indicates the path components as an array. For example, if a module - * registers for several paths of the form 'user/%user_category/edit/*', all - * of them can use the same load function user_category_load(), by setting - * the load arguments to array('%map', '%index'). For instance, if the user - * is editing category 'foo' by requesting path 'user/32/edit/foo', the load - * function user_category_load() will be called with 32 as its first - * argument, the array ('user', 32, 'edit', 'foo') as the map argument, - * and 1 as the index argument (because %user_category is the second path - * component and numbering starts at zero). user_category_load() can then - * use these values to extract the information that 'foo' is the category - * being requested. - * - "weight": An integer that determines the relative position of items in - * the menu; higher-weighted items sink. Defaults to 0. Menu items with the - * same weight are ordered alphabetically. - * - "menu_name": Optional. Set this to a custom menu if you don't want your - * item to be placed in Navigation. - * - "context": (optional) Defines the context a tab may appear in. By - * default, all tabs are only displayed as local tasks when being rendered - * in a page context. All tabs that should be accessible as contextual links - * in page region containers outside of the parent menu item's primary page - * context should be registered using one of the following contexts: - * - MENU_CONTEXT_PAGE: (default) The tab is displayed as local task for the - * page context only. - * - MENU_CONTEXT_INLINE: The tab is displayed as contextual link outside of - * the primary page context only. - * Contexts can be combined. For example, to display a tab both on a page - * and inline, a menu router item may specify: - * @code - * 'context' => MENU_CONTEXT_PAGE | MENU_CONTEXT_INLINE, - * @endcode - * - "tab_parent": For local task menu items, the path of the task's parent - * item; defaults to the same path without the last component (e.g., the - * default parent for 'admin/people/create' is 'admin/people'). - * - "tab_root": For local task menu items, the path of the closest non-tab - * item; same default as "tab_parent". - * - "block callback": Name of a function used to render the block on the - * system administration page for this item (called with no arguments). - * If not provided, system_admin_menu_block() is used to generate it. - * - "position": Position of the block ('left' or 'right') on the system - * administration page for this item. - * - "type": A bitmask of flags describing properties of the menu item. - * Many shortcut bitmasks are provided as constants in menu.inc: - * - MENU_NORMAL_ITEM: Normal menu items show up in the menu tree and can be - * moved/hidden by the administrator. - * - MENU_CALLBACK: Callbacks simply register a path so that the correct - * information is generated when the path is accessed. - * - MENU_SUGGESTED_ITEM: Modules may "suggest" menu items that the - * administrator may enable. - * - MENU_LOCAL_ACTION: Local actions are menu items that describe actions - * on the parent item such as adding a new user or block, and are - * rendered in the action-links list in your theme. - * - MENU_LOCAL_TASK: Local tasks are menu items that describe different - * displays of data, and are generally rendered as tabs. - * - MENU_DEFAULT_LOCAL_TASK: Every set of local tasks should provide one - * "default" task, which should display the same page as the parent item. - * If the "type" element is omitted, MENU_NORMAL_ITEM is assumed. - * - * For a detailed usage example, see page_example.module. - * For comprehensive documentation on the menu system, see - * http://drupal.org/node/102338. - */ -function hook_menu() { - $items['blog'] = array( - 'title' => 'blogs', - 'page callback' => 'blog_page', - 'access arguments' => array('access content'), - 'type' => MENU_SUGGESTED_ITEM, - ); - $items['blog/feed'] = array( - 'title' => 'RSS feed', - 'page callback' => 'blog_feed', - 'access arguments' => array('access content'), - 'type' => MENU_CALLBACK, - ); - - return $items; -} - -/** - * Alter the data being saved to the {menu_router} table after hook_menu is invoked. - * - * This hook is invoked by menu_router_build(). The menu definitions are passed - * in by reference. Each element of the $items array is one item returned - * by a module from hook_menu. Additional items may be added, or existing items - * altered. - * - * @param $items - * Associative array of menu router definitions returned from hook_menu(). - */ -function hook_menu_alter(&$items) { - // Example - disable the page at node/add - $items['node/add']['access callback'] = FALSE; -} - -/** - * Alter the data being saved to the {menu_links} table by menu_link_save(). - * - * @param $item - * Associative array defining a menu link as passed into menu_link_save(). - */ -function hook_menu_link_alter(&$item) { - // Example 1 - make all new admin links hidden (a.k.a disabled). - if (strpos($item['link_path'], 'admin') === 0 && empty($item['mlid'])) { - $item['hidden'] = 1; - } - // Example 2 - flag a link to be altered by hook_translated_menu_link_alter() - if ($item['link_path'] == 'devel/cache/clear') { - $item['options']['alter'] = TRUE; - } -} - -/** - * Alter a menu link after it's translated, but before it's rendered. - * - * This hook may be used, for example, to add a page-specific query string. - * For performance reasons, only links that have $item['options']['alter'] == TRUE - * will be passed into this hook. The $item['options']['alter'] flag should - * generally be set using hook_menu_link_alter(). - * - * @param $item - * Associative array defining a menu link after _menu_link_translate() - * @param $map - * Associative array containing the menu $map (path parts and/or objects). - */ -function hook_translated_menu_link_alter(&$item, $map) { - if ($item['href'] == 'devel/cache/clear') { - $item['localized_options']['query'] = drupal_get_destination(); - } -} - -/** - * Inform modules that a menu link has been created. - * - * This hook is used to notify modules that menu items have been - * created. Contributed modules may use the information to perform - * actions based on the information entered into the menu system. - * - * @param $link - * Associative array defining a menu link as passed into menu_link_save(). - * - * @see hook_menu_link_update() - * @see hook_menu_link_delete() - */ -function hook_menu_link_insert($link) { - // In our sample case, we track menu items as editing sections - // of the site. These are stored in our table as 'disabled' items. - $record['mlid'] = $link['mlid']; - $record['menu_name'] = $link['menu_name']; - $record['status'] = 0; - drupal_write_record('menu_example', $record); -} - -/** - * Inform modules that a menu link has been updated. - * - * This hook is used to notify modules that menu items have been - * updated. Contributed modules may use the information to perform - * actions based on the information entered into the menu system. - * - * @param $link - * Associative array defining a menu link as passed into menu_link_save(). - * - * @see hook_menu_link_insert() - * @see hook_menu_link_delete() - */ -function hook_menu_link_update($link) { - // If the parent menu has changed, update our record. - $menu_name = db_result(db_query("SELECT mlid, menu_name, status FROM {menu_example} WHERE mlid = :mlid", array(':mlid' => $link['mlid']))); - if ($menu_name != $link['menu_name']) { - db_update('menu_example') - ->fields(array('menu_name' => $link['menu_name'])) - ->condition('mlid', $link['mlid']) - ->execute(); - } -} - -/** - * Inform modules that a menu link has been deleted. - * - * This hook is used to notify modules that menu items have been - * deleted. Contributed modules may use the information to perform - * actions based on the information entered into the menu system. - * - * @param $link - * Associative array defining a menu link as passed into menu_link_save(). - * - * @see hook_menu_link_insert() - * @see hook_menu_link_update() - */ -function hook_menu_link_delete($link) { - // Delete the record from our table. - db_delete('menu_example') - ->condition('mlid', $link['mlid']) - ->execute(); -} - /** * Informs modules that a custom menu was created. * @@ -470,112 +83,6 @@ function hook_menu_delete($menu) { variable_set('my_module_menus', $my_menus); } -/** - * Alter tabs and actions displayed on the page before they are rendered. - * - * This hook is invoked by menu_local_tasks(). The system-determined tabs and - * actions are passed in by reference. Additional tabs or actions may be added, - * or existing items altered. - * - * Each tab or action is an associative array containing: - * - #theme: The theme function to use to render. - * - #link: An associative array containing: - * - title: The localized title of the link. - * - href: The system path to link to. - * - localized_options: An array of options to pass to url(). - * - #active: Whether the link should be marked as 'active'. - * - * @param $data - * An associative array containing: - * - actions: An associative array containing: - * - count: The amount of actions determined by the menu system, which can - * be ignored. - * - output: A list of of actions, each one being an associative array - * as described above. - * - tabs: An indexed array (list) of tab levels (up to 2 levels), each - * containing an associative array: - * - count: The amount of tabs determined by the menu system. This value - * does not need to be altered if there is more than one tab. - * - output: A list of of tabs, each one being an associative array as - * described above. - */ -function hook_menu_local_tasks_alter(&$data, $router_item, $root_path) { - // Add an action linking to node/add to all pages. - $data['actions']['output'][] = array( - '#theme' => 'menu_local_task', - '#link' => array( - 'title' => t('Add new content'), - 'href' => 'node/add', - 'localized_options' => array( - 'attributes' => array( - 'title' => t('Add new content'), - ), - ), - ), - ); - - // Add a tab linking to node/add to all pages. - $data['tabs'][0]['output'][] = array( - '#theme' => 'menu_local_task', - '#link' => array( - 'title' => t('Example tab'), - 'href' => 'node/add', - 'localized_options' => array( - 'attributes' => array( - 'title' => t('Add new content'), - ), - ), - ), - // Define whether this link is active. This can be omitted for - // implementations that add links to pages outside of the current page - // context. - '#active' => ($router_item['path'] == $root_path), - ); -} - -/** - * Alter contextual links before they are rendered. - * - * This hook is invoked by menu_contextual_links(). The system-determined - * contextual links are passed in by reference. Additional links may be added - * or existing links can be altered. - * - * Each contextual link must at least contain: - * - title: The localized title of the link. - * - href: The system path to link to. - * - localized_options: An array of options to pass to url(). - * - * @param $links - * An associative array containing contextual links for the given $root_path, - * as described above. The array keys are used to build CSS class names for - * contextual links and must therefore be unique for each set of contextual - * links. - * @param $router_item - * The menu router item belonging to the $root_path being requested. - * @param $root_path - * The (parent) path that has been requested to build contextual links for. - * This is a normalized path, which means that an originally passed path of - * 'node/123' became 'node/%'. - * - * @see menu_contextual_links() - * @see hook_menu() - * @see system_preprocess() - */ -function hook_menu_contextual_links_alter(&$links, $router_item, $root_path) { - // Add a link to all contextual links for nodes. - if ($root_path == 'node/%') { - $links['foo'] = array( - 'title' => t('Do fu'), - 'href' => 'foo/do', - 'localized_options' => array( - 'query' => array( - 'foo' => 'bar', - ), - ), - ); - } -} - /** * @} End of "addtogroup hooks". */ -- cgit v1.2.3