Theming custom e-mail formats for the contacts module

This post is provided to help beginning and intermediate Drupal developers and themers. I sometimes post tips like this when I've finished untangling a knotty problem.

The Drupal core contact module, like many aspects of Drupal, provides only a bare-bones generic feature, leaving it up to the developer/themer to groom its output.

My users know each other by their real name, not by username, and I use the realname module to accomplish that result in most contexts. But realname doesn't convert usernames to real names in the context of a personal contact e-mail (a 'personal contact e-mail' is sent to one user from that user’s page; is is different from the 'site-wide contact e-mail,' but is produced by the same module). The standard personal contact e-mail says it is from a username, which is meaningless to my users. Another problem is that when the sending user asks to receive a copy of the personal contact e-mail, the resulting copy is exactly like the original and does not state to whom it was sent. I would prefer that the copy say something like "You sent the following message to John Smith."

Below, I provide the PHP script that I put in a custom module. The purpose of this custom module is to override how the original contact.module composes its e-mails. You will understand the script better if you take a look inside contact.module and see how that file composes the e-mail message (toward the bottom of the file), and if you take a look inside contact.pages.inc and see how it sends the e-mail messages (again, toward the bottom of the file).

(The contact module is in the core modules folder, in your drupal installation directory. Your custom module will go in the folder sites/all/modules, where all of your other third-party modules live.)

Here is the script, with plenty of tips to steer you along.

----------------------

/* What we're going to do here is override the lines at the end of the contact.module that compose how a personal contact e-mail should look. First, an implementation of hook_mail_alter(). This is a basic technique to modify an e-mail sent by Drupal. Replace 'themename' (the hook) with your theme's name */

function themename_mail_alter(&$message) {

/* First, an ‘if’ statement that grabs the e-mail that's going to the original recipient.  You'll find the clue to the message id in the contact.module file */

if ($message['id'] == 'contact_user_mail') {

     /* Anytime you want to pull info about the acting user (such as uid, name, e-mail) start with this next line. Here, the $user is the sender. */

      global $user;      

   /* Now I want to access the values in the user profile (not nodeprofile, and not in the basic user account, although you can pull those in a similar way) so I use this standard Drupal function. */

      profile_load_profile($user);

   /* You can figure out the names of the values below (such as profile_first and profile_last) in a lot of ways, but I usually just peek into the edit-profile form with Firebug and find the name (not the id) of the field */

      $first = $user->profile_first;
      $last = $user->profile_last;

   /* Next is a piece of code that you steal from the contact.module. The module has already taken information from the input form and put it into $message['params']. Here is where you pull that information out for use. */

      $params = $message['params'];

      $body = $params['message'];
      $subject = $params['subject'];

/* Note that when you retrieve info from a PHP 'object' (such as $user), you describe what you want as $thing->value, but if you retrieve it from a PHP 'array' (such as $message), you describe it as  $thing['name']['value']. When you decode the lines above, you will see that we have extracted $message['params']['message'], which is what the sender put into the contact form, and which we are calling $body. We are about to take that text, modify it some, and put it into $message['params']['body'] so that it can be sent to the recipient. */

/* Now we compose the e-mail, using the info we got from params and the profile info we extracted above. First, tell the e-mail what to put in the message subject. */

      $message['subject'] = $subject;

/* Next, tell the e-mail what to put in the message body. If you look at the original contact.module, you will see that it does this in plain text using an array, with each paragraph a separate value in the array. Here, I use HTML because I send all e-mails with mimemail. */

      $message['body'] = "
         <p>The following message was sent to you by $first $last through the mywebsite.com website:</p>
         <p><strong>Subject:</strong> $subject</p>
         <p><strong>Message:</strong> $body</
      ";

// close the if statement

 }

/* Okay, let's do it again. Now it's time to compose the copy that is sent to the sender if he/she checks the appropriate box. So we use another if statement. */

if ($message['id'] == 'contact_user_copy') {

// This should look familiar (see above)

      $params = $message['params'];

// The params value 'account' is the recipient

      $account = $params['account'];
      $body = $params['message'];
      $subject = $params['subject'];

// Again, this should look familiar (see above)

      profile_load_profile($account);
      $tofirst = $account->profile_first;
      $tolast = $account->profile_last;
      $message['subject'] = $subject;

      $message['body'] = "
         <p>You sent the following message to $tofirst $tolast through the mywebsite.com website:</p>
         <p><strong>Subject:</strong> $subject</p>
         <p><strong>Message:</strong> $body</p>   
      ";

// close the if statement

}

// close the function

}