LISTSERV Maestro 11.1-2 Help Table Of Contents

Edit Content Template

To access the editor page for a click-and-fill template, select the node of the desired template in the templates tree. Then select Open Template Definition from the menu (or go via the right-click menu of the template node in the templates tree).

Define the email 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 [Save Template] button. To exit without storing, click in the menu bar.

The editor consists of the main panel that displays the actual editor and an additional panel with various sections on the right.

In this panel on the right, each section can be opened and closed separately, so that you only need to see the content of those sections that are currently of interest to you. Simply click on a section header to open/close this section.

The available tabs in the main panel 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. (The tabs to switch between "HTML" and "Text" are shown as vertical side-tabs at the very left of the main panel.)

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

The panel on the right contains the following sections:

Placeholders

This panel lists all template placeholders that are currently defined in this template. Click on a placeholder to open a menu that allows you to:

  • Insert the selected placeholder at the cursor position.

  • Edit the selected placeholder.

  • Create a new placeholder as a Copy of the selected placeholder.

  • Delete the selected placeholder.

Fluid Design Widgets

This panel section shows the available fluid design widgets that you can use in the HTML content.

Fluid design (often also called "responsive design") is a design principle under which the HTML content is created in such a fashion that it looks nice and readable on a variety of email clients, both with large and small screens, on computers or handheld devices.

To add a fluid design widget to your HTML content, simply place the cursor at the target location, then click on the desired widget in the fluid design widgets panel section. Or simply drag & drop a widget from the options panel section into the HTML code.

You have the choice between several different widget types. These widgets can also be nested into each other. See here for more details about the available widget types and how to use the fluid design widgets.

Fluid Design Widget Default Font

This panel section allows you to select the default font that is to be used by the fluid design widgets. Simply click one of the available fonts to select it and select its default size at the top of the panel. This default font is then automatically applied to all widgets. More precisely: The selected font is set as the default for all widgets but does not affect any text that is not contained in a fluid design widget.

In the widgets, where necessary you can of course always override this default with individual font settings, for example for certain paragraphs or words.

Merge Fields

This panel section shows all available merge fields. Click on a merge field name to insert it into the editor at the current cursor position.

Drop-Ins

This panel lists all user-defined and system drop-ins. (Except for the social media sharing system drop-ins, see "Social Media" section below).

Click on a drop-in name to insert it into the editor at the current cursor position. Hover the mouse pointer over a drop-in name to see a short description of what this drop-in will do. See also here.

Social Media

This panel section allows you to integrate social media sharing and publishing into your email. See here for more details.

Social Media Sharing

By embedding the social media sharing icons (or similar links) into your message, you enable the recipients to easily share your message with other people, on various social media.

You can either include the full {{*SocialMedia}} system drop-in or one of the specific ShareURL drop-ins.

Click on a drop-in name to insert it into the editor at the current cursor position. Hover the mouse pointer over a drop-in name to see a short description of what this drop-in will do.

HTML Template

For an HTML template, define the following values:

  • Subject: The subject line of the template. Leave empty if you want the subject to be supplied during content definition instead.

  • HTML Content: The HTML content editor has two modes:

    In Preview Mode you view the HTML message as it actually appears, with dummy content displayed for any template placeholders (see below) and with all drop-in elements resolved (if drop-ins are enabled and any are present). If errors have been encountered during this placeholder and drop-in replacement, then these problems are highlighted in the HTML preview.

    In Code Mode you edit the HTML message by editing the underlying HTML code directly. You can switch between preview and code mode at any time with the icons at the top left of the editor toolbar.

    To define the body, you can upload a HTML file (via the main menu) or type HTML code directly into the editor, in code mode. An uploaded HTML file may contain links to images on a remote server or local images embedded in the page.

    You can also use the fluid design widgets in the HTML body.

    You can also download the current HTML content via the main menu.

    To add a new placeholder to the template, click Insert New Placeholder in the code mode editor toolbar.

  • Alternative Text Content: This tab is available only if the plain text alternative option for the HTML template is enabled. The alternative text content editor has two modes:

    In Preview Mode you view the alternative text message as it actually appears, with dummy content displayed for any template placeholders (see below) and with all drop-in elements resolved (if drop-ins are enabled and any are present). If errors have been encountered during this placeholder and drop-in replacement, then these problems are highlighted in the text preview.

    In Code Mode you edit the alternative text message directly. You can switch between preview and code mode at any time with the icons at the top left of the editor toolbar.

    To add a new placeholder to the template, click Insert New Placeholder in the code mode editor toolbar.

    The alternative text is a plain text body that is an "alternative" for the more elaborate HTML body of the template. When used for a message, then recipients whose email client does not display HTML may default to the plain text alternative allowing them to receive a message. To reach the highest number of recipients, it is generally a good idea to use an alternative text with each HTML message.

Plain Text Template

For a plain text template, define the following values:

  • Subject: The subject line of the template. Leave empty if you want the subject to be supplied during content definition instead.

  • Text Content: The text content editor has two modes:

    In Preview Mode you view the plain text message as it actually appears, with dummy content displayed for any template placeholders (see below) and with all drop-in elements resolved (if drop-ins are enabled and any are present). If errors have been encountered during this placeholder and drop-in replacement, then these problems are highlighted in the text preview.

    In Code Mode you edit the plain text message directly. You can switch between preview and code mode at any time with the icons at the top left of the editor toolbar.

    To add a new placeholder to the template, click Insert New Placeholder in the code mode editor toolbar.

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 email delivery failure.

To create a new placeholder, simply click Insert New Placeholder in the toolbar of the code mode editor.

If you simply want to insert an already existing placeholder somewhere in the current editor, then you can either type its {{#NAME}} tag or you can open the Placeholders section in the panel on the right and click on the desired placeholder. Then select Insert at Current Cursor Position from the popup menu.

Placeholders have various attributes that determine their appearance and behavior. These attributes can be defined during placeholder creation (see above) or by editing an existing placeholder.

To do the latter, open the Placeholders section in the panel on the right and click on the placeholder you want to edit. Then select Edit from the popup menu.

The following placeholder attributes can be edited:

  • Name: The name of the placeholder. This is the name that you must use as a replacement for NAME in the {{#NAME}} tag. Only the following characters are allowed in a placeholder name: 'a'-'z', 'A'-'Z', '0'-'9', '_', and '-'.

  • Display Title: This is the title or name of the placeholder that will be displayed to users that employ the template during content definition. Enter a title that makes it easy for the user to understand the purpose of the placeholder.

  • Mandatory: Defines if the placeholder is mandatory or not. For a mandatory placeholder, the user who employs the template during content definition must supply a non-empty content. For an optional placeholder, the user may decide to leave the placeholder empty.

  • Value Type: Defines the type of placeholder content:

    Single Value Placeholders:

    • Plain Text: The placeholder's content will be interpreted literally, as plain text. If the placeholder is used in a HTML part, then any special HTML code characters in the content will be escaped before replacement. Therefore, it will not be possible to include any HTML formatting (like bold, color, font, etc.) in a placeholder of this type.

    • HTML: The placeholder's content will be interpreted depending on the context:

      If the placeholder appears in the HTML part of a message, then the HTML code appears unescaped and will be interpreted as normal HTML. This allows the user who employs the template during content definition to include HTML formatting code in the placeholder value (e.g. for attributes like underline, bold, color, font, etc.), but it also requires the user to remember to manually escape any HTML-sensitive characters that are not be supposed to be interpreted as HTML code.

      If such a placeholder is used in the plain text part of a message, then the HTML code that the user enters will be converted automatically to plain text (see below).

      If the placeholder appears both in the HTML and the plain text part of a message, then each of the above applies for each respective part, i.e. in the HTML part the placeholder's value will be interpreted as HTML, in the plain text part it will automatically be converted to plain text.

      For example, it is therefore safe for the user to use simple formatting tags (like <b> or <u> for bold or underlined style) so that in the HTML part some special formatting will be applied (even if the same placeholder appears in the plain text part) because these tags will automatically be removed.

      However, the user should avoid complicated HTML code in such placeholders, as the rules by which the HTML code is converted into plain text are rather simple: Any HTML entities (for example like "&amp;" or "&quot;") will be resolved into the correct replacement character. Any paragraph and linebreak tags (<p>, <br> and similar) will be converted to normal line breaks. Any occurrences of ordered or unordered lists with list entries (<ol>, <ul> and <li>) will be converted into simple ordered/unordered lists. All other HTML tags will simply be removed.

    • Image: This is a special placeholder that allows the template manager to define an image in the HTML template of which the actual content is not yet known but will be supplied later by the user who employs the template during content definition.

      During content definition the placeholder will be replaced with a URL to the image, which is why this type of placeholder should be used only in a context in the HTML code where such a URL makes sense.
      Normally the placeholder would stand in for an image and would appear in the "src" attribute of an "<img>" tag, like this: 

      <img src="{{#SampleBinaryPlaceholder}}">

      Placeholders of this type can only be used in the HTML part of a HTML template.

    Multiple Values Placeholders:

    • Plain Text (multiple values): Same as the "Plain Text" type above, but the user who employs the template during content definition has the option of supplying multiple values for the placeholder. The placeholder will be replaced with the combined multiple values (concatenated to each other). This is most useful when used with the multi-placeholder repeater (see here) and/or the special placeholder fixed content (see here) because the fixed content will appear once with each of the multiple values before they are concatenated to build the combined replacement value.

      Select from the values in preview drop-down list how many dummy values shall be displayed for this placeholder during preview (when no values have been supplied yet).

      Only the two plain text placeholder types (see also above) are allowed to be used in a plain text template or in the alternative text of a HTML template.

    • HTML (multiple values): Same as the "HTML" type above, but the user who employs the template during content definition has the option of supplying multiple values for the placeholder. The placeholder will be replaced with the combined multiple values (concatenated to each other). This is most useful when used with the multi-placeholder repeater (see here) and/or the special placeholder fixed content (see below) because the fixed content will appear once with each of the multiple values before they are concatenated to build the combined replacement value.

      From the values in preview drop-down list, select how many dummy values will be displayed for this placeholder during preview (when no values have been supplied yet).

    • Image (multiple values): Same as the corresponding "Image" type above, but the user who employs the template during content definition has the option of supplying multiple images for the placeholder. The placeholder will be replaced with a concatenated list of the URLs of all supplied images. This is most useful when used with the multi-placeholder repeater (see here) and/or the special placeholder fixed content (see below) because the fixed content will appear once with each of the multiple URLs before they are concatenated to build the combined replacement value, which allows you to enclose each of the URLs with its own <img> tag, which actually displays the image.

      From the values in preview drop-down list, select how many dummy images will be displayed for this placeholder during preview (when no images have been supplied yet).

      Placeholders of this type can only be used in the HTML part of a HTML template.

  • Sample Preview: There are several situations where the template is supposed to be displayed while the placeholders are not yet filled out with any content. In these situations, LISTSERV Maestro fills out the placeholders with dummy content as a stand-in for the actual content that is yet to be provided, which makes it easier to assess the overall appearance of the template while the placeholders are still empty.

    The kind of dummy content that is to be used for this can be roughly defined by the content manager, depending on the type of the placeholder:

    • Dummy Text: For placeholders of type "Plain Text" and "HTML" there are several choices to roughly define which kind of dummy text shall be displayed. The choices are:

      • Some / Many Words
      • Some / Many Sentences
      • Some / Many Paragraphs
      • Some / Many Digits
      • Some / Many Letters
      • Sample URL

      Note: The dummy text should be selected according to the kind of content that you expect to be provided by the user for the given placeholder. For example, if the placeholder appears in a context where it will be filled out with a number (like a ZIP-code or phone number), then the choice "Some Digits" would be the closest match. If the placeholder will most likely be filled out with a lot of text, then "Many Paragraphs" is probably better.
      The "Sample URL" choices is a special choice, which will result in a replacement that looks like a dummy "http://" URL. This type is most appropriate if the expected content too will most likely be a URL, for example in a context like "Click this URL: {{#Placeholder}} to go to...".

    • Dummy Images: For placeholders of the image types, the following choices are available to display dummy images:

      • No Sample Image
      • Small Square (20x20 Pixel)
      • Medium Square (100x100 Pixel)
      • Large Square (500x500 Pixel)
      • Small Vertical Oblong (10x20 Pixel)
      • Medium Vertical Oblong (50x100 Pixel)
      • Large Vertical Oblong (250x500 Pixel)
      • Small Horizontal Oblong (20x10 Pixel)
      • Medium Horizontal Oblong (100x50 Pixel)
      • Large Horizontal Oblong (500x250 Pixel)

      Note: The sizes of the dummy images will only be observed if the <img> tag itself does not have any "width" or "height" attributes. If these attributes are present, then they override the sizes of the selected dummy image and the image will be stretched or shrunk accordingly.

  • Disabled Placeholder Highlighting in HTML: Only available for "Plain Text" or "HTML" placeholders (for binary placeholders highlighting is always disabled).

    In certain situations, where the template is being displayed to the user, Maestro attempts to highlight the currently selected placeholder with a high contrast background color so that the user can more easily see which placeholder is selected.

    This highlighting is achieved by embedding additional HTML code into the previewed template (embedded during the preview only). In some situations, this additionally embedded HTML code may disrupt the actual HTML code of the template that surrounds the placeholder so that the HTML is not interpreted correctly, making the template appear "broken".

    In these cases, it is best to disable the highlighting of the placeholder. This can be done with this option. Or more precisely: If this option is checked, then any appearances of the placeholder in the HTML part of the template will no longer be highlighted. However, appearances in the plain text part (if any) will always be highlighted.

Additional Fixed Content 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>
		<li>{{#Placeholder_2}}</li>
		<li>{{#Placeholder_3}}</li>
		<li>{{#Placeholder_4}}</li>
		<li>{{#Placeholder_5}}</li>
	</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):

  • Content of first placeholder
  • Content of second placeholder
  • Content of third placeholder

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 Maestro use a special syntax that allows you to define additional fixed content for the placeholder, which is used in addition to the content that the user supplies, but not if the user does not enter any content of his own. This means that the fixed content appears only if the user actually supplies a non-empty content.

A placeholder with fixed content is specified like this:

	{{#NAME fixed_content_before#VALUE#fixed_content_after}}

where:

  • The string #NAME is replaced with the actual placeholder name.
  • The string #VALUE# (including the "#" enclosing characters) must appear at least once (but can also appear multiple times), embedded into the additional fixed content.
  • Fixed content may appear before and/or after the #VALUE# field, and if there are several occurrences of this field, then also between these occurrences.
  • The fixed content may contain line breaks. The line breaks will become part of the fixed content.
  • Any characters after #NAME and before #VALUE# will be part of the fixed content, including all line breaks (even line breaks that appear immediately before #VALUE#), except for any whitespace that follows immediately after the word #NAME and that appears on the same line as the word #NAME. Such whitespace is ignored. Also, if the first line contains only whitespace after the word #NAME, then the linebreak at the end of this line will also be ignored and will not be part of the fixed content. (See below for examples.)
  • Any characters after #VALUE# and before the closing tag "}}" (or whatever closing tag is applicable in your template) will be part of the fixed content, including all line breaks, even line breaks that appear immediately after #VALUE# or before the closing tag "}}". (See below for examples.)

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 fixed content 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 from the fixed content, in which all occurences of #VALUE# are replaced with the user supplied content. In other words, in the string text_before#VALUE#text_after the #VALUE# part (including the enclosing "#" characters) is replaced with the user content, and the resulting string (including text_before and text_after) is used to replace the placeholder.

The following shows some examples for placeholders with a fixed content. In the examples, line breaks are shown as "" for better readability, and the fixed content is marked with a yellow background.

Examples

  • Simple fixed content:

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

  • Fixed content with line breaks:

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

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

  • Fixed content 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 fixed content 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 fixed content; therefore, 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¶
	}}

  • Fixed content with multiple occurrences of #VALUE#:

    As explained above, it is allowed to include the #VALUE# field multiple times in the fixed content. In this case, each occurrence of the field is replaced with the same user supplied placeholder value.

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

    This is especially useful if you want to create a placeholder that renders a clickable URL, if the user supplies a URL, and that does not render anything at all, if the user does not supply a URL:

    	{{#Placeholder <a href="#Value#">#Value#</a>}}

    If the users supplies a URL as the placeholder value, for example http://example.com, then the above placeholder renders the following code:

    	<a href="http://example.com">http://example.com</a>

    Which of course renders as a proper clickable URL in the browser, like this: http://example.com

  • The example from the beginning of this sub-section could be written as follows instead:

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

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

    • Content of first placeholder
    • Content of second placeholder
    • Content of third placeholder

#TITLE# in a Binary Placeholder Fixed Content

If the placeholder is a placeholder of one of the "Binary" types, then the special #TITLE# attribute may be used anywhere in the fixed content 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 fixed content.

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 (fixed content color coded like above): 

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

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

#WIDTH# in a Binary Placeholder Fixed Content

If the placeholder is a placeholder of one of the "Binary" types, then the special #WIDTH# attribute may be used anywhere in the fixed content 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 fixed content.

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 (fixed content color coded like above): 

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

Note, how in the example the <img> tag is opened in the fixed content and closed in the fixed content, and that the #WIDTH# attribute appears in the fixed content 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.

The #WIDTH# attribute also allows the specification of a maximum width value. This maximum width value restricts the actual image width when it replaces the #WIDTH# attribute. The maximum 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?320#px">}}

In the above example, the #WIDTH?320# attribute will be replaced with either the actual width of the image (in pixels) or 320, whichever is smaller.

It is also possible to specify both the additional width and the maximum width. If both are specified, the additional width must come first and the maximum width second, like so:

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

 

"Multiple Values" Placeholders with Fixed Content

The fixed content has 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 fixed content employed because the fixed content 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, 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 fixed content, 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#</li>}}
	</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 fixed content, 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 <li> from the fixed content, would be used to replace the placeholder, so the resulting HTML code would look something like this:

	<ul>
		<li>Single value here...</li>
	</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 <li> from the fixed content 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>
		<li>Second value here...</li>
		<li>Third value here...</li>
		<li>Fourth value here...</li>
	</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 Fixed Content

Another useful feature for multiple values placeholders is the "#INDEX#" attribute that can be used in the fixed content. 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 fixed content of a normal (non-multiple value) placeholder will not be replaced. This attribute shows its special behavior only in the fixed content of a multiple value placeholder.

Multi-Placeholder Repeater

As described above, using a placeholder with multiple values, usually together with the placeholder fixed content, 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 fixed content. 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 fixed content 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...

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:

  • Opening and closing tags: The "{{" and "}}" of above must be replaced with the correct template placeholder opening and closing tags of your template.
  • Repeater Body: The word "BODY" must be replaced with the body text that shall actually be repeated by this repeater, i.e. the repeater will be replaced with one or more instances of this body text (more about this below).
  • Repeater Separator: The word "SEPARATOR" must be replaced with the separator text that shall appear between two instances of the body text. Such a separator is optional (use the simple form described above if you do not want to specify a separator - more about this below).

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 occurrences 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 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 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. 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 email 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-2023 L-Soft Sweden AB. All rights reserved.