Drupal 7 Module Development

Chapter 5
Forms generated by confirm_form() only call their submit functions if the form
is actually confirmed, so developers don't need to check for this themselves. If the
form is canceled, then the user is simply redirected to the URL specified in the
function call.
We have now gotten a pretty thorough introduction to Drupal's Form API. We
can create forms from scratch, write, validate, and submit handlers, and use some
of Drupal's internal functions to create common form types. We're two-thirds of
the way into this chapter and we still haven't touched on the module's central
purpose—sending an e-mail to a user!
Sending mail with drupal_mail() and
hook_mail()
Drupal implements a custom e-mail templating system. Initially it may appear that
this system is overly complicated, but it allows an enormous amount of flexibility
for module developers.
Sending e-mail in Drupal is a multi-step process:
1. drupal_mail() is called, specifying what mail is being sent and what
options are unique to this specific message (the recipient's e-mail address, the
language the mail should be sent in, and so on).
2. Drupal then builds an e-mail message with standard headers combined with
the information submitted to drupal_mail().
3. The hook_mail() implementation specified in drupal_mail() is called. This
is where the subject and body of the mail are added.
4. The fully composed mail array is then passed to hook_mail_alter(),
allowing other modules to modify it (for instance, to add a common
signature to all outgoing e-mails.).
5. The mail is passed to drupal_send_mail() for delivery.
That is a pretty long process just for sending a simple e-mail! However, in most
cases developers will only have to worry about two of the above steps—calling
drupal_mail() and implementing hook_mail().
[ 141 ]