phpList Resources

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Conditional Placeholder ======

---- plugin ----
description: Provides conditional placeholders in messages, templates, and the subject line. No longer supported.
author     : Arnold Lesikar  
email      : alesikar@mac.com
type       : 
lastupdate : 2015-03-29
compatible : 3.x
depends    : PHP 5.x
conflicts  : 
similar    : 
tags       : conditional, placeholder, attribute,

downloadurl: https://github.com/arnoldle/phplist-plugin-conditionalPlaceholderPlugin/archive/master.zip
bugtracker : https://github.com/arnoldle/phplist-plugin-conditionalPlaceholderPlugin/issues
sourcerepo : https://github.com/arnoldle/phplist-plugin-conditionalPlaceholderPlugin/
donationurl: 

screenshot_img : 
----

A plugin to allow the use of conditional placeholders in phpList messages. Alternate text is inserted when the placeholder has no value. 

**The author has given up phpList development. This plugin is no longer actively supported**


===== Installation =====

if you are running a later version of phpList (3.06+), you can install the plugin using the plugin installer provided by phpList.

Instead of using the installer, you can download the files using the URL above, unzip them and then upload the file conditionalPlaceholderPlugin.php to the admin/plugins subdirectory of phpList. Also, upload the conditionalPlaceholderPlugin subdirectory containing the file config.php.

As well as allowing conditional placeholders, this plugin also duplicates most of the functionality of my [[plugins:subjectlineplaceholder|subjectLinePlaceholderPlugin]].So if you install the //conditionalPlaceholderPlugin//, you should probably disable or remove the [[plugins:subjectlineplaceholder|subjectLinePlaceholderPlugin]].

And of course **make sure that this plugin is enabled before you attempt to use it**.
===== Configuration and Settings =====

The configuration is set by values in the //config.php// file in the subfolder belonging to this plugin.
You can set values by changing the following lines:
 	<code>public static $cpBrackets = array('[*','*]');</code>
$cpBrackets sets the brackets around conditional placeholders and around the keywords used by this plugin.
 	
 	
 	<code>public static $cpKeywords = array('IF', 'ELSE', 'ENDIF', 'ELSEIF');</code>

Change these values to set the keywords recognized by the plugin to implement the 'if', 'else', 'endif', and 'elseif' functions.
 	
   	<code>public static $explicitElse = true;</code>
   
Set this value to 'false' if you want the absence of an explicit 'else' keyword to indicate an empty alternate string. This is not recommended.

<code>public static $listsep = ',';</code>
        
This value defines the character or string used to separate acceptable attribute values in a list.
 	
 	<code>public static $ellipsis = '..';</code>

This value is used to indicate a range, which may be an element in a list of acceptable attribute values.
 	
 	<code>public static $testflag = '~';</code>

This value flags a placeholder to be used only as a test, without replacement.


=== Change Log ===

  * **2013-12-30**
    * 1.0a1 - Initial release
    * 1.0a2 - Added configurable syntax
    * 1.0a3 - Restored the configuration check erroneously commented out in version 1.0a2
    * 1.0a4 - Insured that attribute names with HTML entities inside are recognized
    * 2.0a1 - This version greatly expands the capabilities of the plugin
    * 2.0a2 - Added further configuration checks
    * 2.0a3 - Removed admin menu for plugin, since it has no web pages
    * 2.0a4 - Removed an unnecessary modifier from the regex patterns to prevent future problems
    * 2.0a5 - Fixed a bug that interfered with the mailing of system messages
    * 2.0a6 - Guarded against the editor introducing HTML entities into a placeholder
    * 2.0a7 - Fixed issue with diacritically marked characters in attribute values
    * 2.0a8 - Now trim white space from user attribute values before use
    * 2.0a9 - Fixed a problem with characters being replaced by entities in saved draft messages
    
===== Discussion =====
===ELEMENTARY USE===

This plugin allows the use of conditional placeholders in PHPlist html and text messages. It also allows standard placeholders to be used in the subject line of messages, as well as conditional placeholders, thus duplicating most of the functionality of the //subjectLinePlaceholder plugin//.

The standard placeholder is the attribute name in uppercase and enclosed in square brackets. Aside from allowing the use of such standard placeholders in the subject line of a message, standard placeholders are ignored in this plugin. **The absence of a value for a standard placeholder does not trigger the insertion of alternate text**.

For the purposes of this plugin, a conditional placeholder is an upper case user attribute enclosed in the form of the brackets defined in the 'config.php' file. For the rest of this discussion, we will assume the default configuration values, so that the conditional placeholders and attribute names are enclosed in 'star brackets,' for example: **[*NAME*]**. 
 
The following syntax allows an alternative string to replace the string containing the placeholder when the placeholder attribute has no value:
 
<code>[*IF*]This is a string for user {FIRSTNAME} {LASTNAME}.[*ELSE*]Here is the alternate string.[*ENDIF*].</code>
 
If any of the conditional placeholders is without a value in the first string, that is, the //original string//, the alternate string replaces it. In any case, the **[*IF*]**, **[*ELSE*]**, and **[*ENDIF*]** tags are removed. 

