LISTSERV Maestro 8.1-4 Help

 Forward >> << Back Table Of Contents

Edit Content Template

To access the editor page for a click-and-fill template, select the desired template in the User-Defined Templates subtree, then select Edit -> Open Template Definition from the menu (or go via the right-click menu of the template node in the explorer tree).

Define the mail subject and message content of a click-and-fill template on this screen.

To exit and store any changes made to the template, click the [OK] button. To exit without storing, click [Cancel].

The available tabs depend on if the template is an HTML template (with or without a plain alternative text) or a plain text template. This template type is defined on the Template Properties page.

To test how the current template would behave when used in the content definition of a mail job, click the Test Template link (or, if applicable, the Test HTML Part or Test Text Part link).

HTML Template

For an HTML template, define the following values:

Plain Text Template

For a plain text template, define the following values:

Placeholders Tab

This tab is available both for plain text and HTML templates. It contains a table of all placeholders that are currently defined in the template (see below for more details about placeholders). Each placeholder is displayed with its name, display title, value type, mandatory/optional state, and the following action actions:

Click the [Add Placeholder...] button at the bottom of the list to create a new placeholder (there are other ways to create new placeholders, see below).

Template Placeholders

Template placeholders are what makes content templates really usable, as they define the "blanks" that the user who employs a template during content definition will have to fill out.

A template placeholder appears in the template body (HTML or plain text) in the following form:

