WordContent-Snippet

Ein WordContent-Snippet ist ein wiederverwendbarer Block aus nativem Word-Inhalt: Text mit Formatierung, Tabellen, Bilder, Inhaltssteuerelemente oder beliebige andere Elemente, die in einem Word-Dokument vorhanden sein können. Es wird als Teil einer Vorlage gespeichert und bei der Dokumentgenerierung in das Dokument eingefügt.

WordContent-Snippets sind für Layouter bestimmt. Sie werden in der Kategorie Design (Vorlage) gespeichert und sind für Endbenutzer nicht sichtbar.

Wann WordContent-Snippets verwenden?

Ein WordContent-Snippet verwenden, um:

• Einen komplexen formatierten Block (z.B. eine Tabelle, einen Adressblock oder eine rechtliche Klausel) in mehreren Vorlagen wiederzuverwenden.
• Unterschiedliche Inhaltsblöcke dynamisch je nach Benutzereingabe oder Profildaten einzufügen.
• Kopf- und Fusszeilen oder Abschnitte konsistent über mehrere Inhaltsvorlagen hinweg zu halten, die dasselbe Layout verwenden.

Für einfachen formatierten Text (fett, kursiv, Zeilenumbrüche) stattdessen ein FormattedText-Snippet verwenden, das leichtgewichtiger und HTML-basiert ist.

WordContent-Snippet erstellen

WordContent-Snippets werden über die Snippet-Seitenleiste (Aufgabenbereich) in Word erstellt und verwaltet, nicht über eine Registerkarte im Vorlageneditor.

1. In primedocs Desktop die Vorlage öffnen, in der das Snippet abgelegt werden soll.
2. Die Snippet-Seitenleiste öffnen.
3. Ein neues Snippet vom Typ Word Content anlegen.
4. Dem Snippet einen Namen geben und den Inhalt in Word bearbeiten.
5. Das Snippet speichern.

WordContent-Snippet in einer Vorlage verwenden

Ein WordContent-Snippet wird über die Dokumentfunktion Fields eingebunden: Ein Field vom Typ WordContent ruft das Snippet über die Snippets-API ab. Das Ergebnis wird dort eingefügt, wo das Field in der Vorlage platziert ist.

$.snippets.getWordContent("SnippetName")

So kann das Snippet auch bedingt anhand von Formulareingaben oder Profildaten ausgewählt werden:

const snippetName = $("Forms.Department") === "Legal" ? "LegalDisclaimer" : "StandardDisclaimer";
$.snippets.getWordContent(snippetName);

hinweis

primedocs.SnippetBlockPlaceholder=… und die übrigen Snippet-Platzhalter sind keine Vorlagen-seitige Referenz auf ein Snippet, sondern Platzhalter innerhalb eines Snippets. Sie werden beim Abruf über getWordContent(...) gefüllt (siehe unten).

Platzhalter im Snippet füllen

Enthält das Snippet Platzhalter, werden diese über ein Mapping-Objekt als zweites Argument befüllt. Der Schlüssel ist jeweils der Platzhaltername, der Wert der einzusetzende Inhalt (ein Text, eine Feldreferenz via $.getReference(...) oder ein anderer Snippet-/Field-Wert):

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

Für Profil-, Forms- und Data-Felder erzeugt $.createAutoMapping() das Mapping automatisch. Details zu den Platzhalter-Typen und zur Snippets-API: Snippets.

Bilder im Snippet

Ein WordContent-Snippet darf Bilder enthalten, die fest zum Inhalt gehören, etwa ein Logo im Briefkopf. Übernommen werden im Dokument eingebettete Bilder (DrawingML, SVG mit PNG-Ersatzbild sowie VML aus dem Kompatibilitätsmodus) mit allen Textumbrüchen und Positionierungen von Word, mit Zuschnitt, Drehung, Hyperlink und Bildformaten wie Rahmen, Schatten oder Spiegelung sowie mit der Markierung als dekorativ. Beim Einfügen landet das Bild im richtigen Teil des Dokuments, auch in Kopf- und Fusszeilen, in verschachtelten Snippets und in Tabellenzeilen.

