Best Practices und Anwendungsfälle

Dieses Kapitel sammelt vollständige Anwendungsfälle für typische Aufgaben sowie Tipps, Konventionen und bekannte Hürden bei der Vorlagenerstellung. Die Referenzseiten beschreiben jede Dokumentfunktion einzeln. Die Anwendungsfälle zeigen, wie die Bausteine zusammenspielen.

Anwendungsfälle

Jedes Beispiel führt von der Datenquelle bis zur Stelle im Dokument und enthält alle Konfigurationen vollständig und kopierfähig.

Anwendungsfall	Datenquelle	Bausteine
Brief mit Empfänger aus einer Adressdatenquelle	Benutzer, Adressdatenquelle	Forms (Object, DataProvider), Fields, Feld binden
Geschäftsnummer aus der Fachanwendung in der Kopfzeile	Drittsystem über Connect	Data, Fields, Platzhalterzuordnung, Platzhalterdefinition, Globale Übersetzungen
Teilnehmerliste als Tabelle	Benutzer	Forms (ObjectCollection), Fields (WordTableRows), Feld binden
Globale Konfiguration teilen und pro Vorlage übersteuern	Benutzer	Globale Konfigurationen, Forms (GlobalElements), Fields (GlobalFields, Modifications)

Wie Vorlagen für Microsoft 365 Copilot zu gestalten sind, beschreibt die Seite Microsoft 365 Copilot.

Aufbau eines Beispiels

Jedes Beispiel folgt demselben Aufbau: Ausgangslage und Ergebnis, die beteiligten Bausteine mit Link zur Referenz, der Datenfluss, die Konfiguration Schritt für Schritt mit dem Grund für jeden nicht offensichtlichen Schritt, das Testen ohne Produktivsystem, Varianten und Stolpersteine.

Die Beispiele verwenden neutrale Bezeichnungen: Systeme nach ihrer Rolle («Fachanwendung», «Adressdatenquelle»), Ids auf Englisch, Beschriftungen direkt im Label. So laufen die Konfigurationen ohne Vorarbeit und lassen sich in eine eigene Datasource übernehmen. Für mehrsprachige Vorlagen translate-Label mit globalen Übersetzungen verwenden. Nur das Beispiel mit der Geschäftsnummer setzt eine solche Übersetzung voraus, weil seine Beschriftung der Dokumentsprache folgen soll.

Vorlagenhierarchie

• Für Word-Vorlagen immer die dreistufige Hierarchie (Style, Layout, Inhalt) verwenden. Das Überspringen von Ebenen führt zu Mehraufwand bei Corporate-Identity-Änderungen.
• Alle «kleinsten gemeinsamen Nenner»-Dokumentattribute (Logos, Kopf- und Fusszeilen, Seitenränder) in der Layoutvorlage platzieren, nicht in einzelnen Inhaltsvorlagen.
• Im Vorlageneditor immer das Feld Basierend auf setzen, um eine Inhaltsvorlage mit einer Layoutvorlage und eine Layoutvorlage mit einer Stylevorlage zu verknüpfen.

Versionierung

• Bei wesentlichen Vorlagenänderungen immer eine neue Version erstellen, statt die veröffentlichte Version direkt zu bearbeiten.
• Änderungen mit der Funktion «Dokument testen» prüfen, bevor sie veröffentlicht werden.
• Stabile Testversionen als «Entwurf» markieren, bevor sie als «Veröffentlicht» gekennzeichnet werden.

Berechtigungen

• Berechtigungen durchdacht setzen: Standard ist «Authentifizierte Benutzer», was allen Benutzern erlaubt, die Vorlage zu sehen und zu ändern. Bei Bedarf einschränken.
• Organisationseinheiten-Berechtigungen verwenden, um Vorlagen auf bestimmte Abteilungen zu beschränken.

Globale Konfigurationen und Übersetzungen

• Globale Konfigurationen für alle XML-Konfigurationen verwenden, die in mehreren Vorlagen wiederverwendet werden. Wie globale Einträge zusammenspielen und wie eine einzelne Vorlage davon abweicht, zeigt der Anwendungsfall Globale Konfiguration teilen und pro Vorlage übersteuern.
• Globale Übersetzungen für alle benutzersichtbaren Texte verwenden, die übersetzt werden müssen.
• Typisierte globale Einträge gegenüber untypisierten (classic) Einträgen bevorzugen, weil sie besser validiert werden und leichter auffindbar sind.

Tags

• In der Organisation eine einheitliche Tagging-Konvention etablieren.
• Tags verwenden, um zusammengehörige Vorlagen für einfaches Filtern und für primedocs Connect-Integrationen zu gruppieren.

Tipps & Tricks

