CHAPTER 4 ■ THE MENU SYSTEM

Table 4-5. Flags Expressed by Menu Item Types

*This constant is created with an additional bitwise or with 0x0010.

So which constant should you use when defining the type of your menu item? Look at Table 4-5 and see which flags you want enabled, and use the constant that contains those flags. For a detailed description of each constant, see the comments in includes/menu.inc. The most commonly used are

MENU_CALLBACK, MENU_LOCAL_TASK, and MENU_DEFAULT_LOCAL_TASK. Read on for details.

Common Tasks

This section lays out some typical approaches to common problems confronting developers when working with menus.

84

CHAPTER 4 ■ THE MENU SYSTEM

Assigning Callbacks Without Adding a Link to the Menu

Often, you may want to map a URL to a function without creating a visible menu item. For example, maybe you have a JavaScript function in a web form that needs to get a list of states from Drupal, so you need to wire up a URL to a PHP function but have no need of including this in any navigation menu. You can do this by assigning the MENU_CALLBACK type to your menu item, as in the first example in this chapter.

Displaying Menu Items As Tabs

A callback that is displayed as a tab is known as a local task and has the type MENU_LOCAL_TASK or MENU_DEFAULT_LOCAL_TASK. The title of a local task should be a short verb, such as “add” or “list.” Local tasks usually act on some kind of object, such as a node, or user. You can think of a local task as being a semantic declaration about a menu item, which is normally rendered as a tab—similar to the way that the <strong> tag is a semantic declaration and is usually rendered as boldfaced text.

Local tasks must have a parent item in order for the tabs to be rendered. A common practice is to assign a callback to a root path like milkshake, and then assign local tasks to paths that extend that path, like milkshake/prepare, milkshake/drink, and so forth. Drupal has built-in theming support for two levels of tabbed local tasks. (Additional levels are supported by the underlying system, but your theme would have to provide support for displaying these additional levels.)

The order in which tabs are rendered is determined by alphabetically sorting on the value of title for each menu item. If this order is not to your liking, you can add a weight key to your menu items, and they will be sorted by weight instead.

The following example shows code that results in two main tabs and two subtabs under the default local task. Create sites/all/modules/custom/milkshake/milkshake.info as follows:

name = Milkshake

description = Demonstrates menu local tasks. package = Pro Drupal Development

core = 7.x

files[] = milkshake.module

Then enter the following for sites/all/modules/custom/milkshake/milkshake.module:

<?php

/**

*@file

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

*specifically how local tasks work.

*/

/**

* Implements hook_menu(). */

function milkshake_menu() { $items['milkshake'] = array(

'title' => 'Milkshake flavors', 'access arguments' => TRUE,

85

CHAPTER 4 ■ THE MENU SYSTEM

'page callback' => 'milkshake_overview', 'type' => MENU_NORMAL_ITEM,

);

$items['milkshake/list'] = array( 'title' => 'List flavors', 'access arguments' => TRUE, 'type' => MENU_DEFAULT_LOCAL_TASK, 'weight' => 0,

);

$items['milkshake/add'] = array( 'title' => 'Add flavor', 'access arguments' => TRUE,

'page callback' => 'milkshake_add', 'type' => MENU_LOCAL_TASK, 'weight' => 1,

);

$items['milkshake/list/fruity'] = array( 'title' => 'Fruity flavors',

'access arguments' => TRUE,

'page callback' => 'milkshake_list',

'page arguments' => array(2), // Pass 'fruity'. 'type' => MENU_LOCAL_TASK,

);

$items['milkshake/list/candy'] = array( 'title' => 'Candy flavors',

'access arguments' => TRUE,

'page callback' => 'milkshake_list',

'page arguments' => array(2), // Pass 'candy'. 'type' => MENU_LOCAL_TASK,

);

return $items;

}

function milkshake_overview() {

$output = t('The following flavors are available...'); // ... more code here

return $output;

}

function milkshake_add() {

return t('A handy form to add flavors might go here...');

}

function milkshake_list($type) {

return t('List @type flavors', array('@type' => $type));

}

Figure 4-12 shows the tabbed interface.

86

CHAPTER 4 ■ THE MENU SYSTEM

Figure 4-12. Local tasks and tabbed menus

Hiding Existing Menu Items

Existing menu items can be hidden by changing the hidden attribute of their link item. Suppose you want to remove the “Create content” menu item for some reason. Use our old friend hook_menu_link_alter():

/**

* Implements hook_menu_link_alter(). */

function menufun_menu_link_alter(&$item) { // Hide the Create content link.

if ($item['link_path'] == 'node/add') { $item['hidden'] = 1;

}

}

Using menu.module

Enabling Drupal’s menu module provides a handy user interface for the site administrator to customize existing menus such as the navigation or main menus, and to add new menus. When the menu_rebuild() function in includes/menu.inc is run, the data structure that represents the menu tree is stored in the database. This happens when you enable or disable modules or otherwise mess with things that affect the composition of the menu tree. The data is saved into the menu_router table of the database, and the information about links is stored in the menu_links table.

87