Snippets

Snippets (früher: Textbausteine) sind wiederverwendbare Inhaltsbausteine, die in Vorlagen eingefügt werden können. Sie ermöglichen es, häufig verwendete Inhalte an einem Ort zu pflegen und in mehreren Vorlagen zu referenzieren.

Kategorien

Snippets sind in drei Kategorien unterteilt, die sich in Sichtbarkeit und Verwaltungszuständigkeit unterscheiden:

• Design (Vorlagen-Snippets): in Vorlagen eingebettet und für Layouter bestimmt. Werden bei der Dokumentgenerierung von der Template-Engine verwendet und sind für Endbenutzer nicht sichtbar. Die auf dieser Seite beschriebenen Typen WordContent und FormattedText gehören in diese Kategorie.
• Shared (öffentliche Snippets): organisationsweit oder abteilungsübergreifend geteilt, für Endbenutzer sichtbar und einfügbar.
• Private (persönliche Snippets): von einzelnen Benutzern für den persönlichen Gebrauch erstellt.

Endbenutzer-Snippets (die klassischen, vom Anwender einfügbaren Textbausteine) können in allen drei Kategorien liegen. Welche Rolle welche Kategorie sehen und bearbeiten darf, ist unter Snippet-Berechtigungen beschrieben. Wie ein Snippet beim manuellen Einfügen im Word-Add-In je nach Cursorposition platziert wird, beschreibt das Einfügeverhalten.

Arten von Snippets (für Layouter)

Für die Vorlagenerstellung unterstützt primedocs zwei Haupttypen von Snippets:

• WordContent: Wiederverwendbare Word-Inhaltsbausteine, die Text, Tabellen, Bilder und andere komplexe Word-Inhalte enthalten können. Werden verwendet, wenn ganze Abschnitte von Word-Inhalt dynamisch in ein Dokument eingefügt werden müssen.
• FormattedText: Leichtgewichtige HTML-basierte Snippets mit Formatierung. Werden für formatierte Textpassagen verwendet, die eine konsistente Formatierung in allen Vorlagen benötigen, z.B. Kopf-/Fusszeileninhalte.

Dynamische Textbausteine (DynamicSnippet)

Neben den oben beschriebenen, fest angelegten Snippets können Textbausteine auch dynamisch bei der Dokumentgenerierung erzeugt werden. Dazu dient der Field-Typ DynamicSnippet. Solche Bausteine hängen vom Datenkontext des Dokuments ab, erscheinen im Snippet-Bereich in der Gruppe «Dynamische Textbausteine» und lassen sich optional per AutoText einfügen. Sie werden nur in Word unterstützt.

Im Word-Add-In bietet das Kontextmenü eines dynamischen Textbausteins «Einfügen» und «Eigenschaften». «Eigenschaften» öffnet eine schreibgeschützte Ansicht der Konfigurationswerte. Bearbeiten lassen sich die Werte dort nicht, und das Feld «Sprache» fehlt in dieser Ansicht.

Vorteile

• Konsistenz: Pflegen Sie konsistente Inhalte in allen Vorlagen von einer einzigen Quelle aus.
• Effizienz: Aktualisieren Sie Inhalte an einem Ort und haben Sie diese in allen Vorlagen widergespiegelt, die dieses Snippet verwenden.
• Dynamische Inhalte: Snippets können über JavaScript dynamisiert werden, sodass sie sich an Benutzereingaben oder Profildaten anpassen.

Snippets in Vorlagen verwenden

Snippets werden in der Dokumentfunktion Felder (Fields) über die Snippets-API abgerufen. Es gibt drei Methoden, je eine pro Snippet-Typ:

Methode	Rückgabe	Snippet-Typ
$.snippets.getText("Key")	Text (String)	Text
$.snippets.getFormattedText("Key", { name: wert })	FormattedText (HTML)	FormattedText
$.snippets.getWordContent("Key", { platzhalter: wert })	WordContent	WordContent

