Note: you must create your template using the standard phpList Template editor BEFORE you’ll be able to use these tools.

return to pbts_xtra documentation.

When this is complete I’ll try to get it added to the phpList wiki.

See Also:
phpList Mailing Pre-Flight Check List

This page contains two sets of instructions:

1. Installing the plug-ins (basic install, required)
2. Replacing the built-in phpList Message Editor with PBTS_XTRA’s Template-driven custom Editor

To use this plugin you MUST perform the basic install — making phpList’s sending engine able to process your new multi-content Templates. However, to really create a nearly seamless system you’ll also want to switch from phpList’s default
Message Editors and use the rich features of the PBTS Editor that dynamically creates a customized interface based on your own Template regions (hmm, sounds like a kitchen appliance).

Installation (Basic)

Overview

Time to install: 10 minutes

You’ll need to edit the config files, unzip the plugin into your plugin directory, and make two modifications to one phplist file.

Steps

1. open config/config.php and turn off the WSYSIWYG editors via a configuration setting (~line 481):
   
    
   
   define("USEFCK",0);
   
    
2. Double check that TinyMCE is also turned off:
   
    
   
   define("USETINYMCETEMPL", 0);
   
    
3. Lastly, you’ll probably want to turn off the auto-generated text email. Or, turn on the manual text message option:
   
    
   
   define("USE_MANUAL_TEXT_PART",1);
   
    
4. If you don’t have your plugin directory defined you’ll also need
   to set this: define("PLUGIN_ROOTDIR","plugins"); or you may
   specify some other path.
   
    
5. unzip pbts_xtra.zip files into your plugins directory.
   
    
6. Modifying the SendEmail Library.
   
    
   
   BACKUP YOUR FILE BEFORE PROCEEDING
   
    

   These last two steps are the only ones requiring mods to core
   phpList files. Open admin/sendemaillib.php. Add this line to the
   top of the file:
   
    
   
   include_once dirname(__FILE__).'/plugins/pbts_xtra/pbts_xtra.inc.php';
   
    
   
   Note: if you installed the plugin in a different directory set
   this as needed.

7. Next we replace the current Template tag substitution with the
   PBTS_XTRA calls. Locate the following code (about line 180):
   
    
   181.   if ($cached[$messageid]["template"])
   182.     # template used
   183.     $htmlmessage = eregi_replace("\[CONTENT\]",
        
                $htmlcontent,$cached[$messageid]["template"]);
   184.   else {

   Replace (or comment-out) these lines with this:
    

   181.   if ($cached[$messageid]["template"]){
   182.     # template used
   183.     if (!preg_match("/\[PBTS_/is",
        
                $cached[$messageid]["template"]))
   184.       $htmlmessage = eregi_replace("\[CONTENT\]", $htmlcontent,
        
                $cached[$messageid]["template"]);
   185.     else
   186.       $htmlmessage = pbts_replace_content( $htmlcontent,
        
                $cached[$messageid]["template"] );
   187.   } else {

That’s it. (hopefully)

top of page

Upgrading Message Editor

Overview

Time to install: under 10 mins

As of this writing the plug-in structure provides a less than
ideal level of integration; if you want to enable the pbts message
editor as a replacement of the standard phpList editor follow
the basic installation instructions above, then …

Steps

(REQUIRED TO MAKE THE PBTS EDITOR THE DEFAULT MESSAGE EDITOR)

We’re going to modify the core phpList file that emits the message
editor. Because this is an important file, please, back it up and
keep a good copy in a safe place, just in case.

We’re going to make three edits to this file.

1. Backup admin/send_core.php
   
    
2. Adding the PBTS_XTRA library. Open send_core.php and find
   this line (should be the first one in the file):

   require_once dirname(__FILE__).'/accesscheck.php';

    
   
   We’ll add a statement telling this file where the PBTS library is:
   
    

   require_once dirname(__FILE__).'/accesscheck.php';
   
   include_once dirname(__FILE__).'/plugins/pbts_xtra/pbts_xtra.inc.php';

    

3. OK, now let’s modify where the editor’s form fields
   get emitted. Jump down to around line 1100 and find
   these statements:

   } else {
   
     $maincontent .= '<textarea name=message cols=65 rows=20>'
        .htmlspecialchars($_POST["message"]).'</textarea>';
   
   }

    
   
   Replace this line with:
   
    

   } else {
     # let PBTS emit the form fields based on the Template tags:
     $maincontent .= pbts_send_core_editor();
     # end, PBTS
   }

    

