WordPress Plugin: PHPList Form Integration

PHPList is a excellent open source newsletter manager. However, one missing piece from the application is the ability to cleanly and easily allow users to subscribe to your newsletter from your wordpress blog.

PHPList Subscriber form Embedded in WordPress
Example PHPList Form embedded in WordPress
Code Required to Display
Form

 

This lightweight plugin for WordPress 2.0 to 2.9 gives you the ability to easily allow users to subscribe to your newsletter or RSS blog feed from any page on your blog. Simply install the plug-in, configure your settings, and embed the comment <!--phplist form--> on any page on your blog. It’s easy and fast and does not require any further template modifications in PHPList or WordPress.

 

Table of Contents

  1. Pre-requisites
  2. Download
  3. Quick Start Installation Instructions
  4. Detailed Installation Instructions
  5. Screencast – configuration
    of plugin
  6. Demo
  7. Contact
  8. Change Log
  9. Credits
  10. Future Enhancements
  11. Donations (Link to us)

Pre-requisites

  • WordPress 2.0.x to 3.1
  • Phplist 2.10.2 or greater.
  • PHP 4.x or 5.x with cURL support

Download

Current version of WordPress PHPList Integration plug-in is 1.7

Download
WP PHPLIST

Quick Start Instructions

  1. Download plugin installation and upload phplist.php and phplist.cssto your plug-ins folder, usually /wp-content/plugins
  2. Login to wordpress administration panel and activate the plug-in (Under plug-ins). Plugin name is phplist.
  3. Navigate to Options -> PHPList and fill in the General Settings configuration as instructed. (Optionally, you can configure the form settings as well – see detailed instructions for information)
  4. The last step is to setup the form. If you are adding the subscriber form directly to any post or wordpress page then just add the following comment while inside the wordpress editor:

    <!--phplist form-->


    For more advanced users, who are comfortable editing template files, the form can also be added to any template file. For example most users like to display the subscriber form in their sidebar.php. To do this open up the template page (i.e. sidebar.php) and add the following code:

    <?php
                $content = apply_filters('the_content', '<!--phplist form-->');
                echo $content;?> 

