Creating Email Newsletters with patNewsletter (part 1)

Letters Of The Rich And Famous

This is really based on a true story.

Many years ago, my friend and I wanted to start a newsletter, blast it across the Internet, make lots of money, become rich and famous. But soon, bitter reality struck, and we realized that it was no child’s play to manage a newsletter.

Our first problem was managing the content: while we had tons of information, we did not have any way to organize and manage it for our newsletter. And after we just about managed to put an issue to bed, we would again struggle with the user subscription process. At the end, we gave up and decided to do it manually - interested subscribers could send us email opting in and so could the not-so-interested ones, if they wanted to opt out. Thankfully, there weren’t many in the second category!

The last straw involved sending the newsletter to the subscribers. Back then, we did not have the skills to write a script to automate this task, so we had to come up with something simple. After brainstorming for hours, we decided to break up our large subscriber list into smaller “batches” and BCC the newsletter to each subscriber…not an efficient (or elegant) solution at all!

Fast forward to the present. We have since stopped publishing the newsletter and moved on to bigger things…but any solution to our early problems always gets our attention! And patNewsletter - our topic of discussion today - might just have been the answer to our teething problems back then.

Know Your Application

patNewsletter is a PHP-based application described, in the author’s words, as “a powerful newsletter management tool with a subscription and administration interface”. Developed by Stephan Schmidt, it is freely available for download and is packaged as a single PHP application that you can have up and running in no time at all.

Some of patNewsletter’s more interesting features include quick installation and configuration, management of multiple newsletters from a single interface, personalization of the newsletter by its subscribers, and a readymade framework for users to manage their subscription. That’s not all - you can also broadcast “announcements” to all subscribers without much fuss (a good way to send out breaking news) and use the built-in template support to customize the layout of the newsletter quickly.

patNewsletter can easily be integrated with your Web site, as it comes with a form to manage user subscriptions. After our initial experiences many years ago, I can tell you that this feature alone is worth the price of admission - it can substantially reduce the amount of time you spend managing your newsletter. You’ll find it functional, powerful and (if you’re the kind who likes fiddling) easy to customize, and it’ll soon be the de facto solution to your email newsletter problems.

Start Me Up

In order to get started with patNewsletter, you’ll need a working PHP installation (I’m currently running PHP 4.2.3), a MySQL database server (I’m running MySQL 4.0.10), and a copy of the latest release (version 0.92) of the package; you can download a copy from http:// http://www.php-tools.de/.

Setting up the package is pretty simple. The first step is to uncompress the source archive into a directory under your Web server (mine is called “medusa” here) root.

$ cd /usr/local/apache/htdocs/

$ tar -xzvf /tmp/patNewsletter.tar.gz

When you uncompress the source archive, you should see a directory structure that looks something like this:

patNewsletter
|
|
| --- admin
| --- config
| --- doc
| --- include
| --- sql
| --- templates

Once you’ve got the files in an appropriate location, you also need to create some database tables to store patNewsletter data. Since the database must exist before the software can be installed, you need to create one (say “pattools”) together with a special MySQL user having rights over the “pattools” database. So, fire up that MySQL prompt and execute the following commands:

mysql> CREATE DATABASE `pattools`;
Query OK, 1 row affected (0.00 sec)

This should create a database called “pattools”

You can verify that the database has been created using the “SHOW DATABASES” command.

Now that we have the database, let’s create a MySQL user with appropriate permissions.

mysql> GRANT SELECT ,  INSERT ,  UPDATE , DELETE , CREATE , DROP , INDEX ,
ALTER ON `pattools` . * TO "pattoolsuser"@"pattoolsuser" IDENTIFIED BY "pattoolsuser";
Query OK, 0 rows affected (0.00 sec)

This will create a MySQL user with the username “pattoolsuser” and with the appropriate permissions to manage the “pattools” database.

Now, look in the source archive’s “sql/” directory, where you’ll find an SQL script (“patNewsletter.sql”) to create the required tables.

$ mysql -u root -p pattools < /usr/local/apache/htdocs/patNewsletter/sql/patNewsletter.sql

This command will create the required tables in the “pattools” database.

Setting It Up

Next up, configuration. patNewsletter configuration is handled via a single file named “newsletter.php”, located in the source distribution’s “config/” directory. It’s fairly self-explanatory, take a look:

