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.

In the Word add-in, the context menu for a dynamic snippet provides Insert and Properties. Properties opens a read-only view of the configuration values. The values cannot be edited there, and the Language field is not shown in this view.

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.

Conversely, a mapping entry whose key matches no placeholder in the snippet has no effect and is reported as a warning naming the ignored keys, which makes typos visible. Keys in field path form (Profile.…, Forms.…, Data.…, Document.…) do not trigger the warning, because the automatically generated mapping deliberately supplies more field paths than the snippet contains.

There are four placeholder types. The tag always has the form primedocs.<Type>=<Name> (delimiter =), where <Name> is the mapping key. All four are created in the Word add-in from one button: Insert snippet placeholder in the ribbon group Templating. The «Choice in the dialogue» column gives the entry that produces each type (see Ribbon groups for template editing):

Tag	Choice in the dialogue	Use	Allowed values
primedocs.SnippetPlaceholder=<Name>	Snippet – within the running text	Text-like (in the text flow)	text, field references except WordContent/FormattedText
primedocs.SnippetBlockPlaceholder=<Name>	Block – one or more whole paragraphs	Whole block (own paragraph)	WordContent, FormattedText, InlineWordContent, text
primedocs.SnippetInlinePlaceholder=<Name>	Inline – within a sentence, without breaking the paragraph	Inline (within a paragraph)	InlineWordContent only
primedocs.SnippetTableRowsPlaceholder=<Name>	Table rows – replaces whole rows of a table	Repeating table rows	WordTableRows only

Structure of the placeholders

The type determines not only which values are permitted, but also where the placeholder may sit inside the snippet. This is checked during document generation. A wrongly placed placeholder aborts it.

Block. A block placeholder must span a whole paragraph. A content control at paragraph level or around a whole table cell is permitted. A content control inside a paragraph is only accepted if it stands alone in that paragraph, with no other text beside it. When filled, it is then raised to paragraph level automatically.

Do not insert block placeholders mid-sentence

For Block, the Word add-in creates a text content control at the current selection. Using the button in the middle of a paragraph produces a placeholder that fails the check. For a block placeholder, first create an empty paragraph and place the cursor there.

Table rows. A SnippetTableRowsPlaceholder must enclose a whole table row. It is the only one of the four types to receive a rich text content control for this. If the selection covers exactly one complete row, the kind is already preselected in the dialogue.

Snippet and Inline are not subject to a structural check because they sit in the text flow.

If a placeholder is misplaced, generation aborts with one of these messages:

Message	Cause
Snippet block placeholder '<Name>' must be alone in a paragraph.	The block placeholder sits in a paragraph that holds further content
Snippet block placeholder '<Name>' must be a block-level content control, but is of type '…'.	The block placeholder sits at a level that cannot hold a paragraph
Snippet TableRows placeholder '<Name>' must be around a table row.	The table rows placeholder does not enclose a table row

A value whose type the table above does not permit for that placeholder also aborts generation, for example with WordContent is only supported for Snippet Block Placeholders.

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.