• Shortcuts nutzen: z. B. das Formatvorlagen-Panel mit Strg + Alt + Umschalt + S öffnen.
• Vorlagen einfach halten: so einfach wie möglich bauen. Einfache Vorlagen sind schneller erstellt, leichter zu pflegen und robuster.
• Kommentare im Code: Code in Fields mit Kommentaren dokumentieren, damit er später nachvollziehbar bleibt.
• Möglichst Profilfelder verwenden: für Absender- und Organisationsangaben auf Profilfelder zurückgreifen, statt Werte fest in der Vorlage zu hinterlegen.
• Layouts vereinheitlichen: möglichst wenige, gemeinsam genutzte Layout-Vorlagen verwenden, statt für jede Inhaltsvorlage ein eigenes Layout zu pflegen.
• Snippets nutzen: wiederkehrende Inhalte in Snippets auslagern, statt sie in jeder Vorlage zu duplizieren.
• Tabellen einfach halten: bei selbst definierten Tabellenformatvorlagen auf einfache Strukturen setzen.

Gebundene Bilder in Kopfzeilen-Tabellen

Für gebundene Bilder in Kopfzeilen-Tabellen «Mit Text in Zeile» verwenden. Für freie Platzierung das Bild inline in ein Textfeld setzen und das Textfeld positionieren (siehe Layout).

Troubleshooting

Typische Fehlerquellen beim Layouten und ihre Ursachen:

Symptom	Mögliche Ursache	Lösung
Platzhalter wird nicht ersetzt	Feldname stimmt nicht mit der Platzhalterzuordnung überein	Feldnamen und Zuordnung prüfen (Gross-/Kleinschreibung, exakter Name)
Formatvorlage sieht anders aus als erwartet	Style-Verknüpfung fehlt oder wurde lokal überschrieben	Verknüpfung Basierend auf zur Style-Vorlage prüfen und lokale Formatierung zurücksetzen
Dropdown-Inhaltssteuerelement ist leer	Dropdown-/Schnellbaustein-Inhaltssteuerelemente sind an die jeweilige Vorlage gebunden	In Snippets keine Dropdown-/Schnellbaustein-Inhaltssteuerelemente verwenden (siehe Umsetzungsvarianten)

vorsicht

Änderungen in der Style-Vorlage wirken sich auf alle darauf aufbauenden Inhaltsvorlagen aus. Hier mit besonderer Vorsicht vorgehen und die Auswirkungen testen, bevor eine geänderte Style-Vorlage freigegeben wird.

hinweis

Die Tipps auf dieser Seite konzentrieren sich auf moderne primedocs-Vorlagen (Style/Layout/Inhalt).

Datentypen im Überblick

Woher ein Typ kommt, was er im Code liefert und wie er ins Word-Dokument gelangt. Herkunft: Forms, Data, Fields, Profil, Snippets, Globale Übersetzungen. Einfügen: Feld binden, Platzhalter im Layout.

Typ	Herkunft	Wert in JavaScript	Einfügen in Word
Text	Forms, Data, Fields, Profil	String	Nur-Text-Inhaltssteuerelement («Feld binden») oder Text-Platzhalter im Layout
Choice	Forms	gewählter Options-Value als String, Beschriftung über $.getChoiceLabel(…)	über ein Text-Field
Date	Forms, Fields	Datumsobjekt (.Value für $.formatDate(…), $.getDateAsText(…) für den formatierten Text)	Datums-Inhaltssteuerelement oder Text-Platzhalter im Layout
YesNo	Forms, Fields	Boolean	nicht direkt (steuert Logik in Fields, in PowerPoint die Sichtbarkeit über Tags)
FormattedText	Data, Fields, Globale Übersetzungen, Snippets	FormattedText	RichText-Inhaltssteuerelement
WordContent	Data, Fields, Snippets	WordContent	RichText-Inhaltssteuerelement, eigene Absätze
InlineWordContent	Fields	InlineWordContent, genau ein Absatz	RichText-Inhaltssteuerelement innerhalb eines Absatzes
WordTableRows	Fields	WordTableRows	die Inhaltszeile einer Tabelle, kopiert für jeden Eintrag
Picture	Fields, Profil (z. B. Profile.Org.Logo)	Bild	Bild-Inhaltssteuerelement oder Picture-Platzhalter im Layout
Object	Forms, Data, Fields	JavaScript-Objekt mit den Schema-Ids als Eigenschaften oder null, wenn kein Eintrag angelegt wurde	nicht direkt, sondern über ein Field ausgeben
ObjectCollection	Forms, Data, Fields	Array solcher Objekte (leer: [])	nicht direkt, sondern über ein Field ausgeben, z. B. WordTableRows

Details: Rückgabewert von Field-Typen, Objects und ObjectCollections im Code, Field-Typ pro Office-Anwendung.