CHAPTER 4 ■ THE MENU SYSTEM

function menufun_title() { drupal_set_title(t('The page title')); $now = format_date(time());

return t('It is now @time', array('@time' => $now));

}

This results in one title for the page and another for the menu item, as shown in Figure 4-10.

Figure 4-10. Separate titles for the menu item and the page

Wildcards in Menu Items

So far, we have been using regular Drupal path names in our menu items, names like menufun and menufun/farewell. But Drupal often uses paths like user/4/track or node/15/edit, where part of the path is dynamic. Let’s look at how that works.

Basic Wildcards

The % character is a wildcard character in Drupal menu items, meaning the value is determined at runtime by the value found in the position of the URL that contains the wildcard. Here’s a menu item that uses a wildcard:

74

CHAPTER 4 ■ THE MENU SYSTEM

function menufun_menu() { $items['menufun/%'] = array(

'title' => 'Hi',

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

);

return $items;

}

This menu item will work for the Drupal paths menufun/hi, menufun/foo/bar, menufun/123, and menufun/file.html. It will not work for the path menufun; a separate menu item would have to be written for that path because it consists of only one part, and the wildcard menufun/% will match only a string with two parts. Note that although % is often used to designate a number (as in user/%/edit for user/2375/edit), it will match any text in that position.

■ Note A menu item with a wildcard in its path will no longer show up in navigation menus, even if the menu item’s type is set to MENU_NORMAL_ITEM. It should be obvious why this is: since the path contains a wildcard, Drupal doesn’t know how to construct the URL for the link. But see “Building Paths from Wildcards Using to_arg() Functions” later in this chapter to find out how you can tell Drupal what URL to use.

Wildcards and Page Callback Parameters

A wildcard at the end of the menu path does not interfere with the passing of additional parts of the URL to the page callback, because the wildcard matches only up to the next slash. Continuing with our example of the menufun/% path, the URL http://example.com/?q=menufun/foo/Fred would have the string foo matched by the wildcard, and the last portion of the path (Fred) would be passed as a parameter to the page callback.

Using the Value of a Wildcard

To use the part of the path that matched, specify the number of the path’s part in the page arguments key:

function menufun_menu() { $items['menufun/%/bar/baz'] = array(

'title' => 'Hi',

'page callback' => 'menufun_hello',

'page arguments' => array(1), // The matched wildcard. 'access callback' => TRUE,

);

return $items;

}

/**

* Page callback. */

75

CHAPTER 4 ■ THE MENU SYSTEM

function menufun_hello($name = NULL) {

return t('Hello. $name is @name', array('@name' => $name));

}

The parameters received by our page callback function menufun_hello() will be as shown in Figure 4-11.

Figure 4-11. The first parameter is from the matched wildcard.

The first parameter, $name, is being passed via the page callback. The entry array(1) for the page callback means, “please pass part 1 of the path, whatever that is.” We start counting at 0, so part 0 is menufun, part 1 is whatever the wildcard matched, part 2 would be bar, and so on. The second parameter, $b, is being passed because of Drupal’s behavior of passing the portion of the path beyond the Drupal path as a parameter (see “Page Callback Arguments” earlier in this chapter).

76

CHAPTER 4 ■ THE MENU SYSTEM

Wildcards and Parameter Replacement

In practice, parts of a Drupal path are generally used to view or change an object, such as a node or a user. For example, the path node/%/edit is used to edit a node, and the path user/% is used to view information about a user by user ID. Let’s take a look at the menu item for the latter, which can be found in the hook_menu() implementation in modules/user/user.module. The corresponding URL that this path matches would be something like http://example.com/?q=user/2375. That’s the URL you would click to see the “My account” page on a Drupal site.

$items['user/%user_uid_only_optional'] = array( 'title' => 'My account',

'title callback' => 'user_page_title', 'title arguments' => array(1),

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

'access callback' => 'user_view_access', 'access arguments' => array(1), 'weight' => -10,

'menu_name' => 'user-menu',

);

When Drupal creates the menu using user/%user_uid_only_optional, it replaces the %user_uid_only_optional using the process as described below:

1.In the second segment, match the string after the % and before the next possible slash. In this case, the string would be user_uid_optional.

2.Append _load to the string to generate the name of a function. In this case, the name of the function is user_uid_optional_load.

3.Call the function and pass it, as a parameter, the value of the wildcard in the Drupal path. So if the URL is http://example.com/?q=user/2375, the Drupal path is user/2375, and the wildcard matches the second segment, which is

2375. So a call is made to user_uid_optional_load('2375').

4.The result of this call is then used in place of the wildcard. So when the title callback is called with the title arguments of array(1), instead of passing part 1 of the Drupal path (2375), we pass the result of the call to user_uid_optional_load('2375'), which is a user object. Think of it as a portion of the Drupal path being replaced by the object it represents.

5.Note that the page and access callbacks will also use the replacement object. So in the previous menu item, user_view_access() will be called for access and user_view() will be called to generate the page content, and both will be passed the user object for user 2375.

77