WordContent Snippet

A WordContent snippet is a reusable block of native Word content: text with formatting, tables, images, content controls, or any other element that can exist in a Word document. It is stored as part of a template and injected into a document at generation time.

WordContent snippets are intended for layouters. They are stored in the Design (template) category and are not visible to end users.

When to Use WordContent Snippets

Use a WordContent snippet when you need to:

• Reuse a complex formatted block (e.g. a table, address block, or legal clause) across multiple templates.
• Dynamically insert different content blocks depending on user input or profile data.
• Keep headers, footers, or body sections consistent across content templates that share the same layout.

For simple formatted text (bold, italic, line breaks), use a FormattedText snippet instead. It is lighter and HTML-based.

Creating a WordContent Snippet

WordContent snippets are created and managed via the Snippet sidebar (task pane) in Word, not via a tab in the template editor.

1. In primedocs Desktop, open the template in which the snippet should be stored.
2. Open the Snippet sidebar.
3. Create a new snippet of type Word Content.
4. Give the snippet a name and edit its content in Word.
5. Save the snippet.

Using a WordContent Snippet in a Template

A WordContent snippet is embedded via the Fields document function: a Field of type WordContent retrieves the snippet through the snippets API. The result is inserted wherever the Field is placed in the template.

$.snippets.getWordContent("SnippetName")

This also allows the snippet to be selected conditionally based on form input or profile data:

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

note

primedocs.SnippetBlockPlaceholder=… and the other snippet placeholders are not a template-side reference to a snippet, but placeholders inside a snippet. They are filled when the snippet is retrieved via getWordContent(...) (see below).

Filling placeholders in the snippet

If the snippet contains placeholders, they are filled via a mapping object passed as the second argument. The key is the placeholder name, the value is the content to insert (a text, a field reference via $.getReference(...), or another snippet/field value):

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

For Profile, Forms and Data fields, $.createAutoMapping() builds the mapping automatically. For details on the placeholder types and the snippets API, see Snippets.

Pictures in the snippet

A WordContent snippet may contain pictures that are a fixed part of the content, such as a logo in a letterhead. Pictures embedded in the document (DrawingML, SVG with a PNG fallback, and VML from compatibility mode) are kept with all text wrapping and positioning options of Word, with cropping, rotation, hyperlink and picture styles such as borders, shadows or reflections, and with the decorative mark. On insertion the picture ends up in the right part of the document, also in headers and footers, in nested snippets and in table rows.

Two limits apply when the snippet is saved:

• Linked pictures (in Word via Insert › Pictures › Link to File) are rejected. The message reads "Linked pictures are not supported in snippets. Insert the picture so that it is saved in the document.".
• Size: A snippet may be at most 8 MB, pictures included. There is no limit per picture. If exceeded, the message "The snippet is … MB. The limit is 8 MB. Use fewer or smaller pictures." appears.

If Word cannot read the current selection, the add-in reports "Word could not read the selection. Please try again.". Select the content again and repeat the save.

Picture placeholder

If the picture is to be determined only on insertion, such as the logo from the profile, the snippet gets a picture placeholder (primedocs.SnippetPicturePlaceholder=<Name>, kind Picture in the dialogue Insert snippet placeholder). Word creates a picture content control with a placeholder picture for it. This picture sets the place and the size of the picture inserted later. A Picture field in the selection automatically becomes a picture placeholder when the snippet is created, the picture currently inserted becomes the placeholder picture.

In the mapping of getWordContent, a picture placeholder receives a Picture field. As with the other placeholder types, the way it is passed decides whether the picture stays bound to the field (see Placeholders for snippets):

// With a field reference: the content control stays bound to the field,
// a profile change in the open document swaps the picture.
$.snippets.getWordContent("Letterhead", { Logo: $.getReference("Profile.Org.Logo") })

// With the value of the field: the picture is inserted, the content control removed.
$.snippets.getWordContent("Letterhead", { Logo: $("Profile.Org.Logo") })

The size is set by the Picture field with WidthInCm and HeightInCm (see Setting the image size). The following field sets the logo from the profile to a width of 4 cm and is passed to the placeholder with { Logo: $.getReference("Logo") }:

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

In a picture placeholder the values have this effect:

Given	Effect
none	The picture takes the size of the placeholder picture.
one	The other side follows from the aspect ratio of the inserted picture.
both	The picture takes exactly these dimensions.

An invalid size (such as WidthInCm: -1) is ignored and reported as a warning when the template is tested.

Picture without a Picture field

The placeholder also accepts a picture address as a string ("base64:…") or an object with Source, WidthInCm and HeightInCm, as returned by the code of a Picture field. The picture is then inserted without a binding.

If the picture is empty, for example a Picture field without an image, primedocs inserts a transparent pixel: 1 px without a size, so the text moves up, or in the given size, so the space stays free. With a field reference the binding remains. If a picture arrives later, for example after a profile change, the add-in keeps the previous size. The Picture field should therefore set WidthInCm or HeightInCm.

A field reference to a Picture field in a text placeholder and a picture in any other placeholder type abort generation with an error naming the expected placeholder type. $.createAutoMapping() assigns a field reference to a picture placeholder that was created from a Picture field.

Pictures can also be put into a WordContent without a snippet, with $.wordContent.fromPicture($("Logo")) or $.wordContent.getBuilder().append($("Logo")), see wordContent API.

Cross-references and tables of contents

A WordContent snippet may contain REF and PAGEREF fields with the hyperlink switch \h, as Word sets them when inserting a cross-reference. A table of contents (TOC field) is only allowed without \h. If the TOC field itself contains the \h switch, the content is rejected. The PAGEREF fields with \h that Word writes into the entries of every table of contents, on the other hand, do not matter.

Quick Check fields in a snippet

A WordContent snippet may contain content controls tagged primedocs.Tracked. This allows a Quick Check block to be built once and reused across several templates. The tag must be exactly primedocs.Tracked. With an addition such as =value, the snippet cannot be saved. All types of content controls are allowed, including date and checkbox. A tracked content control must not be locked, otherwise it could not be filled in.

The placeholder text of a content control is preserved in the snippet and carried over into the generated document when the snippet is inserted. As long as a field still shows its placeholder text, the Quick Check counts it as not filled in.

Fill-in hints

Inside a snippet, only primedocs.HintText=[TEXT] is permitted. primedocs.HintField=[FieldId] is not allowed in snippets, so multilingual hint texts via a field do not work there.

Comments in a snippet

Word comments anchored in the content of the snippet are kept when the snippet is saved, including replies and the «resolved» state. During document generation they appear in the generated document at the same position.

primedocs removes personal data on saving: every comment shows the neutral value «Author» as its author, initials and date are removed. Mentioned persons (@ mentions) remain as plain text without an e-mail link. The comment text itself and regular web links are kept.

Not in headers and footers

Snippets with comments cannot be inserted into headers or footers, footnotes or endnotes. Generation fails there, because Word does not allow comments in these places.

Foreign content controls

If inserted Word content contains content controls from another document (e.g. foreign primedocs.Field tags from a subset document), this no longer blocks generation: content controls not created by primedocs are removed during cleanup. Foreign table-row content controls are preserved, so table structure and locked content remain unchanged.

Permissions

WordContent snippets are stored in the Design category. Only Template Admins and Sys Admins can create or edit them. See Snippet Permissions for details.