The core Drupal system provides a facility called Actions. These can be thought of as a packaged series of tasks that are automatically carried out by the system when triggered, or when required conditions are met. It is a digitized stimulus-response mechanism, if you will. Such automated actions are also referred to as robots.

Webform provides a method for us to add actions that can be triggered from the submission View and Edit pages. An example of such an action was covered in the Resending e-mails section discussed in Chapter 3, Working with Submissions. This action appears above the Submission information textarea on the submission View and Edit pages.

When we click on the Resend e-mails action link we are taken to a confirmation page that enables us to selectively resend pre-configured e-mails.

In this chapter we are going to build a similar action of our own, demonstrating yet more of the power and convenience provided by Drupal, Webform, and their respective APIs. The programming of the action will reside in a new Webform extension module. As before, some knowledge of the PHP programming language is assumed.

In order to provide a context for our example we return to the world of the Fictitious Conference Speaker Registration form that has set the scene for so much of this book.

Our conference organizers have determined that the speaker registration drive has been too successful and the list of speakers now requires some pruning. They have asked us to provide a mechanism whereby one of the administrators can decline a speaker registration and have the system automatically send an e-mail to the speaker, notifying them that their presentation will unfortunately not form a part of the conference program.

Adding some spice to the request, the conference organizers have indicated that the users who will carry out the pruning activity are users who have the Access all webform results permissions (see People - Permissions), but who do not have the Edit all webform submissions access. In other words, these users may see submitted data, but cannot make changes to the submitted data.

Also, because of the delicacy surrounding such a rejection on the part of the organizers, they are rather keen to ensure that a speaker can only be declined once. It would be bad for the reputation of the conference if a speaker were to receive two or more rejections because the same speaker was declined by more than one user.

It may sound like a fairly complicated request, but it actually breaks down quite simply. We are going to add a new private select component to our Speaker Registration form as a status field, which will indicate whether that submission has been declined or not. Next we will create a new module to handle the action of flagging a submission as declined and sending an automated notification e-mail.

Based on the value in our new status field, the module will decide whether or not to display the Decline speaker action. When the users view a submission which has not yet been declined and click upon the action, they will be taken to a form where they can confirm that they do, indeed, wish to decline this particular submission. After clicking the button on the confirmation form, the module will update the submission to reflect its declined status and then send a notification e-mail to the speaker. The next user who views that particular submission will not see the Decline speaker action.