diff --git a/modules/menu/menu.api.php b/modules/menu/menu.api.php
index 3bd18224074d892c5cb1780746f5736cf58ca9df..0abb1c546285f5f5a1d0912979d5ccdfb6da2dfe 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".
*/
diff --git a/modules/system/system.api.php b/modules/system/system.api.php
index 2f236d6ba368d4ba66237fdfc963776a663632ad..4f4fb99356e151e03c0e71ed89e10ce9ff31268e 100644
--- a/modules/system/system.api.php
+++ b/modules/system/system.api.php
@@ -682,6 +682,499 @@ function hook_page_build(&$page) {
}
}
+/**
+ * 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();
+}
+
+/**
+ * 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',
+ ),
+ ),
+ );
+ }
+}
+
/**
* Perform alterations before a page is rendered.
*