FormattedText

FormattedText ist ein Datencontainer, welcher Text mit Formatierungsoptionen (u.A. Fett, Kursiv, Unterstrichen, Umbrüche oder auch Word-spezifische Formatierungen) enthalten kann.

Dabei handelt es sich bei FormattedText, egal in welchem Kontext, technisch um HTML:

<p>Erstellt mit: <b>primedocs</b>!</p>

Erstellt mit: primedocs!

FormattedText bietet sich an, um einfache Formatierungsoptionen abzubilden, welche sowohl in Word-, PowerPoint- oder Outlook-Vorlagen genutzt werden können.

In FormattedText können auch produktspezifische Formatierungsoptionen hinterlegt werden, sodass z. B. ein Absatz in Word mit einem Style ausgestattet sein kann.

---

Syntax

FormattedText tritt in primedocs auf als...

• Field-Typ, also kann als Code generiert werden, wobei FormattedText als Snippet oder globale Übersetzung geholt werden kann.
• Typ einer globalen Übersetzung
• Snippet-Typ.

HTML-Elemente

Die folgenden Listen zeigen alle möglichen HTML-Elemente und deren Attribute, die in den Vorlagen verwendet werden können.

Word-Vorlagentypen

Elemente:

<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 />

Attribute auf span und 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)

Attribut auf br:

"data-word-break-type" (Page)

PowerPoint-Vorlagentypen

Elemente:

<p>Paragraph</p>
<span>Span</span>
<sup>hochgestellt</sup>
<sub>tiefgestellt</sub>
<ul><li>Liste</li></ul>
<ol><li>Liste</li></ol>
<u>unterstrichen</u>
<i>kursiv</i>
<em>kursiv</em>
<b>fett</b>
<strong>fett</strong>
<br />

Attribute auf span und p:

"data-office-font"
"data-office-font-size"
"data-office-color-hex"
"data-office-color-theme-name"
"data-powerpoint-alignment" (Center, Right, Left)

Dynamische Attribute

Einige native HTML-Attribute können mit Werten aus Fields befüllt werden — die Ersetzung erfolgt über Platzhalter in doppelten geschweiften Klammern:

<a href="{{url}}">Link</a>

Nur Outlook-HTML-Vorlagen

Dynamische Attribute wie href, src oder alt werden ausschliesslich in Outlook-HTML-Vorlagen (E-Mail und Signatur) unterstützt. Dort erfolgt die Ersetzung vor der Bereinigung (Sanitization) des HTML.

In Word- und PowerPoint-Vorlagen lässt der HTML-Sanitizer sonst nur die Attribute class und data-* zu; andere Attribute (auch dynamisch gesetzte) werden entfernt. In Outlook ist zusätzlich das cid:-Schema erlaubt.

In Outlook-HTML-Vorlagen unterstützte dynamische Attribute:

alt
aria-label
class
href
id
name
src
title
value

Outlook (new) — Vorlagentypen

Gemeint ist der webfähige Outlook-Client (Outlook (new)). Dieser nutzt HTML als «Beschreibung» für E-Mails und Signaturen, daher können FormattedText-Daten hier direkt genutzt werden. Zusätzlich können alle von Outlook erlaubten HTML-Elemente und -Attribute verwendet werden.

hinweis

Outlook (new) ignoriert gewisse CSS-Eigenschaften wie white-space: pre-wrap, wodurch Zeilenumbrüche und Leerzeichen nicht wie in Standard-Browsern dargestellt werden. Um das gewünschte Layout zu erreichen, ist das Einfügen von <br>-Elementen notwendig.

---

FormattedText als Field

Soll ein FormattedText in eine (oder mehrere) Vorlage(n) eingebunden werden, kann dies in einem Field vom Typ FormattedText definiert werden.

Verhalten von Paragraphen — abhängig vom Vorkommen von Paragraphen (<p>):

• Ist mindestens eines der Elemente ein Paragraph, werden alle nicht-Paragraph-Elemente jeweils in einen separaten Paragraphen gesetzt.
• Ist keines der Elemente ein Paragraph, werden alle Elemente ohne zusätzliche Absatzumbrüche direkt aneinandergereiht.

Dieses Verhalten ist beabsichtigt und gilt für sämtlichen FormattedText, unabhängig von dessen Herkunft oder Verwendung.

