FormattedText
FormattedText is a data container that can hold text with formatting options (among others bold, italics, underline, breaks or even Word-specific formatting).
Regardless of the context, FormattedText is technically HTML:
<p>Erstellt mit: <b>primedocs</b>!</p>
Created with: primedocs!
FormattedText is ideal for mapping simple formatting options that can be used in Word, PowerPoint or Outlook templates.
Product-specific formatting options can also be stored in FormattedText, so that, for example, a paragraph in Word can be equipped with a style.
Syntax
FormattedText occurs in primedocs as...
- a Field type, so it can be generated as code, whereby FormattedText can be fetched as a Snippet or global translation.
- the type of a global translation
- a Snippet type.
HTML Elements
The following lists show all possible HTML elements and their attributes that can be used in the templates.
Word template types
Elements:
<p>Paragraph</p>
<span>Span</span>
<sup>hochgestellt</sup>
<sub>tiefgestellt</sub>
<u>unterstrichen</u>
<i>kursiv</i>
<em>kursiv</em>
<b>fett</b>
<strong>fett</strong>
<br />
<custom-tab />
Attributes on span and p:
"data-office-font"
"data-office-font-size"
"data-office-color-hex"
"data-office-color-theme-name"
"data-word-style-id"
"data-word-space-after"
"data-word-space-before"
"data-word-indentation"
"data-word-alignment" (Center, Right, Left)
Attribute on br:
"data-word-break-type" (Page)
PowerPoint template types
Elements:
<p>Paragraph</p>
<span>Span</span>
<sup>superscript</sup>
<sub>subscript</sub>
<ul><li>list</li></ul>
<ol><li>list</li></ol>
<u>underline</u>
<i>italic</i>
<em>italic</em>
<b>bold</b>
<strong>bold</strong>
<br />
Attributes on span and p:
"data-office-font"
"data-office-font-size"
"data-office-color-hex"
"data-office-color-theme-name"
"data-powerpoint-alignment" (Center, Right, Left)
Dynamic Attributes
Some native HTML attributes can be populated with values from Fields — the replacement is done via placeholders in double curly braces:
<a href="{{url}}">Link</a>
Dynamic attributes such as href, src or alt are supported only in Outlook HTML templates (email and signature). There, the replacement happens before the HTML is sanitized.
In Word and PowerPoint templates, the HTML sanitizer otherwise only allows the class and data-* attributes; other attributes (including dynamically set ones) are removed. In Outlook, the cid: scheme is additionally allowed.
Dynamic attributes supported in Outlook HTML templates:
alt
aria-label
class
href
id
name
src
title
value
Outlook (new) — template types
This refers to the web-capable Outlook client (Outlook (new)). It uses HTML as the "description" for e-mails and signatures, so FormattedText data can be used directly here. In addition, all HTML elements and attributes permitted by Outlook can be used.
Outlook (new) ignores certain CSS properties such as white-space: pre-wrap, so line breaks and spaces are not rendered as in standard browsers. To achieve the desired layout, inserting <br> elements is necessary.
FormattedText as a Field
If a FormattedText is to be embedded into one (or more) template(s), this can be defined in a Field of the FormattedText type.
Paragraph behaviour — depending on the occurrence of paragraphs (<p>):
- If at least one of the elements is a paragraph, all non-paragraph elements are each placed in a separate paragraph.
- If none of the elements is a paragraph, all elements are concatenated directly without additional paragraph breaks.
This behaviour is intentional and applies to all FormattedText regardless of its origin or use.
A global translation of the FormattedText type can be output in Fields via the translations API:
$.translations.getFormattedText("FormattedTexts.EnclosuresTitle")
Existing Snippets of the FormattedText type can also be accessed via the snippets API:
$.snippets.getFormattedText("FormattedTexts.SimpleSnippet")
Optionally, an object of parameters can be passed. These replace the Handlebars placeholders ({{name}}) in the snippet's HTML:
$.snippets.getFormattedText("FormattedTexts.Greeting", { name: $("Forms.CustomerName") })
FormattedText as a Global Translation
A FormattedText can be saved as a global translation in the Global Translations. The advantage is that no Snippet has to be created; instead, the text can be created directly in its technical format, HTML.
FormattedText as a Snippet
A FormattedText can also be saved as a Snippet of the FormattedText type under the template Snippets. However, Snippets of this type are only used for template construction or templating and are therefore not used by end users.
FormattedText Snippets cannot store tables, images or other complex content. Snippets of the WordContent type are suitable for this purpose, however.
FormattedText Snippets are less flexible than global translations or the definition in the Fields, but there is an automatic converter: if you create a text in Word, you can save the Snippet as FormattedText via the Snippet sidebar.
Placeholders, Loops and Conditions
A FormattedText can contain placeholders that are filled with named parameters when it is retrieved. primedocs uses the HTML template engine Handlebars for this — hence the double curly braces.
The placeholders work the same way whether the FormattedText is defined as a global translation, as a snippet, or directly in a Field.
Inserting a value
<p>Hello {{name}}</p>
$.translations.getFormattedText("Texts.Greeting", { name: $("Forms.CustomerName") })
Every placeholder in the HTML must receive a matching parameter. If one is missing, generation aborts with a message stating that the parameter was not specified for the template.
Condition — {{#if}}
A block is only rendered when the parameter has a value:
{{#if content}}
<p data-word-style-id="Quote">{{content}}</p>
{{/if}}
primedocs treats an empty string and an empty FormattedText as «not set». If content is empty, the whole block is dropped — including the <p> element. Without the condition an empty paragraph would end up in the document.
data-word-style-id refers to a Word style; the example uses the built-in «Quote» style. The name of a custom style from the template is equally valid.
This is the usual way to build optional paragraphs: a field that may stay empty should not leave an empty paragraph behind.
Loop — {{#each}}
An array of objects can be turned into a list:
<ul>{{#each positions}}<li>{{this.Description}}</li>{{/each}}</ul>
The array elements must be objects; an array of plain values is rejected.
What is not allowed
- Triple curly braces (
{{{...}}}, «triple-stash») are rejected. HTML is already inserted through theFormattedTexttype; raw unescaped insertion is not intended. - The Handlebars helper
{{#attribute ...}}must not be written directly. For attributes, use the normal formhref="{{url}}"— primedocs converts it internally. Which attributes accept dynamic values, and in which template types, is described under Dynamic Attributes. data-*attributes do not accept dynamic values.data-word-style-id="{{styles}}"is rejected — the style must be fixed in the HTML.