Integrating phpList 2 with Drupal

Exclusive offer: get 50% off this eBook here
phpList 2 E-mail Campaign Manager

phpList 2 E-mail Campaign Manager — Save 50%

Get to grips with the phpList e-mail announcement delivery system!

$23.99    $12.00
by David Young | July 2011 | Open Source

Drupal is described as a "community publishing system". It has a mature, modular, well-documented "core" of features, providing general content management functions such as content, user, and system management.

Drupal is then extensible through modules, which add features like e-commerce, advanced taxonomy, SEO optimizations, and so on. In this article by David Young, author of phpList 2 E-mail Campaign Manager, we're going to install and configure a module to add phpList integration.

 

PHPList 2 E-mail Campaign Manager

PHPList 2 E-mail Campaign Manager

Get to grips with the PHPList e-mail announcement delivery system!

        Read more about this book      

(For more resources on this subject, see here.)

Prerequisites

For this article, we'll make the following assumptions:

  • We already have a working instance of Drupal (version 6).
  • We are hosting our Drupal site and our phpList site on the same web server and with the same URL base. That is, our Drupal site is accessible at http://yoursite.com and our phpList installation is accessible at http://yoursite.com/lists/.

We chose to document the Drupal-phpList integration using Drupal 6, even though Drupal 7 has recently been released. This is because (a) the phpList module for Drupal 7 is still marked as "development" and (b) Drupal 6 has been the official stable version for three years and has a more familiar interface than 7 at this time.
However, the following method described for Drupal 6 will work on Drupal 7.

Installing and configuring the phpList integration module

Go to http://drupal.org/project/phplist and download the latest stable version of the module for Drupal 6.x. Unpack the tar.gz file and you should have a folder called phplist inside. Upload this folder to your Drupal installation's modules directory and then navigate to Administer | Site building | Modules:

phpList 2 E-mail Campaign Manager tutorial

At the bottom of the modules list, you'll find the Mail and phpList headings with a single phpList module under each. Check both and click on Save configuration:

phpList 2 E-mail Campaign Manager tutorial

External phpList configuration

Navigate to Administer | Site configuration | PHPlist to set up the database credentials and other options required for the integration:

phpList 2 E-mail Campaign Manager tutorial

You are prompted for your phpList database details. Enter your database host, database name, username, and password. Unless you've done a non-standard installation of phpList, the default entries for prefix and user table prefix will already be correct.

Under PHPList URL, enter the URL to your phpList installation. Because we are using phpList and Drupal at the same base URL, we set /lists/ (with a trailing slash) as our PHPList URL:

phpList 2 E-mail Campaign Manager tutorial

The database check illustrated in the preceding screenshot (red text reading Password is not set) is done after you save your settings. The module tries to connect to the phpList database using the details provided and will warn you if it fails.

Scroll to the bottom, ignoring the other options for now, and click on Save configuration:

phpList 2 E-mail Campaign Manager tutorial

If the database connection test was successful, the External PHPList configuration options will be collapsed into a single, clickable field, hiding them from normal view, as you configure the remaining options:

phpList 2 E-mail Campaign Manager tutorial

Attribute mapping

The module can auto-create attributes in phpList to match any attributes created in your Drupal instance. For example, you may ask your Drupal members to enter demographic information when registering and this mapping would allow these details to be transferred to the phpList.

Note that the module warns you that this mapping only works well with textline attributes and not select attributes or radio buttons. Use of this feature is not covered in this article, as it requires advanced pre-configuration of your Drupal instance:

phpList 2 E-mail Campaign Manager tutorial

phpList 2 E-mail Campaign Manager Get to grips with the phpList e-mail announcement delivery system!
Published: July 2011
eBook Price: $23.99
Book Price: $39.99
See more
Select your format and quantity:
        Read more about this book      

(For more resources on this subject, see here.)

My Account – My Newsletters options