Eine globale Übersetzung vom Typ FormattedText kann in Fields über die translations-API ausgegeben werden:

$.translations.getFormattedText("FormattedTexts.EnclosuresTitle")

Bestehende Snippets vom Typ FormattedText können auch über die snippets-API abgerufen werden:

$.snippets.getFormattedText("FormattedTexts.SimpleSnippet")

Optional lässt sich ein Objekt mit Parametern übergeben. Diese ersetzen im HTML des Snippets die Handlebars-Platzhalter ({{name}}):

$.snippets.getFormattedText("FormattedTexts.Greeting", { name: $("Forms.CustomerName") })

---

FormattedText als globale Übersetzung

Ein FormattedText kann als globale Übersetzung in den Globalen Übersetzungen abgespeichert werden. Der Vorteil ist, dass kein Snippet erstellt werden muss, sondern der Text direkt in seinem technischen Format HTML erstellt werden kann.

---

FormattedText als Snippet

Ein FormattedText kann auch als Snippet vom Typ FormattedText unter den Vorlagen-Snippets abgespeichert werden. Snippets dieses Typs werden jedoch nur für die Vorlagenkonstruktion bzw. das Templating verwendet und werden daher nicht von Endbenutzern genutzt.

FormattedText-Snippets können keine Tabellen, Bilder oder andere komplexe Inhalte speichern. Dafür eignen sich jedoch Snippets vom Typ WordContent.

tipp

FormattedText-Snippets sind weniger flexibel als globale Übersetzungen oder die Definition in den Fields, aber es gibt einen automatischen Konverter: Einen Text in Word erstellen und das Snippet über die Snippet-Seitenleiste als FormattedText speichern.

---

Platzhalter, Schleifen und Bedingungen

Ein FormattedText kann Platzhalter enthalten, die beim Abruf mit benannten Parametern befüllt werden. Dafür nutzt primedocs die HTML-Template-Engine Handlebars — daher die doppelten geschweiften Klammern.

Die Platzhalter funktionieren gleich, egal ob der FormattedText als globale Übersetzung, als Snippet oder direkt in einem Field definiert ist.

Wert einsetzen

<p>Guten Tag {{name}}</p>

$.translations.getFormattedText("Texts.Greeting", { name: $("Forms.CustomerName") })

Jeder Platzhalter im HTML muss einen passenden Parameter erhalten. Fehlt er, bricht die Generierung mit der Meldung ab, dass der Parameter für das Template nicht angegeben wurde.

Bedingung — {{#if}}

Ein Block wird nur ausgegeben, wenn der Parameter einen Wert hat:

{{#if content}}
<p data-word-style-id="Quote">{{content}}</p>
{{/if}}

primedocs behandelt einen leeren String und einen leeren FormattedText wie «nicht gesetzt». Ist content leer, entfällt der ganze Block — inklusive des <p>-Elements. Ohne die Bedingung entstünde ein leerer Absatz im Dokument.

data-word-style-id verweist dabei auf eine Word-Formatvorlage; im Beispiel auf die eingebaute Vorlage «Quote». Ebenso zulässig ist der Name einer eigenen Formatvorlage aus der Vorlage.

Das ist der übliche Weg, um optionale Absätze zu bauen: Ein Feld, das leer bleiben darf, soll keinen leeren Absatz hinterlassen.

Schleife — {{#each}}

Über ein Array von Objekten lässt sich eine Liste erzeugen:

<ul>{{#each positions}}<li>{{this.Bezeichnung}}</li>{{/each}}</ul>

Die Array-Elemente müssen Objekte sein; ein Array aus einfachen Werten wird abgewiesen.

Was nicht erlaubt ist

• Dreifache geschweifte Klammern ({{{...}}}, «triple-stash») werden abgewiesen. HTML wird bereits über den FormattedText-Typ eingesetzt, ein unmaskiertes Roh-Einfügen ist nicht vorgesehen.
• Der Handlebars-Helper {{#attribute ...}} darf nicht direkt geschrieben werden. Für Attribute gilt die normale Schreibweise href="{{url}}" — primedocs setzt das intern selbst um. Welche Attribute dynamisch befüllbar sind und in welchen Vorlagentypen, steht unter Dynamische Attribute.
• data-*-Attribute nehmen keine dynamischen Werte an. data-word-style-id="{{styles}}" wird abgewiesen — der Stil muss fest im HTML stehen.