hook_menu

Define menu items and page callbacks.

This hook enables modules to register paths, which determines whose requests are to be handled. Depending on the type of registration requested by each path, a link is placed in the the navigation block and/or an item appears in the menu administration page (q=admin/menu).

Drupal will call this hook twice: once with $may_cache set to TRUE, and once with it set to FALSE. Therefore, each menu item should be registered when $may_cache is either TRUE or FALSE, not both times. Setting a menu item twice will result in unspecified behavior.

This hook is also a good place to put code which should run exactly once per page view. Put it in an if (!may_cache) block.

Parameters

$may_cache: A boolean indicating whether cacheable menu items should be returned. The menu cache is per-user, so items can be cached so long as they are not dependent on the user's current location. See the local task definitions in node_menu() for an example of uncacheable menu items.

Return value

An array of menu items. Each menu item is an associative array that may contain the following key-value pairs:

• "path": Required. The path to link to when the user selects the item.
• "title": Required. The translated title of the menu item.
• "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.
• "callback arguments": An array of arguments to pass to the callback function.
• "access": A boolean value that determines whether the user has access rights to this menu item. Usually determined by a call to user_access(). If omitted and "callback" is also absent, the access rights of the parent menu item will be used instead.
• "weight": An integer that determines 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.
• "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_ITEM_GROUPING: Item groupings are used for pages like "node/add" that simply list subpages to visit.
  • MENU_CALLBACK: Callbacks simply register a path so that the correct function is fired when the URL is accessed.
  • MENU_DYNAMIC_ITEM: Dynamic menu items change frequently, and so should not be stored in the database for administrative customization.
  • 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" key is omitted, MENU_NORMAL_ITEM is assumed.

For a detailed usage example, see page_example.module.

Related topics

Hooks

Allow modules to interact with the Drupal core.

File

developer/hooks/core.php, line 760

These are the hooks that are invoked by the Drupal core.

Code

<?php
function hook_menu($may_cache) {
  global $user;
  $items = array();

  if ($may_cache) {
    $items[] = array(
      'path' => 'node/add/blog', 
      'title' => t('blog entry'), 
      'access' => user_access('maintain personal blog'),
    );
    $items[] = array(
      'path' => 'blog', 
      'title' => t('blogs'), 
      'callback' => 'blog_page', 
      'access' => user_access('access content'), 
      'type' => MENU_SUGGESTED_ITEM,
    );
    $items[] = array(
      'path' => 'blog/' . $user->uid, 
      'title' => t('my blog'), 
      'access' => user_access('maintain personal blog'), 
      'type' => MENU_DYNAMIC_ITEM,
    );
    $items[] = array(
      'path' => 'blog/feed', 
      'title' => t('RSS feed'), 
      'callback' => 'blog_feed', 
      'access' => user_access('access content'), 
      'type' => MENU_CALLBACK,
    );
  }
  return $items;
}
?>