Beim Speichern des Snippets gelten zwei Grenzen:

• Verknüpfte Bilder (in Word über Einfügen › Bilder › Verknüpfung mit Datei) werden abgewiesen. Die Meldung lautet «Verknüpfte Bilder werden in Textbausteinen nicht unterstützt. Fügen Sie das Bild so ein, dass es im Dokument gespeichert wird.».
• Grösse: Ein Snippet darf höchstens 8 MB gross sein, Bilder eingerechnet. Ein Limit pro Bild gibt es nicht. Bei Überschreitung erscheint «Der Textbaustein ist … MB gross. Das Limit beträgt 8 MB. Verwenden Sie weniger oder kleinere Bilder.».

Kann Word die aktuelle Auswahl nicht lesen, meldet das Add-In «Word konnte die Auswahl nicht lesen. Bitte versuchen Sie es erneut.». Die Auswahl dann erneut markieren und das Speichern wiederholen.

Bild-Platzhalter

Soll das Bild erst beim Einfügen bestimmt werden, etwa das Logo aus dem Profil, erhält das Snippet einen Bild-Platzhalter (primedocs.SnippetPicturePlaceholder=<Name>, Art Bild im Dialog Textbaustein-Platzhalter einfügen). Word legt dafür ein Bild-Inhaltssteuerelement mit einem Platzhalterbild an. Dieses Bild legt Position und Grösse des später eingesetzten Bildes fest. Ein Picture-Feld in der Auswahl wird beim Erstellen des Snippets automatisch zu einem Bild-Platzhalter, das aktuell eingesetzte Bild wird zum Platzhalterbild.

Im Mapping von getWordContent erhält ein Bild-Platzhalter ein Picture-Feld. Wie bei den anderen Platzhalter-Typen entscheidet die Übergabe, ob das Bild an das Feld gebunden bleibt (siehe Platzhalter für Snippets):

// Mit Feldreferenz: Das Inhaltssteuerelement bleibt an das Feld gebunden,
// ein Profilwechsel im offenen Dokument tauscht das Bild aus.
$.snippets.getWordContent("Letterhead", { Logo: $.getReference("Profile.Org.Logo") })

// Mit dem Wert des Felds: Das Bild wird eingesetzt, das Inhaltssteuerelement entfernt.
$.snippets.getWordContent("Letterhead", { Logo: $("Profile.Org.Logo") })

Die Grösse legt das Picture-Feld mit WidthInCm und HeightInCm fest (siehe Bildgrösse festlegen). Das folgende Feld setzt das Logo aus dem Profil auf 4 cm Breite und wird mit { Logo: $.getReference("Logo") } in den Platzhalter gegeben:

<Picture Name="Logo">
  <Code><![CDATA[
    function main() {
      return {
        Source: $("Profile.Org.Logo"),
        WidthInCm: 4
      };
    }
  ]]></Code>
</Picture>

Im Bild-Platzhalter wirken die Angaben so:

Angabe	Wirkung
keine	Das Bild erhält die Grösse des Platzhalterbilds.
eine	Die andere Seite ergibt sich aus dem Seitenverhältnis des eingesetzten Bildes.
beide	Das Bild erhält exakt diese Masse.

Eine ungültige Grösse (etwa WidthInCm: -1) wird ignoriert und beim Testen der Vorlage als Warnung gemeldet.

Bild ohne Picture-Feld

Der Platzhalter nimmt auch eine Bildadresse als String ("base64:…") oder ein Objekt mit Source, WidthInCm und HeightInCm, wie es der Code eines Picture-Felds zurückgibt. Das Bild wird dann ohne Bindung eingesetzt.

Ist das Bild leer, etwa bei einem Picture-Feld ohne Bild, setzt primedocs einen transparenten Pixel ein: ohne Grössenangabe 1 px gross, sodass der Text nachrückt, mit Grössenangaben in dieser Grösse, sodass der Platz frei bleibt. Bei einer Feldreferenz bleibt die Bindung bestehen. Kommt später ein Bild, etwa nach einem Profilwechsel, übernimmt das Add-In die bisherige Grösse. Das Picture-Feld sollte deshalb WidthInCm oder HeightInCm setzen.