• getText liefert reinen Text und nimmt keine Parameter.
• getFormattedText ersetzt im HTML des Snippets Handlebars-Platzhalter ({{name}}) durch die übergebenen Werte.
• getWordContent füllt die im Snippet enthaltenen Platzhalter über ein Mapping-Objekt (siehe unten).

Platzhalter im WordContent-Snippet

Ein WordContent-Snippet enthält Platzhalter (Word-Inhaltssteuerelemente mit einem primedocs.-Tag). Beim Abruf über getWordContent(key, mapping) wird jeder Platzhalter über das Mapping befüllt: Der Schlüssel ist der Platzhaltername, der Wert der einzusetzende Inhalt.

$.snippets.getWordContent("SnippetName", {
  "Profile.User.LastName": $.getReference("Profile.User.LastName"),
  "Anrede": "Sehr geehrte Damen und Herren"
});

Als Wert sind zulässig: ein String, eine Feldreferenz über $.getReference("FeldId") (späte Bindung, wird erst bei der Generierung aufgelöst) sowie WordContent-, InlineWordContent-, FormattedText- und WordTableRows-Werte. Ein Platzhalter ohne Zuordnung führt zu einem Fehler.

Umgekehrt bleibt ein Mapping-Eintrag, dessen Schlüssel im Snippet keinen Platzhalter trifft, wirkungslos und wird als Warnung gemeldet, die die ignorierten Schlüssel benennt, sodass Tippfehler auffallen. Schlüssel in Feldpfad-Form (Profile.…, Forms.…, Data.…, Document.…) lösen die Warnung nicht aus, weil das automatisch erzeugte Mapping bewusst mehr Feldpfade liefert, als das Snippet enthält.

Es gibt vier Platzhalter-Typen. Der Tag hat immer die Form primedocs.<Typ>=<Name> (Trennzeichen =), wobei <Name> der Mapping-Schlüssel ist. Angelegt werden alle vier im Word-Add-In über eine Schaltfläche: Textbaustein-Platzhalter einfügen in der Ribbon-Gruppe Vorlagenbearbeitung. Die Spalte «Auswahl im Dialog» nennt den Eintrag, der den jeweiligen Typ erzeugt (siehe Ribbon-Gruppen für die Vorlagenbearbeitung):

Tag	Auswahl im Dialog	Verwendung	Zulässige Werte
primedocs.SnippetPlaceholder=<Name>	Textbaustein – im laufenden Text	Text-artig (im Textfluss)	Text, Feldreferenzen ausser WordContent/FormattedText
primedocs.SnippetBlockPlaceholder=<Name>	Block – ein oder mehrere ganze Absätze	Ganzer Block (eigener Absatz)	WordContent, FormattedText, InlineWordContent, Text
primedocs.SnippetInlinePlaceholder=<Name>	Inline – innerhalb eines Satzes, ohne den Absatz zu brechen	Inline (innerhalb eines Absatzes)	nur InlineWordContent
primedocs.SnippetTableRowsPlaceholder=<Name>	Tabellenzeilen – ersetzt ganze Zeilen einer Tabelle	Wiederholte Tabellenzeilen	nur WordTableRows

Struktur der Platzhalter

Der Typ legt nicht nur fest, welche Werte zulässig sind, sondern auch, wo der Platzhalter im Snippet stehen darf. Geprüft wird das bei der Dokumentgenerierung. Ein falsch platzierter Platzhalter bricht sie ab.

Block. Ein Block-Platzhalter muss einen ganzen Absatz umfassen. Zulässig ist ein Inhaltssteuerelement auf Absatzebene oder um eine ganze Tabellenzelle. Ein Inhaltssteuerelement innerhalb eines Absatzes wird nur akzeptiert, wenn es allein im Absatz steht, also ohne weiteren Text daneben. Beim Befüllen wird es dann automatisch auf Absatzebene gehoben.

Block-Platzhalter nicht mitten im Satz einfügen