**Note that a numerical zero value for a conditional placeholder will trigger replacement by the alternate string.**

The presence or absence of a value for any standard placeholders in the original string
or the alternate string has no effect on whether the original string or the alternate
string appears in the message. Which string appears is determined solely by the existence or absence of a value for the conditional placeholders in the original string.
 
**The [*IF*]...[*ELSE*]...[*ENDIF*] construction must be well-formed, or the message will not be queued.** A conditional placeholder **must** appear inside a string preceded by an **[*IF*]** tag, that is, inside the original string. 

If you set the value of **$explicitElse** to 'false', then the appearance of an **[*ELSE*]** with an alternate string is optional. If there is no **[*ELSE*]**, the alternate string is taken to be an empty string. Otherwise a missing **[*ELSE*]** is an error. This is the recommended behaviour under the philosophy that if you want an empty alternate string, you should indicate it explicitly in the text.

The original string, preceded by **[*IF*]** and terminated by **[*ELSE*]** or** [*ENDIF*]** **must** contain at least one conditional placeholder. **No** conditional placeholder can appear in the alternate string, but standard placeholders are OK.

Star brackets must be closed. The appearance of an opening or closing star bracket without its partner will prevent the message from being queued.

A star bracket placeholder containing a string that cannot be identified as a user attribute will prevent the message from being queued.

===SETTING ACCEPTABLE ATTRIBUTE VALUES===
In the discussion above, the placeholder is replaced if the corresponding attribute has a defined value. However, it is possible to specify the acceptable values in a list enclosed in parentheses immediately after the name of the attribute. Thus the placeholder will be replaced only if the corresponding attribute has an acceptable value. Otherwise, the alternate string will be used. If there are several placeholders in the original string, each one must have a defined value or an acceptable value, depending on how each placeholder is set up; otherwise, the alternate string will be used.

Note that the testing of attribute values has been internationalized. Umlauts, accented characters, are generally any character requiring diacritical marks should be OK. The plugin has only been tested thus far with umlauts, but any UTF-8 characters should function as well, with the one exception mentioned below. 

For example, 
<code>[*IF*]Your southernmost western state is [*STATE(California, Arizona, New Mexico, Texas)*].
[*ELSE*]You don't live in the southern part of the West.[*ENDIF*]</code> 

The new keyword **[*ELSEIF*]** allows us to take more possibilities into account, as in the following example:

<code>[*IF*]Your southernmost western state is [*STATE(California, Arizona, New Mexico, Texas)*].
[*ELSEIF*]Your northern New England state is [*STATE*(Maine, Vermont, New Hampshire)*]
[*ELSE*]You don't live in the southern part of the West or the northern part of
New England.[*ENDIF*]</code>

A list can include an empty string, but an empty list is an error. So **[*STATE*(Maine,, New Hampshire)*]** or **[*STATE*(, Vermont, New Hampshire)*]** is OK, but **[*STATE*( )*]** is an error.

A list can include include a range, for example:
<code>[*STATE(Arkansas, Oregon, California..Georgia)*]</code>

Here the acceptable values of the state attribute are Arkansas, Oregon, and states with names between California, and Georgia inclusive, in alphabetical order. That would be California, Colorado, Connecticut, Delaware, Florida, and Georgia.

If the starting value or the ending value of a range is not given explicitly, then the alphabetically preceding or succeeding values respectively are understood to be acceptable thus with

<code>[*STATE(..Arkansas)*]</code>
the acceptable values would be Arkansas and state names preceding Arkansas in the alphabet, that is, Alabama, Alaska, and Arizona. Since there is no state having the name 'B', we could write the placeholder as 
<code>[*STATE(..B)*]</code>
to select the same states.

Similarly <code>[*STATE(W..)*]</code> would select all states with names alphabetically following 'W', that is Washington, West Virginia, Wisconsin, and Wyoming.

if the attribute value is numeric, then the attribute value is checked against the range numerically. For example <code>[*AGE(..35)*]</code> accepts any age value numerically less than or equal to 35.

A range must have at least an upper or lower limit. So **[*AGE(..)*]** is an error.

**Note that in the current version of the plugin, ranges can only be used with numerical values or text formed with normal characters from the English language.** Testing an attribute value containing a diacritically marked character, such as an accented character or an umlaut, against a range will lead to unpredictable results. Even testing an attribute value formed of normal English characters against a range defined with such diacritically marked characters will lead to unpredictable results. In short, ranges of attribute text values are treated as if those values can be arranged in the normal alphabetical order of the English language.

If there is a demand for it, the treatment of ranges will be internationalized in a later release.

Note that placeholders are tolerant of white space. Extraneous white space is ignored. So, for example, in a list you can add white space between the items to make the list more readable.

===USING A PLACEHOLDER AS A TEST WITHOUT REPLACEMENT===

In version 1 of this plugin, a conditional placeholder served two functions:
  *Marking a place for an attribute value to be placed.
  *Serving as a test to determine whether the original string or an alternate string should appear in the processed text.

The first function (without the test) is served by a standard placeholder, which holds the place for an attribute value to be placed, without regard to the existence of that value.

