Tagging elements overview

Tagging elements are special markers or placeholders within a Document Template that indicate where specific data from the Data Source should be inserted during document generation. When you generate a document form a Document Template, these tagging elements are replaced with actual data values from your Data Source, transforming a template into a final document containing real data in the place of the tagging elements.

You can insert tagging elements into a template using the buttons in the Tagging Elements ribbon group in Microsoft Word. Each tagging element type serves a specific purpose, from displaying simple text values to generating complex repeating sections or conditional content.

Types of tagging elements

Tagging elements fall into two main categories based on how they function:

Placeholder tagging elements are placeholders that are replaced with actual data values during document generation. The content inside these tagging elements is there only for your convenience during template design, and it is not preserved, as these tagging elements are simply replaced altogether with real data content during document generation.

  • Field - Displays text, numbers, or date-time values
  • Image - Renders images dynamically from data
  • Summary Field - Calculates and displays aggregate values like totals or averages
  • Subdocument - Embeds another document
  • Barcode - Renders data as barcodes or QR codes
  • Label - Displays localized text for multi-language templates
  • Var - Defines a variable storing a value for reuse within a template, displays nothing

Container tagging elements require content to be present and define how that content behaves (repeating, conditional display, grouping, etc.). The content you place inside these elements is preserved and processed according to the element's configuration. Each of these tagging elements serves a specific purpose, for example, to repeat certain sections of the document for collections of data, or to conditionally display content based on data values. These tagging elements are not simply replaced with data (like placeholders); instead, they define structures and behaviors for the content they contain. These include:

  • List - Generates repeating sections for collections of records
  • Group - Groups records in given collection of records by specified key(s) and generates repeating sections for each group
  • If - Shows or hides its wrapped content based on condition
  • Context - Sets a data context for nested elements
  • Hyperlink - Makes its wrapped content a clickable link

Container tagging elements can nest other tagging elements, allowing you to create more complex templates. For example, you can place an If tagging element inside a List tagging element to conditionally display content for each item in a collection, or a List tagging element in a Group tagging element to list records of each group.

Data binding

Data binding links a tagging element to a specific data field or record in the Data Source, ensuring the correct data appears in the generated document.

When you data-bind a tagging element, you specify two components:

  • Binding Source - The root of the data, such as a section in the Data Source (Parameters, Main Data, General Data) or the current Data Context provided by a parent container tagging element
  • Binding Path - The specific data field or record within the selected Binding Source, which can be a simple path or a Power Fx expression

Container tagging elements like List, Group, and Context can provide a data context for their nested elements. For example, when a List tagging element is bound to a collection of invoice line items, each nested tagging element operates within the context of the current line item being processed.

Common scenarios

Tagging elements enable a wide range of document generation scenarios:

  • Displaying simple values - Use Field tagging elements to show customer names, order numbers, dates, and other record-specific information
  • Repeating sections - Use List tagging elements to generate invoice line items, quote products, or any repeating data
  • Conditional content - Use If tagging elements to display special discount messages only when conditions are met
  • Summarization and aggregation - Use Summary Field tagging elements to compute totals, subtotals, averages, or counts
  • Multi-language support - Use Label tagging elements to create templates that dynamically adapt to different languages
  • Branded documents - Use Image tagging elements to dynamically insert company logos, product images, or signatures

Troubleshooting tagging element insertion

If tagging element buttons appear disabled on the ribbon, this typically means you have a tagging element selected that doesn't allow nesting other elements inside it. Field, Image, Summary Field, Barcode, and Label tagging elements cannot contain nested elements.

To enable buttons for inserting a new tagging element:

  • Move the cursor outside the currently selected tagging element in the document using arrow keys or by clicking
  • Select a different location where you want to insert a new element

Related content