CHAPTER 3 ■ HOOKS, ACTIONS, AND TRIGGERS
We’ve described our action to Drupal, so let’s go ahead and write it:
/**
* Simulate a beep. A Drupal action. */
function beep_beep_action() { beep_beep();
}
That wasn’t too difficult, was it? Before continuing, go ahead and delete beep_user_login() and beep_node_insert(), since we’ll be using triggers and actions instead of direct hook implementations.
Assigning the Action
Now, let’s click the Structure link in the top menu, and on the Structure page, click the Triggers link. If you’ve done everything correctly, your action should be available in the user interface, as shown in Figure 3-2.
Figure 3-2. The action should be selectable in the triggers user interface.
39
Download from Wow! eBook <www.wowebook.com>
CHAPTER 3 ■ HOOKS, ACTIONS, AND TRIGGERS
Assign the action to the trigger associated with saving new content by selecting “Beep annoyingly” from the drop-down list and clicking the Assign button. Next create a new Basic page content item and save it. After saving click the Reports link at the top of the page and select the Recent log entries report. If you set up the action and trigger properly, you should see results similar to Figure 3-3.
Figure 3-3. The results of our beep action being triggered on node save is an entry in the log file.
Changing Which Triggers an Action Supports
If you modify the values that define which operations this action supports, you should see the availability change in the user interface. For example, the “Beep” action will be available only to the “After deleting a node” trigger if you change beep_action_info() as follows:
/**
*Implemenation of hook_action_info(). */
function beep_action_info() { return array(
'beep_beep_action' => array( 'type' => 'system',
'label' => t('Beep annoyingly'), 'configurable' => FALSE,
'triggers' => array('node_delete'), ),
);
}
Actions That Support Any Trigger
If you don’t want to restrict your action to a particular trigger or set of triggers, you can declare that your action supports any trigger:
/**
*Implementation of hook_action_info(). */
function beep_action_info() { return array(
'beep_beep_action' => array( 'type' => 'system',
'label' => t('Beep annoyingly'), 'configurable' => FALSE,
40
CHAPTER 3 ■ HOOKS, ACTIONS, AND TRIGGERS
'triggers' => array('any'), ),
);
}
Advanced Actions
There are essentially two kinds of actions: actions that take parameters and actions that do not. The “Beep” action we’ve been working with does not take any parameters. When the action is executed, it beeps once and that’s the end of it. But there are many times when actions need a bit more context. For example, a “Send e-mail” action needs to know to whom to send the e-mail and what the subject and message are. An action like that requires some setup in a configuration form and is called an advanced action or a configurable action.
Simple actions take no parameters, do not require a configuration form, and are automatically made available by the system. You tell Drupal that the action you are writing is an advanced action by setting the configurable key to TRUE in your module’s implementation of hook_action_info(), by providing a form to configure the action, and by providing an optional validation handler and a required submit handler to process the configuration form. The differences between simple and advanced actions are summarized in Table 3-3.
Table 3-3. Summary of How Simple and Advanced Actions Differ
|
Simple Action |
Advanced Action |
|
|
|
Parameters |
No* |
Required |
Configuration form |
No |
Required |
Availability |
Automatic |
Must create instance of action using actions |
|
|
administration page |
Value of configure key in |
FALSE |
TRUE |
hook_action_info() |
|
|
*The $object and $context parameters are available if needed.
Let’s create an advanced action that will beep multiple times. We will be able to specify the number of times that the action will beep using a configuration form.
First, we will need to tell Drupal that this action is configurable. Let’s add an entry for our new action in the action_info hook implementation of beep.module:
/**
*Implementation of hook_action_info(). */
function beep_action_info() { return array(
'beep_beep_action' => array( 'type' => 'system',
'label' => t('Beep annoyingly'),
41
CHAPTER 3 ■ HOOKS, ACTIONS, AND TRIGGERS
'configurable' => FALSE,
'triggers' => array('node_view', 'node_insert', 'node_update', 'node_delete'),
),
'beep_multiple_beep_action' => array( 'type' => 'system',
'label' => t('Beep multiple times'), 'configurable' => TRUE,
'triggers' => array('node_view', 'node_insert', 'node_update', 'node_delete'),
),
);
}
Let’s quickly check if we’ve done the implementation correctly at Administer -> Site configuration - > Actions. Sure enough, the action should show up as a choice in the advanced actions drop-down select box, as shown in Figure 3-4.
Figure 3-4. The new action appears as a choice.
42
CHAPTER 3 ■ HOOKS, ACTIONS, AND TRIGGERS
Now, we need to provide a form so that the administrator can choose how many beeps are desired. We do this by defining one or more fields using Drupal’s form API. We’ll also write functions for form validation and submission. The names of the functions are based on the action’s ID as defined in hook_action_info(). The action ID of the action we are currently discussing is beep_multiple_ beep_action, so convention dictates that we add _form to the form definition function name to get beep_multiple_beep_action_form. Drupal expects a validation function named from the action ID plus _validate (beep_multiple_beep_action_validate) and a submit function named from the action ID plus
_submit (beep_multiple_beep_action_submit).
/**
* Form for configurable Drupal action to beep multiple times */
function beep_multiple_beep_action_form($context) { $form['beeps'] = array(
'#type' => 'textfield', '#title' => t('Number of beeps'),
'#description' => t('Enter the number of times to beep when this action executes'), '#default_value' => isset($context['beeps']) ? $context['beeps'] : '1', '#required' => TRUE,
);
return $form;
}
function beep_multiple_beep_action_validate($form, $form_state) { $beeps = $form_state['values']['beeps'];
if (!is_int($beeps)) {
form_set_error('beeps', t('Please enter a whole number between 0 and 10.'));
}
else if ((int) $beeps > 10 ) {
form_set_error('beeps', t('That would be too annoying. Please choose fewer than 10 beeps.'));
} else if ((int) $beeps < 0) {
form_set_error('beeps', t('That would likely create a black hole! Beeps must be a positive integer.'));
}
}
function beep_multiple_beep_action_submit($form, $form_state) { return array(
'beeps' => (int)$form_state['values']['beeps']
);
}
The first function describes the form to Drupal. The only field we define is a single text field so that the administrator can enter the number of beeps. To access the advanced actions form, click the Configuration link at the top of the page, and on the Configuration page, click the Actions link. On the Actions page, scroll to the bottom of the page, and in the Create an Advanced action select list, click the “Beep multiple times” item. After selecting the item, Drupal displays the advanced actions form, as shown in Figure 3-5.
43
CHAPTER 3 ■ HOOKS, ACTIONS, AND TRIGGERS
Figure 3-5. The action configuration form for the “Beep multiple times” action
Drupal has added a Description field to the action configuration form. The value of this field is editable and will be used instead of the default description that was defined in the action_info hook. That makes sense, because we could create one advanced action to beep two times and give it the description “Beep two times” and another that beeps five times with the description “Beep five times.” That way, we could tell the difference between the two advanced actions when assigning actions to a trigger. Advanced actions can thus be described in a way that makes sense to the administrator.
■ Tip These two actions, “Beep two times” and “Beep five times,” can be referred to as instances of the “Beep multiple times” action.
The validation function is like any other form validation function in Drupal (see Chapter 11 for more on form validation). In this case, we check to make sure the user has actually entered a number and that the number is not excessively large.
The submit function’s return value is special for action configuration forms. It should be an array keyed by the fields we are interested in. The values in this array will be made available to the action when it runs. The description is handled automatically, so we need only to return the field we provided, that is, the number of beeps.
44