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 — über den 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.

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.

Es gibt vier Platzhalter-Typen. Der Tag hat immer die Form primedocs.<Typ>=<Name> (Trennzeichen =); <Name> ist der Mapping-Schlüssel:

Tag	Verwendung	Zulässige Werte
primedocs.SnippetPlaceholder=<Name>	Text-artig (im Textfluss)	Text; Feldreferenzen ausser WordContent/FormattedText
primedocs.SnippetBlockPlaceholder=<Name>	Ganzer Block (eigener Absatz)	WordContent, FormattedText, InlineWordContent, Text
primedocs.SnippetInlinePlaceholder=<Name>	Inline (innerhalb eines Absatzes)	nur InlineWordContent
primedocs.SnippetTableRowsPlaceholder=<Name>	Wiederholte Tabellenzeilen	nur WordTableRows

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.