Best Practices

This section contains a collection of tips and tricks, conventions and known obstacles when using primedocs for template creation.

Template Hierarchy

• Always use the three-level hierarchy (Style, Layout, Content) for Word templates. Skipping levels leads to additional effort when making corporate identity changes.
• Place all "lowest common denominator" document attributes (logos, headers and footers, margins) in the Layout template, not in individual Content templates.
• Always set the Based on field in the template editor to link a Content template to a Layout template, and a Layout template to a Style template.

Version Control

• For significant template changes, always create a new version rather than editing the published version directly.
• Test changes using the "Test Document" function before publishing them.
• Mark stable test versions as "Draft" before marking them as "Published".

Permissions

• Set permissions thoughtfully: the default is "Authenticated users", which allows all users to see and change the template. Restrict as needed.
• Use organizational unit permissions to restrict templates to specific departments.

Global Configurations and Translations

• Use Global Configurations for any XML configuration that is reused across multiple templates.
• Use Global Translations for all user-visible text that needs to be translated.
• Prefer typed global entries over untyped (classic) entries for better validation and discoverability.

Tags

• Establish a consistent tagging convention across your organization.
• Use tags to group related templates for easy filtering and for primedocs Connect integrations.

Tips & Tricks

• Use shortcuts — for example, open the styles panel with Ctrl + Alt + Shift + S.
• Keep templates simple — build as simply as possible. Simple templates are faster to create, easier to maintain and more robust.
• Comments in the code — document code in Fields with comments so that it remains comprehensible later on.
• Use profile fields where possible — for sender and organization details, fall back on profile fields rather than hard-coding values in the template.
• Standardize layouts — use as few shared Layout templates as possible rather than maintaining a dedicated layout for each Content template.
• Use Snippets — move recurring content into Snippets rather than duplicating it in every template.
• Keep tables simple — for self-defined table styles, opt for simple structures.

Troubleshooting

Typical sources of error when laying out templates and their causes:

Symptom	Possible cause	Solution
Placeholder is not replaced	Field name does not match the PlaceholderMapping	Check the field name and mapping (case sensitivity, exact name)
Style looks different than expected	Style link is missing or has been overridden locally	Check the Based on link to the Style template; reset local formatting
Drop-down content control is empty	Drop-down/building block content controls are bound to the respective template	Do not use drop-down/building block content controls in Snippets (see Implementation variants)

caution

Changes in the Style template affect all Content templates built on it. Proceed with particular caution here and test the effects before you release a changed Style template.

warning

The best practices documentation for classic templates is located in the reference section. The guidance above focuses on modern primedocs templates.