CHAPTER 2 ■ WRITING A MODULE

Since we didn’t implicitly perform any database operations, you might be wondering where Drupal stored and retrieved the value for our annotation field. The Field API handles all of the behind-the- scenes work of creating the table to hold the value, plus storing and retrieving the value on node save and node load. When you call the Field API’s field_create_field() function, it handles the creation of a table in the Drupal database using a standard naming convention of field_data_<fieldname>. In the case of our annotations field, the name of the table is field_data_annotations. We’ll cover additional details about the Field API in Chapter 4.

Defining Your Own Administration Section

Drupal has several categories of administrative settings—such as content management and user management—that appear on the Configuration page. If your module needs a category of its own, you can create that category easily. In this example, we created a new category called “Node annotation.” To do so, we used the module’s menu hook to define the new category:

/**

* Implementation of hook_menu(). */

function annotate_menu() { $items['admin/config/annotate'] = array(

'title' => 'Node annotation',

'description' => 'Adjust node annotation options.', 'position' => 'right',

'weight' => -5,

'page callback' => 'system_admin_menu_block_page',

'access arguments' => array('administer site configuration'), 'file' => 'system.admin.inc',

'file path' => drupal_get_path('module', 'system'),

);

$items['admin/config/annotate/settings'] = array( 'title' => 'Annotation settings',

'description' => 'Change how annotations behave.', 'page callback' => 'drupal_get_form',

'page arguments' => array('annotate_admin_settings'), 'access arguments' => array('administer site configuration'), 'type' => MENU_NORMAL_ITEM,

'file' => 'annotate.admin.inc',

);

return $items;

}

The category on the Configuration page with our module’s setting link in it is shown in Figure 2-4.

25

CHAPTER 2 ■ WRITING A MODULE

Figure 2-4. The link to the annotation module settings now appears as a separate category.

If you ever modify code in the menu hook, you’ll need to clear the menu cache. You can do this by truncating the cache_menu table or by clicking the “Rebuild menus” link that the Drupal development module (devel.module) provides or by using the “Clear cached data” button by visiting the Configuration page and clicking the Performance link.

■ Tip The development module (http://drupal.org/project/devel) was written specifically to support Drupal development. It gives you quick access to many development functions, such as clearing the cache, viewing variables, tracking queries, and much more. It’s a must-have for serious development.

We were able to establish our category in two steps. First, we added a menu item that describes the category header. This menu item has a unique path (admin/config/annotate). We declare that it should be placed in the right column with a weight of -5, because this places it just above the “Web Services” category, which is handiest for the screenshot shown in Figure 2-3.

The second step was to tell Drupal to nest the actual link to annotation settings inside the “Node annotation” category. We did this by setting the path of our original menu item to admin/config/ annotate/settings. When Drupal rebuilds the menu tree, it looks at the paths to establish relationships among parent and child items and determines that, because admin/config/annotate/settings is a child of admin/config/annotate, it should be displayed as such.

Drupal loads only the files that are necessary to complete a request. This saves on memory usage. Because our page callback points to a function that is outside the scope of our module (i.e., the function system_admin_menu_block_page() in system.module), I need to tell Drupal to load the file modules/system/system.admin.inc instead of trying to load sites/all/modules/custom/annotate/ system.admin.inc. We did that by telling Drupal to get the path of the system module and put the result in the file path key of our menu item.

Of course, this is a contrived example, and in real life, you should have a good reason to create a new category to avoid confusing the administrator (often yourself!) with too many categories.

Presenting a Settings Form to the User

In the annotate module, we gave the administrator the ability to choose which node types would support annotation (see Figure 2-1). Let’s delve into how this works.

26

CHAPTER 2 ■ WRITING A MODULE

When a site administrator wants to change the settings for the annotate module, we want to display a form so the administrator can select from the options we present. In our menu item, we set the page callback to point to the drupal_get_form() function and set the page arguments to be an array containing annotate_admin_settings. That means that when you go to http://example.com /?q=admin/config/annotate/settings, the call drupal_get_form('annotate_admin_settings') will be executed, which essentially tells Drupal to build the form defined by the function annotate_admin_settings().

Let’s take a look at the function defining the form, which defines a check box for node types (see Figure 2-1), and add two more options. The function is in sites/all/modules/custom/annotate/ annotate.admin.inc:

/**

*Form builder. Configure annotations.

*@ingroup forms

*@see system_settings_form().

*/

function annotate_admin_settings() {

//Get an array of node types with internal names as keys and

//"friendly names" as values. E.g.,

//array('page' => 'Basic Page', 'article' => 'Articles')

$types = node_type_get_types(); foreach($types as $node_type) {

$options[$node_type->type] = $node_type->name;

}

$form['annotate_node_types'] = array( '#type' => 'checkboxes',

'#title' => t('Users may annotate these content types'), '#options' => $options,

'#default_value' => variable_get('annotate_node_types', array('page')), '#description' => t('A text field will be available on these content types to make user-specific notes.'),

);

$form['annotate_deletion'] = array( '#type' => 'radios',

'#title' => t('Annotations will be deleted'),

'#description' => t('Select a method for deleting annotations.'), '#options' => array(

t('Never'),

t('Randomly'), t('After 30 days')

),

'#default_value' => variable_get('annotate_deletion', 0) // Default to Never

);

27

CHAPTER 2 ■ WRITING A MODULE

$form['annotate_limit_per_node'] = array( '#type' => 'textfield',

'#title' => t('Annotations per node'),

'#description' => t('Enter the maximum number of annotations allowed per node (0 for no limit).'),

'#default_value' => variable_get('annotate_limit_per_node', 1), '#size' => 3

);

$form['#submit'][] = 'annotate_admin_settings_submit'; return system_settings_form($form);

}

We add a radio button to choose when annotations should be deleted and a text entry field to limit the number of annotations allowed on a node (implementation of these enhancements in the module is left as an exercise for you). Rather than managing the processing of our own form, we call system_settings_form() to let the system module add some buttons to the form and manage validation and submission of the form. Figure 2-5 shows what the options form looks like now.

Figure 2-5. Enhanced options form using check box, radio button, and text field options

28