<?php

/**
*	patNewsletter Config
*/

//	Database configuration
$db_host = "localhost";
$db_name = "pattools";
$db_user = "pattooluser";
$db_pass = "pattooluser";

// Directory where the templates for subscription pages are stored
$template_dir =	"templates";
// Directory where the templates for the administration are stored
$admin_template_dir = "templates";

?>

Most of this is pretty standard information - patNewsletter needs to know the database access parameters so that it can get to its tables, and the location of the directories containing screen templates for the newsletter administration module and the newsletter itself (these templates are used by the patTemplate engine to render each page of the application, and can be customized to your needs - more on this later).

If you’re using the default installation, you shouldn’t need to change any of the information in this file, except the database access parameters. If, on the other hand, you’re not using the default installation paths, you should also alter the directory locations in the configuration file to reflect where the templates are located.

You can now check to see if patNewsletter is up and running, by visiting the URL (remember to alter this as per the installation path on your system) http://localhost/patNewsletter/admin/newsletter.php

patNewsletter should load up and display the following screen:

Not impressed? Well, let’s proceed to create a newsletter and see if you change your mind.

Hole In The Ground

Before we get started, it is essential to understand how patNewsletter allows you to build your newsletter. Simply put, a newsletter is at the top level of the content hierarchy. Each newsletter is further broken down into topics, which constitute the different subsections of the newsletter. Thus the newsletter, along with its topics, represents the skeleton of the final product.

Each issue of a newsletter is made up of a set of articles. Each article is associated with one of the topics of the newsletter.

You create an issue of a newsletter by associating articles with the topics defined for the newsletter.

Let’s see how this works in practice. Start up patNewsletter again, and use the “New Newsletter” option to see the following screen:

This screen allows you to define some basic parameters for your newsletter:

1. Title: This is the common name for the newsletter, used for reference purposes throughout the application.

2. Prefix: This is the text that is prefixed to the title of each and every issue of your newsletter and appears in the Subject: field of the email message sent to every subscriber. Unimportant as it sounds, this allows subscribers to create a filter for the newsletter in their email client and move it to a separate folder automatically.

3. Reply-to address: This is the address that appears in the Reply-To: field of the email message (usually, the address the newsletter is sent from).

4. Description: This is a description of the newsletter, shown to users when they subscribe.

5. Header: This is the header for the newsletter - you can use the template mechanism to display this in each issue that is sent out.

6. Footer: This is the footer for the newsletter, and it’s useful for messages that are common across newsletters (unsubscription instructions, copyright information and so on).

7. URL of subscription form: This is the URL of the subscription form that can be used to subscribe to the newsletter. Luckily, patNewsletter comes with a simple and ready-to-use form for this. We shall see how to use this to sign up users as we proceed with the tutorial.

8. Maximum amount of pending issues: This allows you to define the number of issues that can be worked on simultaneously. If you have a weekly newsletter, then it makes sense to work on them simultaneously to save time.

All done? Hit the “Save Changes” button and you’ll see a neat little screen giving you information about the newsletter that you have just created.

Off Topic

Now that we have defined our first newsletter, its time to add the “topics”. As described earlier, these topics form the basic framework for the content in our newsletter.

For example, our newsletter used to address one hot Internet topic of discussion, and give subscribers an in-depth look on the issues surrounding it. Plus, in order to keep the reader interested, we added in-between sections containing quotes, riddles and jokes to make the reading experience more enjoyable.

In the patNewsletter context, it is obvious that each of these sections can be stored as a topic. Here’s how you add a new topic to an existing newsletter:

This form is pretty simple - it just requires a title and description. A little check box makes this a default topic for your newsletter. More on this personalization feature when we study the subscription process later in this article.

Once you add and save all your topics, you will be presented with a neat listing of all the topics that form a part of your newsletter:

Now that we have the skeleton of the newsletter in place, let’s add some meat to it. Click the “Add” menu option on the left menu to view the “Create a new issue” screen:

The fields are self-explanatory. The text that you enter in the “Subject” field here will be displayed in the Subject: header of the email message, while the “Introduction” will be placed at the top of this particular issue of the newsletter. Once again, click on “Save Changes” to see a list of existing issues (including the one that you’re working on).