Eine Feldreferenz auf ein Picture-Feld in einem Text-Platzhalter und ein Bild in einem anderen Platzhalter-Typ brechen die Generierung mit einem Fehler ab, der den erwarteten Platzhalter-Typ nennt. $.createAutoMapping() ordnet einem Bild-Platzhalter, der aus einem Picture-Feld entstanden ist, eine Feldreferenz zu.

Bilder lassen sich auch ohne Snippet in ein WordContent setzen, mit $.wordContent.fromPicture($("Logo")) oder $.wordContent.getBuilder().append($("Logo")), siehe wordContent API.

Querverweise und Inhaltsverzeichnisse

Ein WordContent-Snippet darf REF- und PAGEREF-Felder mit dem Hyperlink-Schalter \h enthalten, wie Word sie beim Einfügen eines Querverweises setzt. Ein Inhaltsverzeichnis (TOC-Feld) ist nur ohne \h zulässig. Enthält das TOC-Feld selbst den Schalter \h, wird der Inhalt abgewiesen. Die PAGEREF-Felder mit \h, die Word in die Einträge jedes Inhaltsverzeichnisses schreibt, stören dagegen nicht.

Quick-Check-Felder im Snippet

Ein WordContent-Snippet darf Inhaltssteuerelemente mit dem Tag primedocs.Tracked enthalten. Damit lässt sich ein Quick-Check-Block einmal aufbauen und in mehreren Vorlagen wiederverwenden. Das Tag muss exakt primedocs.Tracked lauten. Mit einem Zusatz wie =Wert lässt sich das Snippet nicht speichern. Zulässig sind alle Arten von Inhaltssteuerelementen, auch Datum und Kontrollkästchen. Ein Tracked-Inhaltssteuerelement darf nicht gesperrt sein, sonst liesse es sich nicht ausfüllen.

Der Platzhaltertext eines Inhaltssteuerelements bleibt im Snippet erhalten und wird beim Einfügen in das erzeugte Dokument übernommen. Solange ein Feld seinen Platzhaltertext zeigt, wertet der Quick Check es als nicht ausgefüllt.

Ausfüllhinweise

Im Snippet ist nur primedocs.HintText=[TEXT] zulässig. primedocs.HintField=[FieldId] ist in Snippets nicht erlaubt, sodass mehrsprachige Hinweistexte über ein Field dort nicht funktionieren.

Kommentare im Snippet

Word-Kommentare, die im Inhalt des Snippets verankert sind, werden beim Speichern des Snippets übernommen, samt Antworten und dem Status «erledigt». Bei der Dokumentgenerierung erscheinen sie im erzeugten Dokument an derselben Stelle.

Persönliche Angaben entfernt primedocs beim Speichern: Als Autor steht in jedem Kommentar der neutrale Wert «Author», Initialen und Datum fehlen. Erwähnte Personen (@-Erwähnungen) bleiben als reiner Text ohne E-Mail-Verknüpfung stehen. Der Kommentartext selbst und gewöhnliche Web-Links bleiben erhalten.

Nicht in Kopf- und Fusszeilen

Snippets mit Kommentaren lassen sich nicht in Kopf- oder Fusszeilen und nicht in Fuss- oder Endnoten einfügen. Die Generierung schlägt dort fehl, weil Word an diesen Stellen keine Kommentare zulässt.

Fremde Inhaltssteuerelemente

Wird Word-Inhalt eingefügt, der Inhaltssteuerelemente aus einem anderen Dokument enthält (z.B. fremde primedocs.Field-Tags aus einem Teildokument), blockiert das die Generierung nicht: Beim Bereinigen werden nicht von primedocs stammende Inhaltssteuerelemente entfernt. Fremde Tabellenzeilen-Inhaltssteuerelemente bleiben dabei erhalten, damit Tabellenstruktur und gesperrte Inhalte unverändert bestehen.

Berechtigungen

WordContent-Snippets werden in der Kategorie Design gespeichert. Nur Template Admins und Sys Admins können sie erstellen oder bearbeiten. Weitere Details unter Snippet-Berechtigungen.