CHAPTER 4 ■ THE MENU SYSTEM

■ Tip It is easier to think about object replacement in a Drupal path like node/%node/edit if you think about %node as being a wildcard with an annotation right there in the string. In other words, node/%node/ edit is node/%/edit with the implicit instruction to run node_load() on the wildcard match.

Passing Additional Arguments to the Load Function

If additional arguments need to be passed to the load function, they can be defined in the load arguments key. Here’s an example from the node module: the menu item for viewing a node revision. Both the node ID and the ID of the revision need to be passed to the load function, which is node_load().

$items['node/%node/revisions/%/view'] = array( 'title' => 'Revisions',

'load arguments' => array(3), 'page callback' => 'node_show', 'page arguments' => array(1, TRUE),

'access callback' => '_node_revision_access', 'access arguments' => array(1),

);

The menu item specifies array(3) for the load arguments key. This means that in addition to the wildcard value for the node ID, which is passed automatically to the load function as outlined previously, a single additional parameter will be passed to the load function, since array(3) has one member—that is, the integer 3. As you saw in the “Using the Value of a Wildcard” section, this means that the part of the path in position 3 will be used. The position and path arguments for the example URL http://example.com/?q=node/56/revisions/4/view are shown in Table 4-2.

Table 4-2. Position and Arguments for Drupal Path node/%node/revisions/%/view When Viewing the Page http://example.com/?q=node/56/revisions/4/view

Thus, defining the load arguments key means that the call node_load('56', '4') will be made instead of node_load('56').

78

CHAPTER 4 ■ THE MENU SYSTEM

When the page callback runs, the load function will have replaced the value '56' with the loaded node object, so the page callback call will be node_show($node, NULL, TRUE).

Special, Predefined Load Arguments: %map and %index

There are two special load arguments. The %map token passes the current Drupal path as an array. In the preceding example, if %map were passed as a load argument, its value would be array('node', '56', 'revisions', '4', 'view'). The values of the map can be manipulated by the load function if it declares the parameter as a reference. So for the preceding example, the token’s value would be 1 because the wildcard is at position 1, as shown in Table 4-2.

Building Paths from Wildcards Using to_arg() Functions

Recall that I said that Drupal cannot produce a valid link from a Drupal path that contains a wildcard, like user/% (after all, how would Drupal know what to replace the % with)? That’s not strictly true. We can define a helper function that produces a replacement for the wildcard that Drupal can then use when building the link. In the “My account” menu item, the path for the “My account” link is produced with the following steps:

1.The Drupal path is originally user/%user_uid_optional.

2.When building the link, Drupal looks for a function with the name user_uid_optional_to_arg(). If this function is not defined, Drupal cannot figure out how to build the path and does not display the link.

3.If the function is found, Drupal uses the result of the function as a replacement for the wildcard in the link. The user_uid_optional_to_arg() function returns the user ID of the current user, so if you are user 4, Drupal connects the “My account” link to http://example.com/?q=user/4.

The use of a to_arg() function is not specific to the execution of a given path. In other words, the to_arg() function is run during link building on any page, not the specific page that matches the Drupal path of a menu item. The “My account” link is shown on all pages, not just when the page http://example.com/?q=user/3 is being viewed.

Special Cases for Wildcards and to_arg() Functions

The to_arg() function that Drupal will look for when building a link for a menu item is based on the string following the wildcard in the Drupal path. This can be any string, as in this example:

/**

* Implementation of hook_menu(). */

function_menufun_menu() { $items['menufun/%a_zoo_animal'] = array(

'title' => 'Hi',

'page callback' => 'menufun_hello', 'page arguments' => array(1),

79