The module adds a tab to your My Account page in Drupal, allowing a user to modify their list subscriptions. You can customize several aspects of this page, including:

  • The text to show on the My Newsletters tab
  • The title of the My Newsletters tab itself (that is, you may want it to read "My Subscriptions")
  • Whether or not to show mailing list descriptions (the list description you entered in phpList)
  • Whether to offer the user the choice of HTML or Text e-mail and which one should be the default

phpList 2 E-mail Campaign Manager tutorial

Registration Page options

The module can optionally display a subscription page on the registration page that Drupal shows to prospective members as they register. This would allow new members to select their subscription preferences at the same time as they create their Drupal account. By default, this is disabled:

phpList 2 E-mail Campaign Manager tutorial

Miscellaneous

There are three unclassified options offered under the Miscellaneous heading:

  • Redirect /newsletters to registration: Normally, if an unauthenticated user tries to go to the My newsletters URL in Drupal, they would be presented with a login screen to authenticate. This option replaces this default behavior and, instead, presents them immediately with the registration page.
  • Delete user from PHPList when deleted from Drupal: To keep your phpList database tidy, you may want to automatically delete phpList's version of a user when their Drupal account is deleted.
  • Delay sign-up until first login: This option will leave a subscribed user in a blacklisted state in phpList until they've logged into Drupal for the first time. This is to prevent a malicious user from filling out the registration form on behalf of an unsuspecting victim and having that victim immediately subscribed to your mailing lists.

phpList 2 E-mail Campaign Manager tutorial

Synchronize users to phpList

Normally, synchronization between Drupal and phpList happens when a user initiates the change (that is, they register or they change their subscription preferences). However, as this is the first time the phpList integration has been introduced, you may want to force an immediate synchronization of all existing Drupal users, by checking the Synchronise now checkbox:

phpList 2 E-mail Campaign Manager tutorial

The lower two checkboxes control whether the subscription information (as opposed to simply the user information) will be altered in the synchronization process. You would only conceivably use the Update default subscriptions and Remove existing subscriptions checkboxes if you were working on a clean install without existing users.

Turn on debugging

Enabling the Turn on debugging checkbox will add some debugging status boxes to help identify problems. This should be left disabled unless required.

phpList 2 E-mail Campaign Manager tutorial

Configuring list access

Now that the global integration options are configured, let's configure which Drupal user roles may sign up to which phpList lists.

Under the Administer | Site Configuration | PHPlist page, click on the List access tab. You're prompted to select user access based on roles and the two default Drupal roles (anonymous user and authenticated user) are displayed:

phpList 2 E-mail Campaign Manager tutorial

Expand each role and select (with the checkbox) all the lists that this role is allowed to subscribe to and click on Save settings:

phpList 2 E-mail Campaign Manager tutorial

Remember that Drupal considers unauthenticated users as anonymous and logged-in users as authenticated. If you make some lists accessible to the anonymous user role, but not the authenticated user role, then the logged-in users will be unable to manage their subscription.

Any list marked as optional is available for subscription and any marked as auto-subscribe is subscribed to by default.

Configuring Drupal permissions

Now that we've carried out all the configuration inside the phpList module, we also need to grant permissions to the various phpList functions to user roles in Drupal.

Navigate to Administer | User management | Permissions to assign these permissions:

phpList 2 E-mail Campaign Manager tutorial

You're shown a table of all the available permissions in Drupal, with a column for each user role (by default, anonymous and authenticated).

Scroll down to the phplist module section and grant access lists permission to all the user roles that you want to be able to subscribe to lists. Leave the administer PHPlist and manage subscriptions (of other users) unchecked as these are administrator-only functions:

phpList 2 E-mail Campaign Manager tutorial

phpList 2 E-mail Campaign Manager Get to grips with the phpList e-mail announcement delivery system!
Published: July 2011
eBook Price: $23.99
Book Price: $39.99
See more
Select your format and quantity:
        Read more about this book      

