Ribbon groups for template editing
When a template is opened from the Template Editor, primedocs adds further groups to the primedocs tab: the tools used to edit a template (bind fields, place placeholders and hints, and, in PowerPoint, tag shapes).
This page names each button under the caption it carries in the ribbon, the tag it produces and the condition under which it is enabled.
The groups belong to the Office add-in of the Desktop Client (Windows). Outlook has no template editing group.
When the groups appear
The precondition in all three applications: the document was opened from the Template Editor for editing. The groups do not appear in a regularly generated document. In PowerPoint the presentation must additionally not be write-protected.
The Word Preview group follows a different condition: it appears in the generated test document, that is, in the result of a test run, not in the template opened for editing.
| Application | Tab | Group | Buttons |
|---|---|---|---|
| Word | primedocs | Templating | 4 (fields, placeholders, hints) |
| Word | primedocs | Tools | 4 (Word content controls, design mode, diagnostics) |
| Word | primedocs | Preview | 2 (test document only) |
| Excel | primedocs | Templating | 2 |
| PowerPoint | primedocs | Templating | 8 (tags and table of contents) |
| PowerPoint | Slide Master | Templating | 5 (layout names and tags) |
| Word / Excel / PowerPoint | Developer | Templating | Diagnostic tools |
Word
Word splits template work across three groups: Templating writes primedocs meaning into the document, Tools holds what works without a primedocs binding, and Preview appears in the generated test document only.
«Define placeholder text» and «Set Tracked» are greyed out here because the cursor position does not permit them.
Group «Templating»
| Button | Tag produced | Purpose |
|---|---|---|
| Bind field / Bind field/placeholder | primedocs.Field=<FieldName> or primedocs.Placeholder=<Name> | Opens the pane listing the bindable entries of the template |
| Insert snippet placeholder | primedocs.Snippet…Placeholder=<Name> | Placeholder that a snippet fills at runtime |
| Insert Hint | primedocs.HintText=<Text> or primedocs.HintField=<FieldName> | Places a completion hint |
| Define placeholder text | primedocs.PlaceholderField=<FieldName> | Sets the text Word shows in the empty content control |
The content controls produced are highlighted in different colours by type. The mapping is described under Accessing primedocs fields.
The three buttons on the right are enabled only when the current selection permits the action. What matters is whether a content control can be inserted at the cursor position, or whether the control there can show a placeholder text. Greyed out therefore means «not possible at this spot», not «not available in this template».
The rules at a glance:
- Snippet placeholders and hints can only be inserted outside content controls. When the cursor sits in a content control, including a rich text control or a control in a header or footer, both buttons are greyed out.
- Fields and ordinary content controls may be inserted into a surrounding rich text content control, but not into other types.
- Nothing can be inserted into a hint. This also applies when the cursor sits in a content control that itself lies inside a hint.
- If the selection already contains one or more content controls, nothing can be inserted at that spot.
If the enabled state no longer applies, for example because the ribbon still shows the state from before the cursor moved, the click aborts with a message naming the reason: «… because the surrounding element does not allow nesting» or «… because the current selection contains one or more Content Controls».
Bind field
Bind field is a toggle: it opens and closes the pane of the same name on the right, which can stay open throughout the template work. It replaces the earlier dialogue that closed after every field. The next time a template is opened, the pane reappears if it was open the last time.
The pane contains:
- The list of bindable fields, with name and field type. Hint fields and yes/no fields do not appear.
- A second list, «Layout placeholders», but only in a layout template that defines at least one bindable placeholder. Only then are the button and the pane called Bind field/placeholder. In a content template they read Bind field.
- A filter box above both lists and a counter below.
- A status line stating before the click what will happen: insert, change an existing binding, or «no field can be inserted at the current selection».
- Reload fields: fetches the field contract from the primedocs client again without blocking Word. This surfaces fields created after the template was opened.
Insert by double-click, with the Enter key or with the button. The cursor then sits behind the content control created, so typing can continue directly.
Several fields at once: hold Ctrl or Shift to select several entries. They are inserted one after another in the order they were picked. primedocs puts a space between fields in the text flow, while block contents (picture, WordContent, table rows) follow one another directly.
Change instead of insert: if the cursor sits in a content control that is already bound, the pane changes that binding. Fields of another type are then greyed out (the tooltip gives the reason). Only a single selection is applied. With several entries marked, the button stays inactive.
Inside content controls: a field may be inserted into a surrounding rich text content control, for example into an ordinary content control from the «Tools» group. Inside a hint this is not possible, nor inside a content control that itself lies in a hint. An existing field or placeholder binding cannot be changed there either. In these cases the status line reports that no content control can be inserted here because the surrounding element does not allow nesting.
A selection always lives in one of the two lists: selecting in one clears the other.
For fields of type WordTableRows the selection must cover exactly one complete table row. Otherwise the action aborts with a message.
Insert snippet placeholder
Creates a placeholder that makes a snippet fillable at runtime. There are four kinds. The kind is chosen in the dialogue, not through four separate buttons:
| Choice in the dialogue | Tag produced |
|---|---|
| Snippet – within the running text | SnippetPlaceholder |
| Block – one or more whole paragraphs | SnippetBlockPlaceholder |
| Inline – within a sentence, without breaking the paragraph | SnippetInlinePlaceholder |
| Table rows – replaces whole rows of a table | SnippetTableRowsPlaceholder |
Which values each kind permits and where the placeholder may sit is described under Snippets.
The procedure: select the target spot, click the button, choose the Kind in the Insert snippet placeholder dialogue, enter a Name and confirm with Insert. The name is mandatory because it later serves as the key in the mapping object of $.snippets.getWordContent(...).
The kind is preselected from the context: if the selection covers exactly one complete table row, Table rows is already set, otherwise Snippet.
For Block, a text content control is created at the current selection. Inserted in the middle of a paragraph, this produces a placeholder that document generation later rejects. First create an empty paragraph and place the cursor there (see Structure of the placeholders).
The title of the content control created carries the tag name in brackets, for example Salutation (SnippetBlockPlaceholder). Its content shows the name in square brackets, so [Salutation]. Table rows get a rich text content control, the other three a text content control.
What the placeholders do in the snippet and how they are filled is described in Snippets.
A snippet placeholder cannot be placed inside a content control, not even inside a rich text control or a content control in a header or footer. The button is greyed out there, and also when the selection already contains a content control. An existing snippet placeholder cannot be converted to another kind this way. Instead, delete it and place it again.
Insert Hint
Places a completion hint at the selection, which the Quick Check shows while the document is being filled in. The Insert hint content control dialogue requires a Title and the Hint itself.
A hint comes either from a field or from a fixed text, never both. Both are entered in the same box: as you type, it suggests the hint fields of the template. Choosing a suggestion produces primedocs.HintField=<FieldName>, otherwise primedocs.HintText=<Text>. An icon in the box indicates which of the two currently applies and toggles it with a click: for a linked field (</>) the click turns it into fixed text with the same wording, for fixed text (A) it links to the field whose name exactly matches the text. Details under Placeholder texts.
A hint can only be placed outside content controls, the button is greyed out inside any content control. Conversely, nothing can be inserted into a hint: neither a field nor a layout placeholder, another hint, a snippet placeholder or a content control. Existing bindings inside a hint cannot be changed. The reason: during generation, primedocs replaces and locks the content of the hint as a whole.
Define placeholder text
Sets the text Word shows in the content control at the cursor for as long as that control is empty, either as a fixed text or from a text field of the template, which follows the document language. What is written into the tag, what happens during generation, and why bound fields without a placeholder text of their own still get one is described in Placeholder texts.
The button is enabled when the cursor addresses exactly one content control that can show a placeholder text: bound fields, layout placeholders, tracked content controls and content controls without a tag. It stays greyed out on picture and check box content controls, on hints, and on content controls whose tag primedocs cannot interpret.
Group «Tools»
This group holds what works without a primedocs binding. It is visible in both modes (while editing the template and in the generated test document) so that the developer tools live in a single place. The two content control buttons appear only while editing the template.
| Button | Purpose |
|---|---|
| Insert content control | Creates an ordinary Word content control with type, title and placeholder text, without a primedocs binding |
| Set Tracked | Marks the content control at the cursor as an open spot for the Quick Check |
| Design Mode | Toggles Word's design mode, in which placeholder texts can be edited directly in the document |
| Developer tools | Diagnostic view (see below) |
Inserting and marking are two separate buttons so that it is clear before the click which of the two happens. Both are described under Quick Check.
Insert content control follows the same rules as «Bind field»: allowed in the running text and inside a surrounding rich text content control, not inside a hint and not when the selection already contains a content control.
Set Tracked acts on the content control the cursor addresses, just like «Define placeholder text»: the single control the selection spans, or the control the cursor sits in. This also works with nested content controls and in headers and footers. The button is enabled as long as the control carries no primedocs binding (field, placeholder, snippet placeholder or hint). A field reference from «Define placeholder text» does not interfere and is kept. When the selection spans several content controls, the button is greyed out.
Design Mode is Word's built-in button from the «Developer» tab, placed here within easier reach. Saving a template in design mode is harmless: documents created from it open in normal mode and keep their placeholder texts.
Group «Preview» (test document)
When a test document is generated from a template, the Preview group appears in place of the templating group, holding the two preview actions. Both use the first page of the test document as the preview image of the template:
- Generate language-independent preview (icon: document with an eye): the image applies to all languages of the template.
- Generate preview for language (icon: globe): the image applies only to the document language chosen in the dialogue that follows. This gives each language its own preview image.
Both buttons are enabled only once primedocs has recognized and loaded the test document. The tooltip of each button states its effect.
Excel
In Excel the data binding is created through named ranges, not content controls. The group is correspondingly narrow:
| Button | Purpose |
|---|---|
| Bind field | Writes the field reference into the selected cell |
| Developer tools | Diagnostic view (see below) |
In Excel, Bind field still opens a selection list of the fields (the Word pane does not exist here) and writes the formula =<FieldId> into the selected cell, the same reference that can also be typed by hand. Only fields of type Text and Date are offered. An empty selection clears the cell content.
Workbook protection is checked before the action runs: if the workbook is protected, nothing happens and the ribbon is re-evaluated.
How named ranges, field IDs and the special form {FieldId} in headers and footers work together is described in Excel template.
PowerPoint
In PowerPoint no content controls are placed. Instead, tags are set on shapes and slides. A tag is a name-value pair that primedocs evaluates during generation. Which tags exist and what they do is listed under PowerPoint tags. This page describes only the buttons that set them.
| Button | Tab | Enabled when |
|---|---|---|
| Manage tags of selection | primedocs, Slide Master | always (while the group is visible) |
| Select all shapes with tags | primedocs, Slide Master | always |
| Tag overview of selection | primedocs, Slide Master, Developer | always |
| Set layout names | Slide Master | in a master template only |
| Define agenda title | primedocs | in a table of contents template only |
| Define agenda slide numbers | primedocs | in a table of contents template only |
| Define agenda height range | primedocs | in a table of contents template only |
| Define agenda gap | primedocs | in a table of contents template only |
Manage tags of selection
Opens the Tags dialogue for the selected shape. It presents the tag types primedocs knows as individual selection boxes, each with a descriptive name and explanation:
- Field tags: chosen from the fields of the template.
- Placeholder tags: chosen from the defined placeholders.
- Tags with a fixed value range: chosen from the values permitted for that tag.
Below them sits the multi-line Additional tags box for everything the selection boxes do not cover. It follows the rule the dialogue itself states: tagname=value adds a tag, an empty entry removes it.
Select all shapes with tags
Selects every shape carrying at least one tag on the current slide or in the current slide master. Useful for seeing which shapes are bound to primedocs at all in an unfamiliar or grown layout.
Tag overview of selection
Shows the tags of the currently selected shapes as an overview. Unlike Manage tags of selection, the overview is read-only and works across several shapes.
Set layout names (Slide Master)
Enabled in a master template only, and only on the Slide Master tab. The Slide layouts dialogue lists every slide layout of the presentation with a selection box. The choices are the layout names defined by the Slide Layout document function. This assigns each PowerPoint layout to a primedocs slide layout. Without that assignment, primedocs cannot select a layout during generation.
The four agenda buttons
Enabled in a table of contents template only. They assign the selected shape its function in the generated table of contents:
| Button | Function of the shape |
|---|---|
| Define agenda title | Entry (title) |
| Define agenda slide numbers | Page number |
| Define agenda gap | Gap between entries |
| Define agenda height range | Available vertical space |
The complete procedure, including shape formatting, is described under PowerPoint table of contents.
Diagnostic tools
Developer tools opens a diagnostic view of the primedocs data of the open document: the custom XML parts, the document data and the Word styles. It serves troubleshooting in support cases. The contents shown are not a supported contract and can change without notice. The button is enabled once primedocs has recognized and loaded the document.
In all three applications the button also sits on the Word, Excel or PowerPoint Developer tab. In PowerPoint that tab additionally holds Tag overview of selection and the Idx editor, an aid in the context of design conversion. Normal template work does not require these tools.
Customising the ribbon
Which groups and buttons of the primedocs tab are visible can be configured organisation-wide. The corresponding IDs and the XML format are described under Configuring primedocs ribbon elements.
Several element IDs no longer exist after the Word groups were restructured. Entries in <HiddenRibbonElements> that point at them run into nothing without an error message and no longer hide anything:
PrimeDocsTemplating.WordInsertSnippetBlockPlaceholderAction
PrimeDocsTemplating.WordInsertSnippetInlinePlaceholderAction
PrimeDocsTemplating.WordInsertSnippetTableRowsPlaceholderAction
PrimeDocsTemplating.WordInsertOrSetTrackedContentControlAction
PrimeDocsTemplating.WordDisplayDeveloperToolsAction
PrimeDocsTemplating.PrimeDocsTemplating.InsertPlaceholder
PrimeDocsTemplatingInDocumentMode.WordDisplayDeveloperToolsActionInDocumentMode
The developer tools have not been removed but are reachable under PrimeDocsTooling.WordDisplayDeveloperToolsAction.