CHAPTER 4 ■ THE MENU SYSTEM

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 of the menu item array.

Table 4-1. Hook_menu() Key/Value Attributes

61

CHAPTER 4 ■ THE MENU SYSTEM

Continued

The place to hook into the process is through the use of the menu hook in your module. This allows you to define menu items that will be included in the router table. Let’s build an example module called menufun.module to experiment with the menu system. We’ll map the Drupal path menufun to the PHP function that we’ll write named menufun_hello(). First, we need a menufun.info file at sites/all/modules/custom/menufun/menufun.info:

name = Menu Fun

description = Learning about the menu system. package = Pro Drupal Development

core = 7.x

files[] = menufun.module

Then we need to create the sites/all/modules/custom/menufun/menufun.module file, which contains our hook_menu() implementation and the function we want to run.

<?php

/**

*@file

*Use this module to learn about Drupal's menu system.

*/

62

CHAPTER 4 ■ THE MENU SYSTEM

/**

* Implementation of hook_menu(). */

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

‘title’ => ‘Greeting’,

'page callback' => 'menufun_hello', 'access callback' => TRUE,

'type' => MENU_CALLBACK,

);

return $items;

}

In the foregoing code, you’ll see that we’ve created our menu ($items[‘menufun’]) by creating an array with three key/value pairs:

“title”: A required value that defines the untranslated title of the menu item

“page callback”: The function that will be called when the user visits the menu path “access callback”: Typically this would contain a function that returns a Boolean value.

/**

* Page callback. */

function menufun_hello() { return t('Hello!');

}

Enabling the module at Modules causes the menu item to be inserted into the router table, so Drupal will now find and run our function when we go to http://example.com/?q=menufun, as shown in Figure 4-3.

The important thing to notice is that we are defining a path and mapping it to a function. The path is a Drupal path. We defined the path as the key of our $items array. We are using a path that is the same as the name of our module. This practice assures a pristine URL namespace. However, you can define any path.

63

CHAPTER 4 ■ THE MENU SYSTEM

Figure 4-3. The menu item has enabled Drupal to find and run the menufun_hello() function.

Page Callback Arguments

Sometimes, you may wish to provide more information to the page callback function that is mapped to the path. First of all, any additional parts of the path are automatically passed along. Let’s change our function as follows:

function menufun_hello($first_name = '', $last_name = '') { return t('Hello @first_name @last_name',

array('@first_name' => $first_name, '@last_name' => $last_name));

}

64

CHAPTER 4 ■ THE MENU SYSTEM

Now if we go to http://example.com/?q=menufun/John/Doe, we get the output shown in Figure 4-4.

Figure 4-4. Parts of the path are passed along to the callback function.

Notice how each of the extra components of the URL was passed as a parameter to our callback function.

You can also define page callback arguments inside the menu hook by adding an optional page arguments key to the $items array. Defining a page argument is useful because it allows you to gain more control over the parameters that are being passed to the callback function.

As an example, let’s update our menufun module by adding page arguments for our menu item:

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

'title' => 'Greeting',

'page callback' => 'menufun_hello',

65

CHAPTER 4 ■ THE MENU SYSTEM

'page arguments' => array('Jane', 'Doe'),

'access callback' => TRUE, 'type' => MENU_CALLBACK,

);

return $items;

}

After Drupal has followed all the instructions that are explicitly given for page arguments, any remaining path arguments that are unaccounted for also get sent into the page callback function as extra parameters, using PHP’s parameter overloading feature for functions. The arguments from the URL are still available; to access them, you would change the function signature of your callback to add parameters from the URL. So with our revised menu item, the following function signature would result in $first_name being Jane (from the first item in the page arguments array), and $last_name being Doe (from the second item in the page arguments array).

function menufun_hello($first_name = '', $last_name = '') {...}

Let’s test this by putting Jane Doe in the page arguments and John Doe in the URL and seeing which appears. Going to http://example.com/?q=menufun/John/Doe will now yield the results shown in Figure 4-5 (if you’re not getting those results, you forgot to rebuild your menus).

Figure 4-5. Passing and displaying arguments to the callback function

66