Das Word-Add-In legt für Block ein Text-Inhaltssteuerelement an der aktuellen Auswahl an. Wird die Schaltfläche mitten in einem Absatz benutzt, entsteht ein Platzhalter, der die Prüfung nicht besteht. Für einen Block-Platzhalter zuerst einen leeren Absatz anlegen und den Cursor dorthin setzen.

Tabellenzeilen. Ein SnippetTableRowsPlaceholder muss eine ganze Tabellenzeile umschliessen. Als einziger der vier Typen erhält er dafür ein Rich-Text-Inhaltssteuerelement. Umfasst die Auswahl genau eine vollständige Zeile, ist die Art im Dialog bereits vorbelegt.

Textbaustein und Inline unterliegen keiner Struktur-Prüfung, denn sie stehen im Textfluss.

Bei falscher Platzierung bricht die Generierung mit einer dieser Meldungen ab:

Meldung	Ursache
Snippet block placeholder '<Name>' must be alone in a paragraph.	Block-Platzhalter steht in einem Absatz mit weiterem Inhalt
Snippet block placeholder '<Name>' must be a block-level content control, but is of type '…'.	Block-Platzhalter liegt auf einer Ebene, die keinen Absatz aufnehmen kann
Snippet TableRows placeholder '<Name>' must be around a table row.	TableRows-Platzhalter umschliesst keine Tabellenzeile

Ein Wert, dessen Typ die Tabelle oben für diesen Platzhalter nicht vorsieht, bricht die Generierung ebenfalls ab, etwa mit WordContent is only supported for Snippet Block Placeholders.

Felder in Snippets

Ein Snippet enthält technisch nur Platzhalter, nie Felder. Die eigentlichen Werte werden erst beim Einfügen zugeordnet. Beim Erstellen eines WordContent- oder FormattedText-Snippets im Word-Add-In dürfen im markierten Text trotzdem direkt Felder stehen: primedocs wandelt sie beim Anlegen automatisch in den passenden Platzhalter um. Das frühere manuelle Vorgehen (Feld löschen, Platzhalter von Hand mit korrektem Typ anlegen) entfällt.

Umgewandelt werden Felder unterhalb der Wurzeln Profile, Forms und Data. Je nach Feldtyp entsteht ein anderer Platzhalter-Typ:

Feldtyp	Platzhalter
Text, Ja/Nein, Datum	SnippetPlaceholder
InlineWordContent	SnippetInlinePlaceholder
WordContent, FormattedText	SnippetBlockPlaceholder

Der Platzhaltername entspricht dabei dem vollständigen Feldpfad in Punktnotation (z.B. Profile.User.FirstName).

hinweis

Die automatische Umwandlung erfolgt im Word-Add-In des Desktop Clients. Eigene Fields (Custom Fields), WordTableRows, Bilder und Hinweisfelder werden nicht automatisch umgewandelt.

Mapping automatisch erzeugen: $.createAutoMapping()

Beim Einfügen eines WordContent-Snippets muss jeder enthaltene Platzhalter einem Wert zugeordnet werden. Statt jedes Mapping einzeln zu schreiben, erzeugt $.createAutoMapping() die vollständige Zuordnung als Einzeiler:

$.snippets.getWordContent("MeinSnippet", $.createAutoMapping())

Die Funktion liefert ein Objekt, dessen Schlüssel die bekannten Feldreferenzen in Punktnotation sind (z.B. Profile.User.FirstName). Berücksichtigt werden ausschliesslich Felder unterhalb von Profile, Forms und Data.

Einzelne Einträge lassen sich per Spread-Syntax ergänzen oder überschreiben, etwa für ein Custom Field, das nicht automatisch erfasst wird:

$.snippets.getWordContent("MeinSnippet", {
    ...$.createAutoMapping(),
    MeinCustomFeld: $.getReference("EinAnderesField")
})

hinweis

Custom Fields sowie verschachtelte Block-Platzhalter (eingebettete Snippets) sind von $.createAutoMapping() nicht abgedeckt und müssen weiterhin von Hand zugeordnet werden.