4. Lastly, we need to "smarten up" the code that’s
   executed when you click the Save Edits button.
   Locate the following statements (about line 270?):

   if (!$htmlformatted  && strip_tags($_POST["message"]) !=  $_POST["message"])
     $errormsg = '<span  class="error">'
       .$GLOBALS['I18N']->get("htmlusedwarning").'</span>';
   
   $query = sprintf('update %s  set  '.
       'subject = "%s", '.
       'fromfield = "%s", '.
       'tofield = "%s", '.

    
   
   Let’s insert a line between the two above:
   
    

   if (!$htmlformatted  && strip_tags($_POST["message"]) !=  $_POST["message"])
     $errormsg = '<span  class="error">'.
         $GLOBALS['I18N']->get("htmlusedwarning").'</span>';
   
   # Add PBTS processing to save:
   if (isset($_POST['pbts_xtra']))
     $_POST["message"]= pbts_send_core_save();
   # done adding PBTS lines.
   
   $query = sprintf('update %s  set  '.
       'subject = "%s", '.
       'fromfield = "%s", '.
       'tofield = "%s", '.

    

top of page

Sample Templates

In the zip there is a sample_Template.php. Create a Template and import
this file as the content. It’s important that the WYSIWYG editor be
turned off, otherwise it will rewrite my custom region tags, replacing
the & with & and that will definitely break this.

The sample template is not necessarily a study in "best email layout
practices", but serves for illustration purposes. I just had to add
that, not that I’m ashamed of this one, but I’d definitely do it
differently.

top of page

Run down these check lists and you might just make it.

More Pizza phpList stuff: multiple-placeholder plug-in: pbts_xtra or growing list of built-in placeholders

Installation & Setup Check List

• Have you setup an "abuse@mydomain.com" account?
• Have you setup a "postmaster@mydomain.com" account?
• Verify your reverse DNS? Use DNSreport.com to verify.
• Added a SPF record? (debate continues on how crucial this is, or even whether it’s even a good idea. AOL seems to be throwing their weight behind "yes, do this")
• Does your email/site hosting company limit the number of emails per hour you may send? Are you sure? If so, have you set phpList’s throttle in config.php? There are three settings: MAILQUEUE_BATCH_SIZE, MAILQUEUE_BATCH_PERIOD, and MAILQUEUE_THROTTLE.
• Have you tested the unsubscribe?
• Did you include a note in your email asking people to "safe list" your sending-from email address, "my-phplist-account@mydomain.com"?
• Did you check your bounced mail account setup? phpList requires the IMAP PHP extension. It also requires a valid logon be setup in config.php.
• On the configure page you’ve set your domain correctly?

Message Sending Check List

• You’ve added Users (recipients) to your target List (seems obvious, lots of people remember to add Users, but not make them Members of a List)?
• Have you sent a test message? Which desktop mail client and webmail have you viewed it in? Have you test-mailed AOL? Yahoo! GMail? Hotmail?  HelloKitty.com?
• You’ve proofread and spell-checked your HTML AND Text-only email? Even if you’re sending all HTML emails, 100%, no exceptions… check the text message. phpList is smart. It will send multi-part emails: that is, it will send your HTML email and, in another hidden bucket inside that email will be the text-only version. Why? If the recipient’s email client can’t view HTML emails it will look for the text version. Fails politely.
• Verify the from email address. Does it match the one you told people to "safe list"?
• Meaningful Subject line?

Great. Hit Send… and then…

What went wrong?

If you send your email and have no problems, fantastic. Wait. Did you say NO PROBLEMS? Ahhhhhhhhh! I mean, Uh-oh. No bounces? No "out of office" auto-responses? Really? Dude, bad news… you’re screwed. Time for quick triage:

• Was everyone on your list confirmed?
• If you imported Users into your List from a file did you set them all as pre-confirmed?
• Maybe you exceeded your hosting company’s limit? FTP in and, if you’re able to find it, look in your mail directory. Look for sent, bad, etc. You may find a big pile of all of your emails.
• Did you inadvertently leave phpList in "Test" mode? In config.php check your value for this constant (0 is off, 1 is on): define ("TEST",0);
• Send a test mail. Perhaps you’ve a basic setup/configuration problem with mail account etc?
• Still no ideas? Head over to the phpList forums and do a search. Odds are that someone has had a similar problem. Oh, if you do decide to post a new thread — don’t be an asshat. Ask a specif clear, meaningful, well constructed question, details and examples help and people will be more likely to reply. Give it a meaningful post name (not "Help me!!!!!!!! " or "Didn’t work" or "this program sux") And, if you solve your problem, please, post the solution. For the next person, who is just exactly like you and me.
• Also, don’t forget your hosting company’s support forum, knowledgebase, or other options. Might get help configuring there.

See also:

• Advice: Fix your DNS records so you’re not seen as spam
• phplist setup walkthrough

This plugin extends phpList’s Template functionality by allowing you to define multiple Content Regions within your Templates.

You are also able to include or exclude sections of your Template based on whether one of these Content Regions is empty or not.

Sections on this page:

Problem Definition | Basic Usage | Advanced Options
Conditional Regions | faq
thank yous | terms of use  |  revision history

See Also:

detailed installation instructions  |  screenshots,
More on phpList: phpList’s standard placeholders  |  
phpList Mailing Pre-Flight Check List

Resources

Download plugin:pbts_xtra.zip
Current Version: 0.04 [beta] 5-December-05
Includes: plugin, install notes, and sample template for practice

phpList homepage (on tincan.co.uk)
discuss this plugin on phpList forums

the Problem: why this plugin is needed

If you know the problem, skip ahead, if not, why are you here? You’re here? Fine. Here’s a summary of the Problem.

phpList has a cool method of managing Email Templates, allowing one to divide responsibilities of look-n-feel designer-types from the marketing people that will actually send out the mailings (I need to accept the word "blast" for this action, but it’s difficult).

There are a handful of special phpList tags that you may include within your Templates, the most important of which is the [CONTENT] tag (others include [FOOTER], [SIGNATURE], [USERID], and [USERTRACK]). Your template may contain on Content; it’s the guts of the email.

Therein, however, lies the problem. Because it’s assumed that you have only one "chunk of stuff" per email, that is, it is assumed that the layout only needs on block, this Content area.

Now, while you can embed HTML and whatever else you’d need to make, say, a multi-column layout, well, this breaches that line separating Design and Function; suddenly the person sending out the (oh, so help me) "Blast" needs to be an HTML hack.

This kinda sucks for those who want more dynamic layouts.

So this, then, is the problem I set out to solve, which is where the following tweaks come in.

top of page

pbts_xtra

pbts_xtra allows you to define as many dynamic sections within your Template as you want. You’re also able to choose to have some sections included or excluded depending upon whether there is content available (more later). Finally, the plugin automatically creates an editor for these Content Regions based on settings you provide.

Basic Usage

Your Template

Begin by creating your template. Wherever you wish to insert a Content Region do so by entering the PBTS_XTRA tag:

[PBTS_XTRA name="MyNewColumn"]

There are more options and features to be covered shortly, but to just get started using this plugin that’s all you need to do.

Frequently alternative methods are supported by the plugin. On such alternative (shorthand way) of defining a Custom Region is:

[PBTS_MyNewColumn]

Either way informs the plugin that the Template has a Custom Region named "MyNewColumn".

Message Content

To use your Template in a mailing all you need to is create a Message in the usual phpList way with the additional step of marking portions of the Content to match your custom Content Regions.

Backstory: phpList has exactly one Content "chunk" per email. Thus, we need to subdivide this Content by marking the beginning and ending of our custom Content Regions. We do this thusly:

Now, doing this by hand might be tedious and error prone. Also, you might overlook some of your Template’s Content Regions. To mitigate this a bit pbts_xtra offers it’s own editor. This editor reads your Template and creates an entry field for each Content Region.

top of page

Advanced Topics: More Options

pbts_Xtra tags have several parameters (straight from HTML form tags) that allow you to control the auto-generated Message Editor. For example, this would be in your Template:

[PBTS_XTRA name="MyNewColumn" displayname="Joke of the Day" 

type="textarea" rows="6" cols="45"]

This will cause the Editor to, you guessed it, emit a textarea for MyNewColumn with 6 rows and 45 columns. The label next to it will be Joke of the Day.

Other parameters allow you to set the order in which the fields are emitted and what kind of formatted pbts_xtra will automatically apply to the values entered.

Oh, curious about what happens to the values supplied for all of the fields, are you? Sure.

Well, no new tables or columns are added for pbts_xtra. Instead all of the values are tagged (begin and end markers added) and all stored together in the same single Content area used for normal phpList Messages. (yes, completely denormalized, but quite backwards compatible).

Using the example begun above, the field "myNewColumn" would be marked-up thusly:

[PBTS_XTRA name="MyNewColumn"]
Here is the content for a block of stuff called MyNewColumn.
[/PBTS_XTR]

Note, that all of the arguments added for Editor generation are completely optional: all you need to do is provide the Enhancement with a means of differentiating the blocks, i.e. just provide each Custom Area with a unique name. All else is gravy.

Im also supporting alternate syntaxes (easier than it sounds since I worked from the code I initially had and being lazy found it just as easy to leave some features in).

For example, if you dont like:

[PBTS_XTRA name="MyNewColumn"]

An alternate, and valid, way to define or mark blocks is:

[PBTS_MyNewColumn]

Behind the scenes it parses the template, no, it doesnt parse it, the Template is scanned for tags that begin "PBTS_".

top of page

Advanced Topics: Conditional Regions

PBTS_Xtra supports conditionally including or excluding sections of the email, based on the presence of a particular Content Region.

For example, say your email Template has an Urgent_Action block that usually has some call to action for your list members. Usually, but not always. Well, rather than creating two templates, instead, just have one thats smart enough to recognize that if the Urgent_Action Content Region is empty dont emit that section’s block:

[pbts_if condition="not_blank" name="Urgent_Action"]
<h5>Urgent Action</h5>
[pbts_xtra name="Urgent_Action"]
<p>For how you can get involved contact Bob </p>
[/pbts_if]

<p>Just a blank line between ifs</p>

[pbts_if condition="empty" name="Urgent_Action"]
<h5>No Urgent Actions This Month</h5>
[/pbts_if]

The syntax is hopefully vaguely familiar. You have two tags that mark the block. The block begins with the pbts_if and ends with the [/pbts_if]. Please, NO NESTING OF IFs.

The two arguments allowed in the if statement are the desired condition and the name of the Content Region to be checked. The conditions supported at this time are only whether the named Content Region is blank or not.

ELSE statements are not offered.

As with the other stuff variants are supported. The following means "the section is not blank":

Condition="defined"

These are alternate means of saying the same thing:

• "defined"
• "is set"
• "not blank"
• "not empty"

Also note that the two word values, such as "is defined" might include (optionally, of course) a dash or underscore between "is" or "not. That is, these are synonymous:

• "defined"
• "is defined"
• "is_defined"
• "is-defined"
• "isdefined"

It is important to note that NESTED IFs are NOT SUPPORTED.

HHH

top of page

faq

What is PBTS?

PBTS? That’d be "Pizza By The Slice". It’s a habit. I always prefix my mods with my website name to make it easier to find my edits. Oh, sometimes I’ll use my initials, too.

My contact info is at the bottom of this page (me = (Courts|Buz) Carter).

Why do the [PBTS_XTRA] tags get wrapped in Paragraph Tags?

This is perhaps an unneeded bit of legacy code, but the phpList Message Editor liked to see things all neatly wrapped in <p> tags, so figured "hey, I’ll do it myself and maintain some control". Regardless of whether or not they are present they are stripped before Emails are sent.

Within a Template may I repeat Tag names?

Yes. However, the editor uses the arguments set with the first occurene of a specific tag name. But yes, sprinkly a given tag throughout your Template is allowed, and any Message using this Template will have the same value plugged into every occurence of this tag.

top of page

Thank yous…

I was content with using my phpList tweaks, which were far short of this plug-in, until Ludlow Brown and Karl Hedner opined that this could be a useful tool for the larger community. So, huge debt of gratitude is owed these two for helping test and, more importantly, for encouragement and suggestions.

top of page

Terms of Use

As always — use this as you will, but don’t sell it. It’s to remain free, released under Creative Commons License:

This work is licensed under a Creative Commons License.

top of page

revision history

top of page

To-Do List

Hope to get feedback on how to better integrate this.

1. Need better place within sendmaillib.php for performance reasons.
2. Possibly add style or class info that could be automatically added to <p> and <li> tags.
3. Probably not for this tag, but Text Templating would be cool.
4. Should single carriage returns be turned into <br />?

top of page