Snippets

Snippets (text modules) are reusable content blocks that can be inserted into templates. They allow you to maintain commonly used content in one place and reference it across multiple templates.

Categories

Snippets fall into three categories that differ in visibility and management responsibility:

• Design (template snippets) — embedded in templates and intended for layouters. Used by the template engine during document generation and invisible to end users. The types WordContent and FormattedText described on this page belong to this category.
• Shared (public snippets) — shared across an organisation or department, visible and insertable by end users.
• Private (personal snippets) — created by individual users for personal use.

End-user snippets (the classic content blocks that users insert themselves) can live in any of the three categories. Which role can view and edit which category is described under Snippet Permissions. How a snippet is placed on manual insertion in the Word add-in, depending on the cursor position, is described under Insertion Behaviour.

Types of Snippets (for Layouters)

For template creation, primedocs supports two main snippet types:

• WordContent: Reusable Word content blocks that can include text, tables, images and other complex Word content. Used when you need to dynamically insert entire sections of Word content into a document.
• FormattedText: Lightweight HTML-based formatted text snippets. Used for formatted text passages that need consistent formatting across templates, such as header/footer content.

Dynamic snippets (DynamicSnippet)

In addition to the pre-authored snippets described above, snippets can also be generated dynamically during document generation — via the DynamicSnippet field type. Such snippets depend on the document's data context, appear in the snippet pane in the "Dynamic snippets" group, and can optionally be inserted via AutoText. They are supported in Word only.

Benefits

• Consistency: Maintain consistent content across all templates from a single source.
• Efficiency: Update content in one place and have it reflected in all templates that use that snippet.
• Dynamic content: Snippets can be made dynamic using JavaScript, allowing them to adapt to user input or profile data.

Using snippets in templates

Snippets are accessed in the Fields document function via the snippets API. There are three methods — one per snippet type:

Method	Returns	Snippet type
$.snippets.getText("Key")	text (string)	Text
$.snippets.getFormattedText("Key", { name: value })	FormattedText (HTML)	FormattedText
$.snippets.getWordContent("Key", { placeholder: value })	WordContent	WordContent

• getText returns plain text and takes no parameters.
• getFormattedText replaces Handlebars placeholders ({{name}}) in the snippet's HTML with the passed values.
• getWordContent fills the placeholders contained in the snippet via a mapping object (see below).

Placeholders in a WordContent snippet

A WordContent snippet contains placeholders (Word content controls with a primedocs. tag). When retrieved via getWordContent(key, mapping), each placeholder is filled from the mapping: the key is the placeholder name, the value is the content to insert.

$.snippets.getWordContent("SnippetName", {
  "Profile.User.LastName": $.getReference("Profile.User.LastName"),
  "Salutation": "Dear Sir or Madam"
});

Allowed values are: a string, a field reference via $.getReference("FieldId") (late binding, resolved only at generation time), and WordContent, InlineWordContent, FormattedText and WordTableRows values. A placeholder without a mapping entry raises an error.

There are four placeholder types. The tag always has the form primedocs.<Type>=<Name> (delimiter =); <Name> is the mapping key:

Tag	Use	Allowed values
primedocs.SnippetPlaceholder=<Name>	Text-like (in the text flow)	text; field references except WordContent/FormattedText
primedocs.SnippetBlockPlaceholder=<Name>	Whole block (own paragraph)	WordContent, FormattedText, InlineWordContent, text
primedocs.SnippetInlinePlaceholder=<Name>	Inline (within a paragraph)	InlineWordContent only
primedocs.SnippetTableRowsPlaceholder=<Name>	Repeating table rows	WordTableRows only

Fields in snippets

Technically, a snippet only ever contains placeholders, never fields — the actual values are assigned when the snippet is inserted. When creating a WordContent or FormattedText snippet in the Word add-in, however, the selected text may contain fields directly: primedocs automatically converts them into the matching placeholder on creation. The former manual procedure (delete the field, hand-build a placeholder with the correct type) is no longer needed.

Fields under the roots Profile, Forms and Data are converted. Depending on the field type, a different placeholder type is produced:

Field type	Placeholder
Text, Yes/No, Date	SnippetPlaceholder
InlineWordContent	SnippetInlinePlaceholder
WordContent, FormattedText	SnippetBlockPlaceholder

The placeholder name equals the full field path in dot notation (e.g. Profile.User.FirstName).

note

The automatic conversion happens in the Word add-in of the Desktop Client. Custom Fields, WordTableRows, images and hint fields are not converted automatically.

Generate the mapping automatically — $.createAutoMapping()

When inserting a WordContent snippet, every contained placeholder must be assigned a value. Instead of writing each mapping individually, $.createAutoMapping() produces the complete mapping as a one-liner:

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

The function returns an object whose keys are the known field references in dot notation (e.g. Profile.User.FirstName). Only fields under Profile, Forms and Data are included.

Individual entries can be added or overridden via spread syntax — for example for a custom field that is not captured automatically:

$.snippets.getWordContent("MySnippet", {
    ...$.createAutoMapping(),
    MyCustomField: $.getReference("AnotherField")
})

note

Custom fields and nested block placeholders (embedded snippets) are not covered by $.createAutoMapping() and must still be mapped by hand.