Detailed Installation Instructions

  1. Download the ZIP installation file, and upload phplist.php and phplist.css to your plug-ins folder ( /wp-content/plugins)
  2. Login to wordpress administration panel and activate the plug-in (Under plug-ins). Plugin name is phplist.
  3. Click on Options -> PHPlist to configure PHPList

  4. Settings are divided up into General Settings and Form Settings. Starting with General settings, set the following:
    1. PHPList URL: Set this to the url of base installation of the domain where you are hosting PHPList. If the installation folder is password protected then the format of the url should be:

      http://username:password@yoursite.com/lists/

    2. PHPList Admin Login: Enter the user name of the PHPList Admin.
      The user/pass of the admin is needed in order to optionally bypass the need to confirm the user.
    3. PHPList Admin Password: Enter the password of the PHPList Admin.
    4. PHPList List Information: In this table enter the number (i.e. PHPList ID) and name of the mailing list you want to subscribe the user too. The name of the list can be whatever you want – it will be displayed on the form in the case when you have more then one list added.

      Phplist

      NOTE: To figure out the correct number (i.e. PHPList ID) for your mailing list, login to PHPList admin and click on Lists for a current list of lists. (http://www.yoursite.com/lists/admin/?page=list)
      Each list is assigned a number which should be entered in this List ID field. See example below

      Note: If you want to give the user the option of subscribing to multiple lists click on the "Add Another List" button to add another row:

      If you have multiple lists configured the form would look similar to this:

    5. Skip Confirmation Email: Check this option to
      automatically confirm the user without the need for a confirmation
      email.
  5. The Form Settings shows the two fields available for the subscribe form. The optional first row is modifiable and allows you to enter any type of text field required. Ideally it should correspond with a field you are already capturing through the PHPList Subscriber Page.
    1. Show on Form: Check this option to show the Optional Field on the subscriber form.
    2. Text Label Name: Enter the label of the field that you want to appear on the subscriber form.
    3. Text Field ID: In order to successfully write the field value to the correct value in the PHPList database you have to get the ID of the field from PHPList. Each attribute in PHP takes the form ‘attribute[X]’ where X is a integer. To determine the corresponding integer go to the Active Subscriber Page within PHPList – http://www.yoursitename.com/lists/admin/?page=spage. Locate the active subscriber page and click edit. Once the subscriber page loads, locate the attribute you are using and find its number:

    4. Text Field Size: Enter the size of the text field box
    5. Text Field Max Size: Enter the maximum size of the text entered by the user
    6. Required Field: Check this box if the field should be required.
  6. Now that the form has been customized, open up any post or page using the wordpress editor and add the following comment to enable the subscriber form:

    <!--phplist form-->

    For more advanced users, who are comfortable editing wordpress template files, the form can also be added to any wordpress template file. For example most users like to display the subscriber form in their sidebar.php. To do this open up the template page (i.e. sidebar.php) and add the following code:

    <?php
                $content = apply_filters('the_content', '<!--phplist form-->');
                echo $content;?> 

    This code should be positioned in the location where you want the form to appear. Typically, you should make sure to include it within the main <DIV> tags for the form.

  7. Edit the css in phplist.css to customize the look and feel of the form

    Note: For advanced users wishing to add additional fields to their form (beyond the two that are provided) see my post on adding additional fields.

Troubleshooting

Question:The plugin is not submitting the user information to the database. Why?

Answer: Steve James comment has helped a lot of people with this issue. Here it is:

For anyone who has everything set up, but the plugin does not actually submit to the database, make sure of one thing. Remember, whatever REQUIRED fields you have in a PHPList “subscribe page” needs to be mimicked in the plugin.

I made the mistake of requiring a name, city and state in my “subscribe page” in PHPList but only required the name in the plugin. The result was that the plugin appeared to submit the data but it never made it to the database because of the “required fields” not matching between PHPList and the plugin.

Demo

See demo at bottom of this post.

Contact

I do not provide support for this plugin. From time to time I will respond to comments. Read comments below for common issues with plugin

Change Log

Version 1.0 – Initial Version

Version 1.01 – Added check to ensure user has entered trailing slash for the PHPList URL. If no trailing slash is found, the slash is appended to the end of the URL.

Version 1.02 (10/8/2006) – Minor tweak to support displaying subscriber form in any template page.

Version 1.2 (1/13/2007) – Changed way script stores options to prevent clashes with other plugins. Moved CSS to seperate file – phplist.css. CSS can now be toggled on or off

Version 1.3 (1/28/2007) – Fixed form display problem in WP 2.1. Full compatibly with WP 2.1

Version 1.4 (10/22/2007) – Fixed X S S vulnerability. Thanks to Gordon for the find.

Version 1.5 (3/16/2008) – Now with multiple list support!

Version 1.6 (7/18/2009) – Now with widget support (FINALLY). Thanks to Rob Z at Web Geek Blog

Version 1.7 (11/21/2009) – Now with Internationalization Support (French & English). Thanks to Le Foie gras

Credits

Credits to Ryan Duff, creator of WordPress Contact form plug-in, for some of the base code I used for detecting spam and the flexible design idea for dropping the subscriber form on any wordpress page.

Future Enhancements

  • Currently, this version only supports a simple subscriber form which supports an email and one optional text field. In the future, I’ll look to add support for multiple fields. Ideally, the plugin could interface directly with PHPList and grab the form structure.
  • Take a class based approach to facilitate future enhancements
  • Explore using wordpress widgets for displaying subscriber form

Donations (Link to us)

If you use this script and find it worthwhile please link back to our main site. While we enjoy releasing scripts to the general community, we also look to benefit by drawing more traffic to our site. Feel free to link back however you want – here is a guideline:

J J. Heap & Son – Manufacturers and distributors of a wide variety of labor saving devices and factory automation technologies including dye sublimation equipment, Heat transfer machines, Fusing Machines, So-Fast Cutting Equipment, Material Handling Equipment and an inventory of rebuilt machines.