Plugin: PBTS_XTRA, add Multiple Content Areas to phpList

Overview

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]
parameter description
Name Required (sort of). Any non-reserved word, made up of alphanumeric characters (a-z, 0-9), dashes, and underscores.
DisplayName Name displayed to Content Creator within the Editor
Type HTML Form Field Type. Allowed values: Text or Textarea. Default is Text.
Paragraph Allowed values "always" or "never". Should the content for this Content Region be wrapped in <p> (paragraph) tags. For example, a large block of text edited in a Textarea typically has the double-newlines replaced with paragraph tags.
Conversely, if one of the Content Regions is used as a URL in, say, an image tag or anchor tag, then you would want to set this to "never" to have all paragraph tags stripped.
Description For Editor any help you might want to include. Please note, until I beef-up the Regular Expressions this needs to following the same rules as the Name for allowed characters.
Rows Used by Textareas.
Cols Used by Textareas.
Size Used by inputs of type Text. Field size.
Required For Editor. If set to yes and the field is left blank errors are produced. Allowed values "yes" or "no". Defaults to yes.
Style Inline CSS Style to be applied to Textares with paragraphs set to Always. Any paragraphs tags added will have this style applied.
TabIndex For Editor. Set the tabbing order and the order in which fields are emitted in the Editor. Default is the order in which they appear within the Template source.

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:


Creative Commons License
This work is licensed under a Creative Commons License.

top of page

revision history

rev date description
0.05 10-Dec-05
  1. Added Tag Editor
  2. Added Template Highlight view
  3. Added Message View Source
  4. Added Style tag attribute
  5. Jiggered the send routine to fix issue with quotes — in a nutshell the send routine already escaped (added slashes) to single and double quotes so xtra now, in fact, strips slashes just prior to doing the merge (inside send email lib)
  6. Some minor cleanup of regular expressions — I’m beginning to understand these well enough to truly be shamed by my earlier feable efforts
0.04 05-Dec-05
  1. Rewrote engine allowing installations to replace phpList’s default editors with the PBTS Template-driven editor
  2. Bug fix. Similarly named tags, using the shorthand syntax, stopped matching too soon. i.e. these three tags got the save value: [PBTS_Article],
    [PBTS_ArticleCopyright], [PBTS_ArticleBlogEntry]. These would all get whatever was entered for PBTS_Article
0.03 30-nov-05

Some code clean-up and oversights:

  1. Replace hardcoded table names with: $GLOBALS["tables"]["message"]
  2. Fixed bug wherein empty Content Regions edited via Textarea were being returned with \n (newline) character (not empty)
0.02 29-nov-05 [beta] Known to have some rough spots (but not crashes), so releasing to development community for feedback.
0.01 Aug 2005 Original, non-plug in version of mods.

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