API Navigation

Menu system

Define the navigation menus, and route page requests to code based on URLs.

The Drupal menu system drives both the navigation system from a user
perspective and the callback system that Drupal uses to respond to URLs
passed from the browser. For this reason, a good understanding of the
menu system is fundamental to the creation of complex modules. As a note,
this is related to, but separate from menu.module, which allows menus
(which in this context are hierarchical lists of links) to be customized from
the Drupal administrative interface.

Drupal's menu system follows a simple hierarchy defined by paths.
Implementations of hook_menu() define menu items and assign them to
paths (which should be unique). The menu system aggregates these items
and determines the menu hierarchy from the paths. For example, if the
paths defined were a, a/b, e, a/b/c/d, f/g, and a/b/h, the menu system
would form the structure:

a

a/b

a/b/c/d

a/b/h

e

f/g

Note that the number of elements in the path does not necessarily
determine the depth of the menu item in the tree.

When responding to a page request, the menu system looks to see if the
path requested by the browser is registered as a menu item with a
callback. If not, the system searches up the menu tree for the most
complete match with a callback it can find. If the path a/b/i is
requested in the tree above, the callback for a/b would be used.

The found callback function is called with any arguments specified
in the "page arguments" attribute of its menu item. The
attribute must be an array. After these arguments, any remaining
components of the path are appended as further arguments. In this
way, the callback for a/b above could respond to a request for
a/b/i differently than a request for a/b/j.

Access to the callback functions is also protected by the menu system.
The "access callback" with an optional "access arguments" of each menu
item is called before the page callback proceeds. If this returns TRUE,
then access is granted; if FALSE, then access is denied. Default local task
menu items (see next paragraph) may omit this attribute to use the value
provided by the parent item.

In the default Drupal interface, you will notice many links rendered as
tabs. These are known in the menu system as "local tasks", and they are
rendered as tabs by default, though other presentations are possible.
Local tasks function just as other menu items in most respects. It is
convention that the names of these tasks should be short verbs if
possible. In addition, a "default" local task should be provided for
each set. When visiting a local task's parent menu item, the default
local task will be rendered as if it is selected; this provides for a
normal tab user experience. This default task is special in that it
links not to its provided path, but to its parent item's path instead.
The default task's path is only used to place it appropriately in the
menu hierarchy.

Everything described so far is stored in the menu_router table. The
menu_links table holds the visible menu links. By default these are
derived from the same hook_menu definitions, however you are free to
add more with menu_link_save().