From a44f72acf05ea6825cfaf97aa7d486e4b991c066 Mon Sep 17 00:00:00 2001
From: Dries Buytaert <dries@buytaert.net>
Date: Fri, 4 Dec 2009 16:27:44 +0000
Subject: [PATCH] - Patch #617424 by matt2000, jhodgdon: documentation for
hook_menu().
---
modules/menu/menu.api.php | 180 +++++++++++++++++++++-----------------
1 file changed, 98 insertions(+), 82 deletions(-)
diff --git a/modules/menu/menu.api.php b/modules/menu/menu.api.php
index 97f0737aea9d..c6d35b9fd1d8 100644
--- a/modules/menu/menu.api.php
+++ b/modules/menu/menu.api.php
@@ -15,17 +15,21 @@
* 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, but can
- * also register a link to be placed in a menu (usually the Navigation menu). A
+ * 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 defining properties for each
- * path. The definition for each path may refer to a callback function that is
- * invoked when the registered path is requested. In case there is no other
+ * 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 optionally passed to the callback function by default.
- * For example, when registering the path 'abc/def':
+ * components are passed to the callback function. For example, your module
+ * could register path 'abc/def':
* @code
* function mymodule_menu() {
* $items['abc/def'] = array(
@@ -37,18 +41,22 @@
* // ...
* }
* @endcode
- * When the path 'abc/def' was requested, then no further arguments would be
- * passed to the callback function, so $ghi and $jkl would take the default
- * values as defined in the function signature.
- * In case 'abc/def/123/foo' was requested, then $ghi would be '123' and $jkl
- * would be 'foo'.
- *
- * In addition to optional path arguments, the definition for each path may
- * specify a list of arguments for each callback function as an array. These
- * argument lists may contain fixed/hard-coded argument values, but may also
- * contain integers that correspond to path components. When integers are used
- * and the callback function is called, the corresponding path components will
- * be substituted. For example:
+ * 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(
@@ -57,65 +65,60 @@
* );
* }
* @endcode
- * When the path 'abc/def' was requested, the callback function would get 'def'
- * as first argument and (always) 'foo' as second argument.
- * The integer 1 in an argument list would be replaced with 'def' and integer 0
- * would be replaced with 'abc', i.e. path components are counted from zero.
- * This allows to re-use a callback function for several different paths.
- *
- * Arguments may also be used to replace wildcards within paths. For example,
- * when registering the path 'my-module/%/edit':
+ * 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 the path 'my-module/foo/edit' is requested, then integer 1 will be
- * replaced with 'foo' and passed to the callback function.
+ * 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
- * menu argument loader function, which here would be mymodule_abc_load().
- * For example, when registering the path 'my-module/%mymodule_abc/edit':
+ * 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 the path 'my-module/123/edit' is requested, then the argument loader
- * function mymodule_abc_load() will be invoked with the argument '123', and it
- * is supposed to take that value to load and return data for "abc" having the
- * internal id 123:
+ * 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
- * The returned data of the argument loader will be passed in place of the
- * original path component to all callback functions referring to that (integer)
- * component in their argument list.
- * Menu argument loader functions may also be passed additional arguments; see
- * "load arguments" below.
- *
- * If a registered path defines an argument list, then those defined arguments
- * will always be passed first to the callback function. In case there are any
- * further components contained in the requested path, then those will always
- * come last.
- *
- * Special care should be taken for the page callback drupal_get_form(), because
- * the callback function will always receive $form and &$form_state as the very
- * first function arguments:
- * @code
- * function mymodule_abc_form($form, &$form_state) {
- * // ...
- * return $form;
- * }
- * @endcode
- * See @link form_api Form API documentation @endlink for details.
- *
+ * 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,
@@ -125,29 +128,28 @@
* the additional tab items, with paths such as "foo/tab2" etc., with type
* MENU_LOCAL_TASK. Example:
* @code
- * // This will make "Foo settings" appear on the admin Config page
+ * // 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
* );
- * // When you go to "Foo settings", "Global settings" will be the main tab
+ * // 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,
- * // page callback, etc. need to be added here
+ * // 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"
+ * // Make an additional tab called "Node settings" on "Foo settings"
* $items['admin/config/foo/node'] = array(
* 'title' => 'Node settings',
* 'type' => MENU_LOCAL_TASK,
- * // page callback, etc. need to be added here
+ * // access callback, page callback, and theme callback will be inherited
+ * // from 'admin/config/foo', if not specified here to override
* );
* @endcode
*
- * This hook is rarely called (for example, when modules are enabled), and
- * its results are cached in the database.
- *
* @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
@@ -179,24 +181,38 @@
* inherited from a parent menu item.
* - "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 callbacks are accessed;
- * this allows 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. Note: This does not apply to the
- * 'access callback'.
- * - "file path": The path to the folder containing the file specified in
+ * - "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. For example, for the path
- * node/%node/revisions/%/view, a "load arguments" value of array(1, 3) will
- * call node_load() with the second and fourth path components passed in (as
- * described above, integers are automatically replaced with path
- * components). There are also two "magic" values: "%index" will correspond
- * to the index of the wildcard path component, and "%map" will correspond
- * to the full menu map, passed in by reference.
+ * 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 23 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. When in doubt, leave
- * this alone; the default alphabetical order is usually best.
+ * 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
@@ -228,12 +244,12 @@
* - 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
- * function is fired when the path is accessed.
+ * information is generated when the path is accessed.
* - MENU_SUGGESTED_ITEM: Modules may "suggest" menu items that the
* administrator may enable.
* - MENU_LOCAL_TASK: Local tasks are rendered as tabs by default.
* - MENU_DEFAULT_LOCAL_TASK: Every set of local tasks should provide one
- * "default" task, that links to the same path as its parent when clicked.
+ * "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.
--
GitLab