Dragonrider Computing

Multiple Content in phpList Helpfile

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.

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.

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.

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 compatibalbe).

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.

Alternate Syntaxes:

For example, if you don’t 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 doesn’t parse it, the Template is scanned for tags that begin "PBTS_".

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 that’s smart enough to recognize that if the Urgent_Action Content Region is empty don’t 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 conditons 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.

phpList expects a template to contain [CONTENT], if this is missing as it's not needed in this plug-in, your template won't work/save, so add <!-- [CONTENT] --> at the top to fix this issue.