In version 2 of this plugin, a conditional placeholder can be used as a test determining which string is to appear in the processed text. If the name of the attribute (in upper case) is preceded by a tilde (**~**), the attribute value will be tested for acceptability, but the placeholder itself will be replaced by an empty string regardless of the attribute value associated with it. In other words, **a placeholder used as a test is never replaced by anything other than an empty string**. 

The following example shows how you might set up a greeting depending upon the gender of the recipient. Let's assume that you have a Gender attribute, which can take the values M or F, or it may be empty. Then the following would give the form of address according to gender:
<code>[*IF*][*~GENDER(M)*]Dear Mr.[*ELSEIF*][*~GENDER(F)*]Dear Ms.[*ELSE*]Greetings[*ENDIF*]</code>

So for a man, the above would output "Dear Mr.,". For a woman the result would be "Dear Ms.," and for someone of unknown gender the output would be "Greetings,". In writing this, we are assuming that the **{*IF*]....{*ENDIF*]** structure would be followed by the placeholder for the name. 

Alternatively, you could do it this way, including the name in the structure:

<code>[*IF*][*~GENDER(M)*]Dear Mr. [*NAME*],[*ELSEIF*][*~GENDER(F)*]Dear Ms. [*NAME*],
[*ELSE*]Greetings,[*ENDIF*]</code>

This way if the gender **or** the name is unknown, the result becomes "Greetings,"

===CONFIGURATION===
The value of the '$cpBrackets' array sets what brackets are to appear around the plugin's keywords. You can set the brackets with the following limitations:
  
  *Exactly two brackets must be specified.
  
  *Neither bracket can be an empty string.
  
  *The two brackets must be distinct. For example, you **cannot** specify each bracket to be
   a single vertical bar, '|'.
  
  *The innermost part of a bracket cannot be a square bar. phpList may recognize such brackets 
   as standard placeholders and replace the attribute inside.
  
  *Avoid angle brackets. phpList removes HTML tags in generating a text message from the HTML 
   version of the message. With angle brackets, the placeholders will be removed.

The value of '$cpKeywords' array determines what keywords are recognized by the plugin for the 'if', 'else', and 'endif' functions. Since the default values in consist of several characters, you might want to specify two character keywords, perhaps as in the following example:
<code>public static $cpKeywords = array('IF', 'LS', 'FI', 'LF');</code>

You can make this plugin very concise in the following way. If you are sure that curly brackets will never appear in a list message, you might use them for your brackets:
<code>public static $cpBrackets = array('{','}');</code>
Further, no one says that your keywords have to be alphabetic; single character symbols are perfectly OK. So you might do this:
<code>public static $cpKeywords = array('?', ':', '/', ':?');</code>
With these choices a conditional placeholder string might look as follows: 
<code>{?}{~GENDER(M)}Dear Mr. {NAME},{:?}{~GENDER(F)}Dear Ms. {NAME},
{:}Greetings,{/}</code>

The default value for the separator in a list is a comma. But you can change this by substituting a different character or string for **$listsep** in //config.php//. Similarly, the double dot range indicator can be changed by changing the value of **$ellipsis**. The default value for the test flag is the tilde. You can change this by changing the value of **$testflag**.

Note although extraneous white space inside a placeholder is ignored, **you cannot include white space in any of the items defined in the configuration file**. 

Also **note that none of these items should be such as to //require// representation by an entity in HTML.** So, for example, using an inverse question mark "¿" in a configuration item is a bad idea!
===Errors==
The plugin will check that each conditional placeholder string makes sense before it will allow the message to be queued. When you attempt to queue a message with an error, you will get a message indicating what the problem is in the message.

The plugin checks its configuration every time a message is queued, whether the message contains a conditional placeholder string or not. If there is a configuration problem, you will not be able to queue any message until the problem is fixed or the plugin is disabled.

The following error messages pertain to the configuration. If there is an error, one of these messages may appear when you attempt to queue a message.

  *'There must be exactly 2 placeholder brackets defined in the config file!'
  
  *'Each placeholder bracket must be defined in the config file!' --- A bracket cannot be an empty string.
  
  *'Left and right placeholder brackets must be distinct!'
  
  *'There must be exactly 4 keywords defined in the config file!'
  
  *'A keyword cannot be an empty string in the config file!'
  
  *'The items in the config file cannot contain white space!' --- For example, you cannot have **' ELSE'** or **'END IF'**.
  
  *'Each item in the config file must be unique!' --- For example, **$listsep** cannot be the same as **$ellipsis**.
  
  *'Placeholder brackets must not conflict with HTML tags!' --- Avoid angle brackets!
  
  *'Placeholder brackets must not conflict with standard placeholders!' --- The brackets defined in the config file may allow phpList to interfere with the conditional placeholders.
  
  *'Neither $testflag nor $listsep nor $ellipsis can be empty strings in the config file!'
Main Navigation

phpList Resources

Quick Links

Resources

Contact Us

Boring Bit

Main Navigation

phpList Resources

User Tools

Site Tools

Page Tools

Quick Links

Resources

Contact Us

Boring Bit
