Callback Mapping [The Menu System]

When  a web browser makes a request to Drupal, it gives Drupal a URL. From  this information, Drupal must figure out 

what  code to run  and  how to handle the request. This is commonly known as routing or dispatching. Drupal trims off

the base  part  of theURL and  uses the latter part, called  the path. For example, if the URL is http://example.com/?q=node/3, the Drupal path is node/3. If you are using Drupal’s clean URLs feature, the URL in your browser would be

http://example.com/node/3, but your webserver  is quietly rewriting the URL to be http://example.com/?q=node/3 before Drupal sees it; so Drupal always deals  with the same Drupal path. In the preceding example, the Drupal path is node/3 regardless of whether clean URLs are enabled. See “TheWeb Server’s Role” in Chapter 1 for more detail on how this works. 

Mapping URLs to Functions

The general approach taken is as follows: Drupal asks all enabled modules to provide an array of menu items. Each menu

item  consists of an array keyed by a path and  containing some information about that path. One of the pieces of

information a module must provide is a page callback. A callback in this context is simply  the name of a PHP function that will be run when the browser requests a certain path. Drupal goes through the following steps when a request comes in:

1.       Establish the Drupal path. If the path is an alias to a real path, Drupal finds the real path and  uses it instead. For example, if an administrator has aliased http://example.com/?q=about to  http://example.com/?q=node/3 (using the pathmodule, for example), Drupal uses node/3 as the path.

2.       Drupal keeps track of which paths map to which callbacks in the menu_router database table and  keeps track of menu items that are links in the menu_links table. A checkis made to see if the menu_router and  menu_links tables needrebuilding, a rare occurrence that happens after Drupal

installation or updating.

3.       Figure  out which entry in the menu_router table corresponds with the Drupal path and  build a router item  describing the callback to be called.

4.       Load any objects necessary to pass to the callback.

5.       Check whether the user is permitted to access the callback. If not, an “Access denied” message is returned.

6.       Localize  the menu item’s  title and  description for the current language.

7.       Load any necessary include files.

8.       Call the callback and  return the result, which index.php then passes through theme_page(), resulting in a finished 

web page.

A visual representation of this process is shown in Figures 4-1 and  4-2.

Figure 4-1. Overview of the menu dispatching process

Figure 4-2. Overview of the router and link  building process

Creating a Menu Item

To create a menu item, we’ll use the hook_menu() function. Hook_menu() takes an array of items that are to be added to a menu, where each  item  is itself an array of key/value pairs  that define the attributes of the menu item.

Table 4-1 details the keys ofthe menu item  array.

Table 4-1. Hook_menu() Key/Value Attributes
Key	Value
title	A required field that represents the untranslated title of the menu item
title callback	A function that is used to generate the title. This function defaults to t(), hence the reason we don’t wrap  the titlein the preceding item  with the t() function. If you do not want  the title to be translated, simply set the value toFALSE.
title arguments	Arguments that are to be sent  to the t() function or your own custom callback  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
Page arguments	An array of arguments to pass to the page callback function; integer values  pass the corresponding URL component.
access  callback	A function returning a Boolean value that determines whether the user has access rights  to this menu item; this 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; integer values   pass the corresponding URL component.
file	A file that will be included before the callbacks are accessed; this allows call back 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.
file path	The path to the folder  containing the file specified in “file.” This defaults to module implementing the hook.
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 the best.
menu_name	Optional; set this to a custom menu if you don’t  want  your item  placed in the  Navigation menu.
type	A bitmask of flags describing properties of the menu item; values to be used are:  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 URL 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, which  links to the same path as its parent when clicked.