Skip to content
Snippets Groups Projects
Commit 5c5bd803 authored by Angie Byron's avatar Angie Byron
Browse files

#394534 by aspilicious, BruceBGordon: Move Menu API documentation contents to system.api.php.

parent 5d672251
No related branches found
No related tags found
2 merge requests!7452Issue #1797438. HTML5 validation is preventing form submit and not fully...,!789Issue #3210310: Adjust Database API to remove deprecated Drupal 9 code in Drupal 10
Expand all Hide whitespace changes
Inline Side-by-side
modules/menu/menu.api.php
+ 0
− 493
View file @ 5c5bd803
......@@ -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".
*/
modules/system/system.api.php
+ 493
− 0
View file @ 5c5bd803
This diff is collapsed.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment