Template Class

One of the most common uses for templates is as the basis for the body of an email message. To see an example of how to use a Template see IEmailService.

The most common format for a template is HTML, but, depending on how it is being used, any text format is supported. Templates support substitution markers whose name/value pairs are typically provided in a NameValueCollection when the template is resolved using one of the various Replace or Expand methods.

The markers may take two forms:

• {{itemName}} - The marker replacement text should be escaped for HTML using TextToHtml(String, TemplateReplaceFlags).
• [[itemName]] - The marker replacement text should not be escaped for HTML.

When populated from a IMapper default markers will, by default, be substitued using the DisplayText of the corresponding IField (obtained via DisplayTextGet(DispTextFlags)). However, an optional marker prefix may be included to specify otherwise (see TemplateNodeMarker). For example, {{&first_name}} would mean that the marker should be replaced with the HTML-escapted text for the "first_name" field's caption.

• & - Caption: Use the field's Caption.
• * - RawValue: Use the field raw value.
• + - ImmediateEdit: Substitute for use with ImmediateEdit. This only applies to page content, but not to email templates and similar.
• / - NavLink: Substitute with a field's NavLink. NavLink marks should not be escaped (that is, always use the '[[]]' delimiters).
• % - Template: Substitute with the expanded content of the specified inner template. Template marks should generally not be escaped (that is, generally use the '[[]]' delimiters). A template marker may optionally include a set of name/value pairs used in expanding the inner template. Any name/value pairs provided will override the corresponding of name/value pairs provided to the outer template. The syntax for a template reference is %<template-name>[:name1=value1;name2=value2...] (wrapped in an outer [[]] or {{}}). A colon is used to separate the optional name/value list, a semi-color separates each name/value pair, and an equals sign separates each name from its value.
• # - Numeric: Substitute with a numeric field's raw value or 0 (zero) when null/empty.
• = - HasValue: Substitute with "1" or "" (empty string) depending on whether or not the field's DisplayText has a non-null/non-blank value.

Templates are commonly used for the following purposes:

• General email body layout and content using IEmailService.
• Email body layout and content via an IMapper using a Send overload such as Send(String, String).
• MiniDetail page element layout, specified via its Template property.
• WizMiniDetail page element layout, specified via its Template property.
• LiteralContent page element layout, specified via its Template property.
• MapperSummary page element layout, specified via its Template property.
• MapperSummary field layout, specified via its SummaryTemplate property.
• Wizard primary summary content and layout, specified via its SummaryTemplate property.
• Programmatic HTML generation using ExpandTemplate with Exec(MapperExecCmds, Enum, Object).
• PDF generation using IPDFDocument.

Templates also support events fired to TemplateExtensionBase components:

• PluginPreRender - Fired when a Plugin template is about to be rendered.

Examples

Dear {{first_name}} {{last_name}},
<br />
Thank you contacting us regarding interest in our {{product_name}} product.  One of our sales people will contact
you shortly to help you with any questions you may have and to aid in ordering.
<br />
Additional information is available at [[product_url]].
<br />
Sincerely,
<br />
{{company_name}}