{{#NAME}}

where "{{" and "}}" and are the opening and closing tags and "NAME" is replaced with the name of the placeholder. The "#" character that prefixes the name must always appear for a template placeholder.

A placeholder with a given name can appear several times throughout the template body and may appear both in the HTML part and the plain text part (if present), if the placeholder's type allows this.

The opening and closing tags for the placeholders can be freely defined and can be any characters you like that do not contain any spaces. "{{" and "}}" are suggested as defaults, but you may change them on the Template Properties page.

Note: The opening and closing tags that are defined for the placeholders will also be used for drop-ins, if drop-ins are enabled for the template.

It is important to choose opening and closing tags with care, making sure that they do not otherwise appear in the template. For example, if you decide to use parentheses '(' and ')' for opening and closing tags, then any text that appears between any set of parentheses will be interpreted as the name of a template placeholder or drop-in. Since parentheses have a high probability for use in the normal text of a message, using them as tags is not recommended because they may cause an error in placeholder or drop-in name look up, leading to mail delivery failure.

There are several ways of creating a new placeholder:

If you simply want to insert an already existing placeholder somewhere in the current text input box, then you can either type its {{#NAME}} tag or you can open the Insert Placeholder screen by clicking the Insert Placeholder menu item or pressing CTRL+E. In this dialog, select an existing placeholder from the list on the left and click [OK], which will automatically insert the placeholder's {{#NAME}} tag at the current cursor position.

Placeholders have various attributes that determine their appearance and behavior. These attributes can be defined during placeholder creation (see above) or by clicking the Edit link of an existing placeholder in the list on the Placeholders tab:

Special Prefix and Suffix Rules for Template Placeholders

When using optional placeholders in a template, it is sometimes desirable that some content defined in the template will only appear if the placeholder is actually filled out, which means that no content will appear if the placeholder is left empty.

For example, consider a HTML template that is supposed to render a bulleted list with up to five bullets, where each list item (except for the first maybe) is optional, meaning that the user who employs the template during content definition can decide how many bullets there are by filling out some and leaving the rest empty, such as:

<ul> <li>{{#Placeholder_1}} <li>{{#Placeholder_2}} <li>{{#Placeholder_3}} <li>{{#Placeholder_4}} <li>{{#Placeholder_5}} </ul>

This would not work because if some placeholders are left empty, then their bullets (rendered by the <li> tag) would still be visible, like this (three placeholders filled out, two left empty):

It would be better if the preceding <li> tag would not appear at all; if the placeholder is left empty.

To facilitate this, template placeholders in LISTSERV Maestro use a special syntax that allows you to define a prefix and a suffix to the content, which will not appear if the user does not enter content. This means that the prefix and suffix are only included if the user actually supplies a non-empty content:

{{#NAME prefix#VALUE#suffix}}

where of course #NAME is replaced with the actual placeholder name and where you replace "prefix" with the desired prefix text and "suffix" with the desired suffix text, using the following rules:

If the user does not supply a placeholder content, then the whole placeholder (starting with the opening tag and ending with the closing tag) will be replaced with an empty string, i.e. the prefix and suffix will not appear in this case.
If the user supplies a non-empty content, then the whole placeholder (again starting with the opening tag and ending with the closing tag) will be replaced with the text that is built by concatenating prefix, content, and suffix. In other words, in the string "prefix#VALUE#suffix" the "#VALUE#" part (including the enclosing "#" characters) is replaced with the user content, and the resulting string (including prefix and suffix) is used to replace the placeholder.

The following shows some examples for placeholders with a prefix and/or suffix. In the examples, line breaks are shown as "" for better readability, and the prefix is marked with a green background, while the suffix is marked with a yellow background.

Simple prefix and suffix:

{{#Placeholder Prefix Text#Value#Suffix Text}}

Prefix and suffix with line breaks.
Note that the whitespace before the first prefix character is not part of the prefix itself since all whitespace between "#NAME" and the prefix is ignored, while the whitespace in the first suffix line (after "#VALUE#") is part of the suffix:

{{#Placeholder       Prefix First Line¶
Prefix Second Line#Value#     Suffix First Line¶
Suffix Second Line}}

Prefix and suffix with line breaks, with line breaks before the first lines and after the last lines.
Note that the whitespace and the linebreak on the first line is not part of the prefix because if the first line contains only whitespace and a linebreak after "#NAME", then both the whitespace and the linebreak are ignored. In comparison, the whitespace and the linebreak immediately after "#VALUE#" are a part of the suffix; therfore, the suffix has actually three lines (where the first line is empty except for whitespace).
Note also that the prefix ends with a linebreak so the content will start on a new line after the prefix. Similarly, the suffix ends with a linebreak; therefore, whatever comes after the placeholder will start on a new line after the suffix:

{{#Placeholder ¶
Prefix First Line¶
Prefix Second Line¶
#Value# ¶
Suffix Second Line¶
Suffix Third Line¶
}}

So, the example of above could be written as follows instead:

<ul> {{#Placeholder_1 <li>#VALUE#}} {{#Placeholder_2 <li>#VALUE#}} {{#Placeholder_3 <li>#VALUE#}} {{#Placeholder_4 <li>#VALUE#}} {{#Placeholder_5 <li>#VALUE#}} </ul>

Which after replacement would then be rendered as desired (three placeholders filled out, two left empty):

#TITLE# in a Binary Placeholder Prefix/Suffix

If the placeholder is a placeholder of one of the "Binary" types, then the special #TITLE# attribute may be used anywhere in the prefix and/or suffix of that placeholder (it may even appear several times).

If the #TITLE# attribute is used, then when the placeholder is filled out during content definition, the user will have the option of not only providing the binary source for the placeholder, but also a title text. This title text will then be used to replace the #TITLE# attribute wherever it appears in the prefix or suffix.

The main use for this attribute is to provide the text for the "title" and/or "alt" attribute of the <img> tag that the binary placeholder is used to generate, for example like this (prefix and suffix color coded like above):

{{#BinaryPlaceholder <img src="#VALUE#" title="#TITLE#" alt="#TITLE#">}}

Note, how in the example the <img> tag is opened in the placeholder prefix and closed in the placeholder suffix, and that the #TITLE# attribute appears in the suffix as a stand-in for the yet to be supplied "title" and "alt" attributes.

#WIDTH# in a Binary Placeholder Prefix/Suffix

If the placeholder is a placeholder of one of the "Binary" types, then the special #WIDTH# attribute may be used anywhere in the prefix and/or suffix of that placeholder (it may even appear several times).

If the #WIDTH# attribute is used, then when the placeholder is filled out during content definition, the image's width (in pixels) will be used to replace the #WIDTH# attribute wherever it appears in the prefix or suffix.

The main use for this attribute is to provide the value for the "width" style of the <img> tag that the binary placeholder is used to generate, for example like this (prefix and suffix color coded like above):

{{#BinaryPlaceholder <img src="#VALUE#" style="width:#WIDTH#px">}}

Note, how in the example the <img> tag is opened in the placeholder prefix and closed in the placeholder suffix, and that the #WIDTH# attribute appears in the suffix as a stand-in for the yet to be determined image width.

The #WIDTH# attribute also allows the specification of an additional width value. This additional width value will be added to the actual image width, and the total result will be used to replace the #WIDTH# attribute. The additional width is specified with a "+", followed by a numeric value, just before the closing "#" character. For example like this:

{{#BinaryPlaceholder <img src="#VALUE#" style="width:#WIDTH+150#px">}}

In the above example, the #WIDTH+150# attribute will be replaced with a value that equates to the actual width of the image (in pixels) plus 150.

"Multiple Values" Placeholders with Prefix/Suffix

The prefix and suffix have an especially important role when used together with placeholders that may have multiple values ("Plain Text (multiple values)" or "HTML (multiple values)" placeholders, see above):

The multiple values of these placeholders are concatenated to each other and the resulting combined value is then used to replace the placeholder. This by itself is not very useful, as the user could just as well have supplied the multiple values already as one combined text in a normal single value placeholder. However, multiple value placeholders become useful when a prefix and/or suffix are employed because the prefix/suffix is added individually to each of the supplied multiple values, and only then are the multiple values concatenated together to build the final replacement value. This means that if a prefix and/or suffix is defined, and the user later supplies several values for the placeholder, then not only will the prefix appear before and the suffix after the supplied value, but the prefix and/or suffix will also appear between the various multiple values.

This, in turn, is very useful if the template manager wants to define a list of items without already knowing how many items there are going to be.

Consider the example above with the bulleted list. As the example was defined, the template manager had set up a bulleted list with up to five bullets. Since the bullet definition (the <li> tag) was defined in the prefix, any empty bullets were effectively avoided should the user decide not to provide values for some of the placeholders.

So far so good. The only problem being that the maximum number of bullets was predefined as five by the template manager. If the user later would want to add a sixth bullet, then he would have to ask the template manager to change the template.

With a multiple values placeholder, this problem is avoided. In this case, the definition of the bulleted list in the template would simply look something like this:

<ul> {{#MultiPlaceholder <li>#VALUE#}} </ul>

And of course the "MultiPlaceholder" placeholder would have to be defined to be the "HTML (multiple values)" type.

Then, it would be up to the user to decide how many values to supply for this placeholder:

If no value is supplied at all (only allowed if the placeholder is also not mandatory), then the placeholder would simply be replaced with an empty string (and thus the "<li>" tag would also not appear, since it is defined in the prefix, which is not rendered for an empty optional placeholder).

If only a single value is supplied, then the placeholder behaves just like a normal placeholder. The value is used to replace the "#VALUE#" part, and the result, including the prefix "<li>" would be used to replace the placeholder, so the resulting HTML code would look something like this:

<ul> <li>Single value here... </ul>

But, if several values are supplied, then the multi-behavior comes into play. Each of the values would be used individually to replace the "#VALUE#" part, and the prefix "<li>" would be added to each of the values. Then, the result for all values would be concatenated together and used to replace the placeholder. So the resulting HTML code would look something like this (sample with four values supplied, line breaks added for readability):

<ul> <li>First value here... <li>Second value here... <li>Third value here... <li>Fourth value here... </ul>

And, the length of this bulleted list would only depend on how many values the user supplies when using the template during a content definition.

#INDEX# in a Multiple Values Placeholder Prefix/Suffix

Another useful feature for multiple values placeholders is the "#INDEX#" attribute that can be used in the prefix and/or suffix. Any appearance of this attribute will be replaced with the index number of the multi-value. For example, assume the following template definition, where "MultiPlaceholder" is of the "HTML (multiple values)" type:

{{#MultiPlaceholder <p>#INDEX#. Paragraph: #VALUE#</p>}}

Now assume that the user fills out this placeholder with four values. Then the resulting HTML code would look something like this (line breaks added for readability):

<p>1. Paragraph: First value here...</p> <p>2. Paragraph: Second value here...</p> <p>3. Paragraph: Third value here...</p> <p>4. Paragraph: Fourth value here...</p>

The above is an example of how the #INDEX# attribute can be used to generated a numbered list where a normal ordered list using the <ol> tag would not be appropriate, or in a plain text, where this tag can not be used.

Another useful case where the #INDEX# attribute can be employed is to generate a unique HTML-ID or unique links and unique link anchor names:

<!-- Example with multi-placeholder that generates a unique HTML-ID, per multi-value: --> <table> {{#TableRow <tr><td id="ValueCell-#INDEX#">#VALUE#</td></tr>}} </table> <!-- multi-placeholder that generates a unique link anchor, per multi-value: --> {{#ParagraphWithAnchor <a name="Paragraph-#INDEX#"><p>#VALUE#</p></a>}} <!-- multi-placeholder that generates a unique link to the above anchor, per multi-value: --> {{#LinkToAnchor <a href="#Paragraph-#INDEX#">#VALUE#</a><br>}}

Assuming that "TableRow", "ParagraphWithAnchor", and "LinkToAnchor" are defined as multiple value placeholders, and assuming that the user supplies five values for TableRow, three values for ParagraphWithAnchor and matching three values for "LinkToAnchor", then the resulting HTML would look something like this (line breaks added for readability):

<!-- Example with multi-placeholder that generates a unique HTML-ID, per multi-value: --> <table> <tr><td id="ValueCell-1">First cell value here...</td></tr> <tr><td id="ValueCell-2">Second cell value here...</td></tr> <tr><td id="ValueCell-3">Third cell value here...</td></tr> <tr><td id="ValueCell-4">Fourth cell value here...</td></tr> <tr><td id="ValueCell-5">Fifth cell value here...</td></tr> </table> <!-- multi-placeholder that generates a unique link anchor, per multi-value: --> <a name="Paragraph-1"><p>First paragraph value here...</p></a> <a name="Paragraph-2"><p>Second paragraph value here...</p></a> <a name="Paragraph-3"><p>Third paragraph value here...</p></a> <!-- multi-placeholder that generates a unique link to the above anchor, per multi-value: --> <a href="#Paragraph-1">Click here to go to the first paragraph...</a><br> <a href="#Paragraph-2">Click here to go to the second paragraph...</a><br> <a href="#Paragraph-3">Click here to go to the third paragraph...</a><br>

Note, how each table cell has a unique ID and each paragraph a unique anchor name and how the links at the bottom each point to one of these unique anchors.

If two placeholders are used in this way, i.e. one to generate link anchors and one to generate the matching links to those anchors, then this will only work if the user who employs the template during content definition makes sure that both placeholders have the same number of values, and that the ordering of the values in both placeholders matches; otherwise, the links will point to the wrong anchors or there will be links without anchors or anchors without links pointing to them.

Note: Any occurrence of the #INDEX# attribute in the prefix/suffix of a normal (non-multiple value) placeholder will not be replaced. This attribute shows its special behavior only in the prefix/suffix of a multiple value placeholder.

Multi-Placeholder Repeater

As described above, using a placeholder with multiple values, usually together with the placeholder prefix/suffix, is very useful for creating a list of user supplied items, where the number of items is not known in advance.

However, this alone does not cover a situation like the following: Assume that the template is meant for a newsletter, where each article in the newsletter is supposed to appear with a heading, a sub-heading and a body, all with different styles, something like this:

Article Heading
Article Sub-Heading
Article Body goes here....

where the matching HTML code looks like this:

<div style="font-weight:bold; font-style:italic; margin-bottom:10px">Article Heading</div> <div style="font-size: 8pt; font-style:italic; margin-bottom:5px">Article Sub-Heading</div> <div style="font-family: serif;">Article Body goes here....</div>

One solution would be to simply have a placeholder called "article" and make this placeholder a multi-value placeholder so that there could be several articles. That would mean that each of the values would constitute one article. However, this would mean that the heading, sub-heading, and body of each article would all have to be supplied in the article's value, which would mean that also the special styles for the heading and subheading would have to be supplied in the value by the user who employs the template during content definition.
That way, the definition of the heading, sub-heading, and body styles would be out of the hands of the template manager and would become the responsibility of the user who employs the template during content definition, which is probably not what is desired.

The other solution one could think of would be to have three placeholders: One called "heading", one "sub-heading", and one "body", and all three would be defined as multiple values placeholders and each could contain the correct styles in the prefix/suffix. The user who employs the template during content definition would then simply have to take care to supply the correct headings, sub-headings, and bodies of all desired articles as the multiple values of each of these placeholders, making sure to supply them in the correct order in all three placeholders and to supply an equal number of values for all. The styles for each would then be supplied automatically, by the prefix/suffix mechanism.

But, there would still be a problem because the correct way to put these three placeholders into the template code would be like this:

{{#heading <div style="font-weight:bold; font-style:italic; margin-bottom:10px">#VALUE#</div>}} {{#sub-heading <div style="font-size: 8pt; font-style:italic; margin-bottom:5px">#VALUE#</div>}} {{#body <div style="font-family: serif;">#VALUE#</div>}}

The result after replacement (assuming that three values were supplied for each of the three multi-value placeholders) would look like this:

First Heading Value
Second Heading Value
Third Heading Value
First Sub-Heading Value
Second Sub-Heading Value
Third Sub-Heading Value
First Article Body Value
Second Article Body Value
Third Article Body Value

Which is because each of the three multiple values placeholders would simply iterate over all its values, followed by the values of the next placeholder, and so on, which is obviously not the desired result. Instead, what would be desired would be if the values of the three multiple values placeholders could be repeated in an alternating fashion: The first heading, followed by the first sub-heading, followed by the first body, only then followed by the second heading, followed by the second sub-heading, and so on...

LISTSERV Maestro does provide a mechanism for this special behavior of the multiple values placeholders, in form of the multi-placeholder repeater. The syntax of the repeater looks similar to the syntax of a placeholder, even though the repeater is not really a placeholder by itself. The simple form without a separator looks like this:

{{#multi:repeat BODY}}

The full form with a separator looks like this:

{{#multi:repeat BODY{{#multi:separator}}SEPARATOR}}

With the following replacements:

The body text and the separator text of the repeater can both contain any kind of text, including template placeholders and even further nested repeater tags. Actually, the repeater only really makes sense if the body contains at least one template placeholder, which also is defined as a multiple values placeholder. And to be really useful, a repeater usually contains at least two multiple values placeholders because the behavior of the repeater is defined as follows:

All occurences of multiple values placeholders in the repeater body are examined. For each such multi-value placeholder the number of values (as supplied by the user) is determined. The maximum number of values over all multi-values placeholders then defines the repeat count. Or in other words: The multi-value placeholder in the repeater body with the most values defines the repeat count of the repeater.

The repeater is then replaced with as many instances of the repeater body as defined by the repeat count, all concatenated together into one long value. During each such instance of the repeater body, each multi-value placeholder which occurs in the body will display only one value from its multi-value list, which is the value that matches the current repeat instance.
I.e. in the first body instance, all multi-value placeholders will display only their first values. In the second instance, each will display only its second value (if any), and so on.

If a separator is defined, then between two instances of the repeater body, one instance of the separator text is inserted. The separator appears only between two instances, it does not appear before the first instance or after the last one.

Note: When using a multi-placeholder repeater in a HTML context, then line breaks usually do not matter, so you can use them to format the repeater in a way that works best for you. However, when using a repeater in a plain text context, then any line breaks that appear in the BODY or SEPARATOR blocks actually do matter, as they become part of the block they belong to. This is especially also true for line breaks that appear just before or after the {{multi:separator}} tag or just before the closing "}}" tag of the repeater itself.

To illustrate the repeater, we use the same example as above with the article with heading, sub-heading and body, where we also want to have a horizontal line between two articles (but not before or after the first and last articles):
The same three placeholders "heading", "sub-heading" and "body" as used above are required, and all three must be defined as multiple values placeholders. The correct code then looks like this:

{{#multi:repeat {{#heading <div style="font-weight:bold; font-style:italic; margin-bottom:10px">#VALUE#</div>}} {{#sub-heading <div style="font-size: 8pt; font-style:italic; margin-bottom:5px">#VALUE#</div>}} {{#body <div style="font-family: serif;">#VALUE#</div>}} {{#multi:separator}} <hr> }}

And the result after replacement (assuming again that three values were supplied for each of the three multi-value placeholders) would look like this, just as desired:

First Heading Value
First Sub-Heading Value
First Article Body Value
Second Heading Value
Second Sub-Heading Value
Second Article Body Value
Third Heading Value
Third Sub-Heading Value
Third Article Body Value

Drop-In Content

Please see here for a general description of drop-in content elements.

To use drop-in content in your template, it must be enabled. This is done on the Template Properties page of the template.

Drop-ins do also use an opening and a closing tag. These tags are used by LISTSERV Maestro to identify the names of the drop-in content. In content templates, the opening and closing tags used for drop-ins must be the same as used for the template placeholders (see above). Therefore, changing the tags for drop-ins also changes the tags for the template placeholders and vice versa. Opening and closing tags can be any characters you like that do not contain any spaces. "{{" and "}}" are suggested as defaults, but you may change them.

To include drop-in content in your template, simply enter the name of the drop-in at the appropriate location, enclosed in the tags you have defined. For example, if your drop-in is called "sample" and you are using the suggested default tags, then you would include the text "{{sample}}" in the location where you want the drop-in content to appear in the final message.

Whenever LISTSERV Maestro finds the opening tag followed by the closing tag, it will interpret all the characters in between first as a template placeholder name. If no placeholder with this name is found, then the name is interpreted as the name of a drop-in. LISTSERV Maestro will then look up the list of available drop-ins for a drop-in with this name. If the name is not found, delivery of the mail fails with an error message like "Drop-In with name 'XYZ' not found".

If drop-in content is disabled, any drop-in placeholder names that might appear in the message will not be replaced with the corresponding content. Instead, the placeholder names will appear verbatim in the body of the message.

© 2002-2017 L-Soft Sweden AB. All rights reserved.