In the first part of this series of posts we created a PHP class that interacted with the dotMailer API. Now that we have this class we will look at how to integrate it into specific areas of Drupal so that we can add users to the dotMailer system.
User Logon
The best (or most obvious place) to start integrating this class is when the user logs into their account, where the user will be either created or updated on dotMailer. All we need to do here is hook into Drupal using the hook_user_login() hook and send the user's contact information over to dotMailer. We first need to create a generic function that we can use to send our dotMailer data. The following function takes the user object, creates an array of custom fields and sends the data over to dotMailer using the UpdateContact method. The email address of the user is used as a universal identifier in the dotMailer system and is the only required field in the contact.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | function MODULE_NAME_dotmailer_update_contact($user) { if (!class_exists('DotMailer')) { // load the dotMailer class if it hasn't been already module_load_include('php', 'MODULE_NAME', 'includes/DotMailer'); } $fields = array(); $fields['LAST-LOGGED-IN'] = date('Y-m-d\TH:i:s', $user->access); $fields['WEB-USER-ID'] = $user->uid; // Send to dotmailer as a contact $dotmailer = new DotMailer('[email protected]', 'password'); $contact = array( 'Email' => $user->mail, ); return $dotmailer->UpdateContact($contact, $fields); } |
Those of your familiar with dotMailer will realise that we can't use the UpdateContact method with a user who doesn't exist. If the user doesn't already exist in dotMailer then don't then dotMailer will return an ERROR_CONTACT_NOT_FOUND error. To prevent this we can easily wrap the UpdateContact method in a simple check using the GetContactByEmail method and then use the CreateContact method to create the contact if the contact isn't found. Here is a more robust way of posting user data to dotMailer.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | function MODULE_NAME_dotmailer_update_contact($user) { if (!class_exists('DotMailer')) { // load the dotMailer class if it hasn't been already module_load_include('php', 'MODULE_NAME', 'includes/DotMailer'); } $fields = array(); $fields['LAST-LOGGED-IN'] = date('Y-m-d\TH:i:s', $user->access); $fields['WEB-USER-ID'] = $user->uid; // Send to dotmailer as a contact $dotmailer = new DotMailer('[email protected]', 'password'); $contact = array( 'Email' => $user->mail, ); $contact = $dotmailer->GetContactByEmail($user->email); if ($contact === FALSE) { return $dotmailer->CreateContact($contact, $fields); } else { return $dotmailer->UpdateContact($contact, $fields); } } |
With this in place we can create our login hook. All we need to do is pass the user object to the function and it does the rest.
1 2 3 | function MODULE_NAME_user_login(&$edit, $account) { MODULE_NAME_dotmailer_update_contact($account); } |
This will allow us to capture their basic details, but we are also passing the login time and uid to dotMailer as custom fields. These are non-standard fields that you will need to create yourself within the dotMailer backend. We are passing the user's last login time as we can use this in the future to send a reminder email to users who haven't logged in for a while. It is possible to send any number of custom fields to dotMailer, you just need to create them in dotMailer and add it to the array above.
User Saves Profile Page
Another place that is a good candidate to integrate dotMailer is when the user saves their profile page. All we would need to do here is hook into the profile form and update the users details to dotMailer. For the following example we will use the Profile2 module, but the basic functionality is the same for fields added directly to the user entity.
The first step is to create a hook_form_form-id_alter() hook to add an additional submit function to our profile form. We don't need to overwrite any existing submit functions, just add our own. In the code below the normal submit function will trigger and then ours will trigger immediately after.
1 2 3 4 | function MODULE_NAME_form_user_profile_form_alter(&$form, &$form_state) { $form['#submit'][] = 'MODULE_NAME_profile_update'; return $form; } |
The submit function we create loads the user object and passes this onto the the dotMailer wrapper function.
1 2 3 4 5 6 7 8 9 10 | function MODULE_NAME_profile_update($form, &$form_state) { if (!isset($form_state['values']['uid']) && !is_numeric($form_state['values']['uid'])) { return; } // Load the user $user = user_load($form_state['values']['uid']); MODULE_NAME_dotmailer_update_contact($user); } |
Now we just need to load the user profile, collate the field data we need into an array, and send this over to dotMailer. Each field we need is loaded using the field_get_items() function and placed into an array of fields. The following example assumed you have created two fields in Profile2 named field_first_name and field_last_name.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 | function MODULE_NAME_dotmailer_update_contact($user) { if (!class_exists('DotMailer')) { // load the dotMailer class if it hasn't been already module_load_include('php', 'MODULE_NAME', 'includes/DotMailer'); } $user_profile = current(profile2_load_by_user($user)); $fields = array(); if ($user_profile) { // Grab the needed fields from the Profile2 object. $fields = array(); $first_name = field_get_items('profile2', $user_profile, 'field_first_name'); if (isset($first_name[0]['safe_value'])) { $fields['FIRSTNAME'] = $first_name[0]['safe_value']; } $last_name = field_get_items('profile2', $user_profile, 'field_last_name'); if (isset($last_name[0]['safe_value'])) { $fields['LASTNAME'] = $last_name[0]['safe_value']; } } $fields['LAST-LOGGED-IN'] = date('Y-m-d\TH:i:s', $user->access); $fields['WEB-USER-ID'] = $user->uid; // Send to dotmailer as a contact $dotmailer = new DotMailer('[email protected]', 'password'); $contact = array( 'Email' => $user->mail, ); $contact = $dotmailer->GetContactByEmail($user->email); if ($contact === FALSE) { return $dotmailer->CreateContact($contact, $fields); } else { return $dotmailer->UpdateContact($contact, $fields); } } |
The CreateContact and UpdateContact methods might add or alter user information to dotMailer, but those users will not be contained in any address books. You can either rely on your dotMailer users to do this or you can use the AddContactToAddressBook method to add the contact to the dotMailer system and an address book at the same time. To use AddContactToAddressBook you just need to know the email address of the user and the ID of the dotMailer address book.
Webform Integration
Perhaps the most popular way of integrating this class into Drupal might be through the webform module. This module allows users to create and modify a node that contains a form on a Drupal site. Assuming that we have created a node with the nid of 1 we can alter the submit function using another HOOK_form_form-id_alter() hook.
1 2 3 4 5 6 | /** * Implements HOOK_form_form-id_alter(). */ function MODULE_NAME_form_webform_client_form_1_alter(&$form, &$form_state) { $form['#submit'][] = 'MODULE_NAME_webform_1_dotmailer_subission'; } |
With this in place we can then create a submission function that collates the submitted information and sends this over to dotMailer. This is an easy way to create a newsletter sign up form in only a few minutes. We can't reuse the dotMailer wrapper function we created earlier because we are dealing with webform form data and user's who might not have an account.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 | /** * Additional submit function for webform 1. * * @param array $form The form. * @param array $form_state The state of the submitted form. */ function MODULE_NAME_webform_1_dotmailer_subission($form, &$form_state) { // Get email address. $email = $form_state['input']['submitted']['email']; $fields = array(); // Collate fields if (isset($form_state['input']['submitted']['FORENAME'])) { $fields['FORENAME'] = $form_state['input']['submitted']['FORENAME']; } if (isset($form_state['input']['submitted']['LASTNAME'])) { $fields['LASTNAME'] = $form_state['input']['submitted']['LASTNAME']; } if (!class_exists('DotMailer')) { // load the dotMailer class if it hasn't been already module_load_include('php', 'MODULE_NAME', 'includes/DotMailer'); } $dotmailer = new DotMailer('username', 'password'); $contact = $dotmailer->GetContactByEmail($email); if ($contact === FALSE) { $dotmailer->CreateContact($contact, $fields); } else { $dotmailer->UpdateContact($contact, $fields); } } |
These are only a couple of examples of how to integrate the dotMailer class into Drupal, but sending the data for single users over to dotMailer is pretty easy. In the next post we will look at how to report on some of the information that dotMailer provides.