(For more resources on this subject, see here.)

Clearing Drupal's cache

We need to clear Drupal's cache, so that our new newsletters tab will show up in our users' profile management page.

Navigate to Administer | Site configuration | Performance:

phpList 2 E-mail Campaign Manager tutorial

Scroll to the bottom of the Performance page and click on the Clear cached data button to clear the cache:

phpList 2 E-mail Campaign Manager tutorial

Confirming access to My newsletters

Having all the requirements in place, click on your account (My account) and then on the My newsletters tab. You will see the phpList lists that you've made available to the authenticated users role:

phpList 2 E-mail Campaign Manager tutorial

Adding the phpList subscribe block

You might want to use the "block" that the phpList module provides. This will put a subscription form (or a link to your current subscriptions) on the sidebar of every Drupal page.

  1. Navigate to Administer | Site building | Blocks:

    phpList 2 E-mail Campaign Manager tutorial

  2. Here a list of all currently active blocks is displayed section-by-section followed by a list of currently disabled blocks. Change the PHPList subscribe block to Left sidebar to activate it and then click on Save blocks at the bottom of the page to save your changes:

  3. Having reloaded the page after saving, click on the configure link next to the PHPList subscribe block to confirm the configuration:

  4. You can make any phpList-specific changes under the Block specific settings section, including whether or not to include an e-mail confirmation field, whether to include list descriptions, and the option of HTML/Text format:

    phpList 2 E-mail Campaign Manager tutorial

    Drupal also gives you flexible control over the display of the block, including which users may see it, which pages it is displayed on, and so on.

  5. Having saved your block settings, the phpList subscribe block is now visible in the left-hand navigation panel, for an authenticated user, as follows:

    phpList 2 E-mail Campaign Manager tutorial

  6. It is also visible for unauthenticated (anonymous) users, as follows:

    phpList 2 E-mail Campaign Manager tutorial

  7. Once the user is done entering an e-mail and making a list selection, they will receive the following message:

Troubleshooting the phpList subscribe block

There are a few prerequisites for correct functioning of the subscribe block:

  • The phpList URL you entered in the module configuration must be correct
  • The default phpList subscribe page must have no mandatory attributes
  • The phpList language must be English (the module looks for the text Thank you for subscribing to indicate success)

Summary

In this article, you've learned about integrating phpList with the popular publishing platform, Drupal.


Further resources on this subject:


About the Author :


David Young

David Young's first experience in documenting the open source world was the official 2003 manual for JAJC, a popular jabber client, which he authored in XML using Docbook.

He followed this with the development of "Bandersnatch", the whimsically named Jabber message logger, which remains the de facto open source platform for recording and archiving messages on a Jabber server.

After founding and successfully running an open source consulting company ("Funky Penguin") for several years, David "retired" to full-time employment.

David now works for a respected New Zealand IT consulting firm (Prophecy Networks Ltd) and pursues the odd "Funky Penguin" project in his spare time.

David's projects, notes, and ramblings can be found at:
http://www.funkypenguin.co.nz.

Books From Packt


Drupal 7
Drupal 7

Drupal 7 Module Development
Drupal 7 Module Development

Drupal 6 Performance Tips
Drupal 6 Performance Tips

High Availability MySQL Cookbook
High Availability MySQL Cookbook

Mastering phpMyAdmin 3.3.x for Effective MySQL Management
Mastering phpMyAdmin 3.3.x for Effective MySQL Management

PHP 5 E-commerce Development
PHP 5 E-commerce Development

Linux Email
Linux Email

Qmail Quickstarter: Install, Set Up and Run your own Email Server
Qmail Quickstarter: Install, Set Up and Run your own Email Server


No votes yet

Post new comment

CAPTCHA
This question is for testing whether you are a human visitor and to prevent automated spam submissions.
B
5
Y
f
H
t
Enter the code without spaces and pay attention to upper/lower case.
Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software