Home » API reference » menu.api.php

hook_menu

Versions
4.6 – 5
hook_menu($may_cache)
6 – 7
hook_menu()

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 path and its associated information is commonly called a "menu router item".

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 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':

<?php

function mymodule_menu() {
$items['abc/def'] = array(
'page callback' => 'mymodule_abc_view',
);
}

function mymodule_abc_view($ghi = 0, $jkl = '') {
// ...
  }

?>

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:

<?php

function mymodule_menu() {
$items['abc/def'] = array(
'page callback' => 'mymodule_abc_view',
'page arguments' => array(1, 'foo'),
);
}

?>

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':

<?php

$items['my-module/%/edit'] = array(
'page callback' => 'mymodule_abc_edit',
'page arguments' => array(1),
);

?>

When the path 'my-module/foo/edit' is requested, then 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':

<?php

$items['my-module/%mymodule_abc/edit'] = array(
'page callback' => 'mymodule_abc_edit',
'page arguments' => array(1),
);

?>

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:

<?php

function mymodule_abc_load($abc_id) {
return db_query("SELECT * FROM {mymodule_abc} WHERE abc_id = :abc_id", array(':abc_id' => $abc_id))->fetchObject();
}

?>

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:

<?php

function mymodule_abc_form($form, &$form_state) {
// ...
    return $form;
}

?>

See Form API documentation for details.

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:

<?php

// This will 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
$items['admin/config/foo/global'] = array(
'title' => 'Global settings',
'type' => MENU_DEFAULT_LOCAL_TASK,
// page callback, etc. need to be added here
);
// Make an additional tab called "Node settings"
$items['admin/config/foo/node'] = array(
'title' => 'Node settings',
'type' => MENU_LOCAL_TASK,
// page callback, etc. need to be added here
);

?>

This hook is rarely called (for example, when modules are enabled), and its results are cached in the database.

For a detailed usage example, see page_example.module. For comprehensive documentation on the menu system, see http://drupal.org/node/102338.

Return value

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 theme that will be used to render the page. If the function returns nothing, the main site theme will be used. If no function is provided, the main site theme will also be used, unless a value is 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". 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.
  • "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.
  • "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:

<?php

'context' => MENU_CONTEXT_PAGE | MENU_CONTEXT_INLINE,

?>
  • "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 function is fired 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.

    If the "type" element is omitted, MENU_NORMAL_ITEM is assumed.

Related topics

Hooks
Allow modules to interact with the Drupal core.

Code

modules/menu/menu.api.php, line 242

<?php
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;
}
?>
Login or register to post comments
 
 

All source code and documentation on this site is released under the terms of the GNU General Public License, version 2 and later. Drupal is a registered trademark of Dries Buytaert.