You will notice that each entry has a “more” option in the listing. Click on this link to view the data that you have just entered.

At the bottom of the screen, use the “Add an article” option to view the following form:

As you can see above, this screen allows you to add content for each of the articles that form the framework for your newsletter. Select a topic from the drop-down list. The article will only be sent to those subscribers who have subscribed to the selected topic.

Next, you have to fill in the “Subject” field - the text of this field is displayed in the index that appears at the beginning of the newsletter and as a topic in the newsletter. The “Text” field holds - duh! - the text that makes up the content for the newsletter

The “Variable Helper” drop-down list allows you to insert pre-defined values such as the “Title of the newsletter”, “URL to modify subscription” and so on into the newsletter content - just select a variable and its value will appear in the final newsletter when it is sent out.

The little announcement check box allows you to flag any article as an announcement. If any article is flagged in this manner, it will be sent to all subscribers irrespective of their selection of topics at the time of subscription.

Finally, the ubiquitous “Save Changes” button saves this article to the database. Follow the above steps for each topic in your newsletter and slowly but surely you will see the entire thing unfolding right in front of your eyes.

Once you’re all done, go back to the “View” screen and check out all your articles neatly displayed one after the other. Click the “Edit” button available under each article to make changes.

Now, how about sending the issue you just created? Hit the “Send this issue” menu item that appears on the screen, and you should see something like this:

A pop-up window will appear and show you status as your newsletter issue is sent out to each subscriber. Once the issue has been sent to all subscribers, you will get a polite little message telling you that it’s all over.

Issues once sent out do not just fade away, they get moved to the archive, where they can be accessed at any time in the future.

What’s The Plan, Man?

Now, that you know the application workflow - right from creating the newsletter to sending it out to your millions of eager subscribers - it’s time to step back a bit, go to the drawing board and discuss the process by which you define the framework for your newsletter.

The first and foremost task is to organize your newsletter into meaningful topics; this involves breaking up the content into smaller and more manageable parts. Not only does this make the task of generating the content for the newsletter easier (as you can distribute the work load across your team), it will also give your subscribers the additional flexibility to opt out of topics that are not of interest to them. For example, the release of the latest patch to the Windows OS is of no use to the financial analyst on Wall Street (unless of course, he has bought heavily into Microsoft stock).

Once you’ve organized the topics, it’s time to get down to the layout of the newsletter. At this point of time, I’ll assume you’re using the default template. But if like tweaking, make sure you come back for the second part of this article, when I’ll show you how to customize the default templates and layout to your exact needs.

So, that takes care of the structure of the newsletter and its look and feel. Time to populate it!

First, make sure that you have all the content of your newsletter in a neat text file (hopefully with out any typos or grammatical errors). Log into the administration module of patNewsletter, select the “Add Issue” option for your newsletter and add each and every article - assigning them to the right topic - one by one. A little tip here: enter the articles in the order that you would like them to appear in the newsletter (for example, you don’t want the answer to a riddle appearing before the riddle itself). Remember that once you enter the content, there is no way to modify the order of articles or even delete an article!

Once you’re all done with the content entry for the newsletter, preview it to ensure that all is hunky-dory, say a little prayer and hit the “Send this issue” button…and hope for the best!

Over And Out

And that’s about all we have time for. In this article, I introduced you to patNewsletter, a PHP application that makes managing a newsletter as easy as clicking your way through a series of menus. I showed you how to create a new newsletter, add topics, create new issues, and add content to your newsletter before blasting it out to all your subscribers. I also gave you some tips on how to plan the framework for your newsletter, so that you can add content to each issue easily and quickly.

Of course, there’s one important thing I haven’t touched on here - the built-in tools that patNewsletter gives you to manage user subscriptions. In the concluding segment, I’ll talk a little bit about this, and also show you how to customize the format of the newsletter as well as that of the user sign-up form - both use the very powerful patTemplate class to drive the user interface. I shall also discuss HTTP authentication to protect the patNewsletter administration module - you’ll notice that it does not come with much security by default. And to top things off, I shall teach you how to integrate patExtras - a nifty little tool that gives you automatic notification of updates and a simple interface to report bugs - into your patNewsletter application.

See you soon!

Note: Examples are illustrative only, and are not meant for a production environment. Melonfire provides no warranties or support for the source code described in this article. YMMV!