How to dynamically insert text elements from the Library in a document

About this article

This article explains how to insert text elements from the Library through smart fields so it can be automatically inserted when generating a document. 

• What is text element insertion?
• How to insert text elements from the Library into a document with smart fields?
• Text element smart field examples

Prerequisites

What is text element insertion?

There are two different types of text elements that can be inserted into a document: 

• Static text element: the text element does not contain any questions in the response form. When dynamically inserting a static text element into a document, the end-user will be prompted with the document response form only.
• Dynamic text element: the text element does contain smart fields and at least one question in the response form. When dynamically inserting a dynamic text element into a document, the end-user will be prompted with a response form gathering both the document and the text element response forms. The text element placeholder displayed in the document response form will dictate where the text element response form should appear for the end-user. 

There are two different ways of inserting text elements into a document, either by using a static or a dynamic insertion:

• Static insertion: linking a specific text element to be inserted in the document.
• Dynamic insertion: linking a dropdown or checkbox question in the response form where the user can pick an answer, which will insert the desired text element in the document. 

When working with text element insertion, the asset ID of the text elements will be necessary. The asset ID can be found in the Admin Center, by navigating to the Text element Library, finding  the relevant text element, clicking on the ellipsis menu, and using Copy asset ID:

How to insert text elements from the Library into a document with smart fields? 

When building a smart template, the text element smart field can be used to insert text elements into a document. To create a text element smart field, it will be necessary to specify the text element that should be inserted. The text elements can be inserted statically or dynamically using asset ID's inside a document. Creating a text element smart field can be achieved following the steps below: 

1. In Template Designer, navigate to the Template tab.
   
   
2. Select the location where the text element should be inserted. Place your cursor at the desired location in the template, or select the text that should be replaced by the smart field. If no text is selected when adding the smart field, the display name will be inserted and used as placeholder text.
   
   

   Make sure your selection is not in-line as inline content controls are not supported for text element insertion (see additional explanation below). In other words: a text element control control needs to be placed in it's own paragraph (it cannot be placed in the middle of a sentence). If you want to add a text element to the header of a template and the template is also configured with an Image Header then you need to add an extra paragraph after the one containing the text element. If you omit to do this then when a document is updated (with 'Update document') unexpected behavior might occur, for example a logo is now shown at another position or has disappeared.

    
3. Click + Add smart field. Note: this step does not apply if you are adding the very first smart field in the template.
   
   
4. Click on Text element.
   
   
5. Enter a Display Name. The display name will be displayed on the Template tab once the smart field has been added.
   
   
6. Manually enter the Asset Id:
   • For a static insertion, copy the asset ID from the Text element Library into the Asset Id field.
   • For a dynamic insertion, create the desired binding linked to the response form using the binding syntax.
7. When creating a text element smart field a text element placeholder will be automatically inserted in the response form. The placeholder defines where the text element response form will appear for the end-user:
   
   • By default a new placeholder will be generated.
   • If a placeholder already exists in the response form, it will be selectable from the list.
     It can be disregarded if the inserted text element does not contain a response form.
     
     

     A new placeholder will be named 'Placeholder 1', 'Placeholder 2' etc., but can be renamed on the Form tab in the Question title field. For example rename 'Placeholder 1' to 'Disclaimer' if that is the content of the text element.

8. Optionally enable Replace on update. When enabled, the inserted text element might be replaced when using the document content updater.
   
   
9. Click Add to template. The smart field will be added to the template and will be displayed in the Template tab.

Text element smart field examples

Example 1

In this example a text element is inserted using static insertion.

A text element smart field is created, linking to a text element that contains two questions ('Monthly salary' and 'Currency', highlighted in red in the response form preview). Then the placeholders are reordered so the text element questions will appear at the desired position in the response form. Finally the preview of the form is opened.

Example 2

In this example a text element is inserted using dynamic insertion, using a dropdown.

In the example the data source 'EmploymentType' is used:

On the Form tab a dropdown question is created in the response form using the following values:

• Question title: 'Employment Type'.
• Data source: 'EmploymentType'.
• Label column: 'Name'.
• Reference name: 'Employment'.

On the Template tab a binding is created for the text element placeholder:

• Display Name: 'Employment type text element insertion'.
• Asset Id: {{Form.Employment.InsertEmploymentType.
  
  

  Because the data source contains the text element asset ID's in the 'InsertEmploymentType' column a binding to that column is created.

   

Each text element contains different questions:

• Permanent: Only contains a 'Start date' question.
• Temporary:  Contains a 'Start date' and 'End date' question.

When generated by the end-user (as shown in the preview), the text element inserted into the document will depend on the selected option in the 'Employment' dropdown question.

Example 3

In this example a text element is inserted using dynamic insertion, using a checkbox.

Two text elements (with different questions) are created, then a template with checkboxes that will insert one or both text elements, or no text element when none of the checkboxes is ticked.
Questions will have names 'A1', 'B1' and 'B2' for an easy explanation.

Create 'Text element A' and 'Text element B'

Create the text elements following the steps below:

1. Create a text element. On the Form tab click + Add question then use these values:
   
   • Type: 'Text'.
     
   • Question title: 'A1'.
   • Reference name: 'A1'.
2. Click + Add to form.
   
   
3. In the template type a placeholder text for the question, for example '[A1]' and select the placeholder.
   
   
4. On the Template tab click Form responses, select form field A1, click Add to template and save the template as 'Text element A.docx'. The result looks like this:
   
   
   
   
5. Repeat steps 1-4 to create the second text element, but this time create two placeholder texts '[B1]' and '[B2]' and corresponding form fields B1 andB2. Save the text element as 'Text element B.docx'. The result looks like this:
   
   
   
   
6. Upload both text elements to the Admin Center.
   
   
7. For both text elements get the asset ID's (you'll need them when creating the template), by clicking the ellipsis button and then Copy asset ID and save them (temporary) to e.g. Notepad.
   
   
    
   

   Tip: You can also save the asset ID to the Description field, so it's shown below the text element name like in the screenshot above.

    

Create 'Template with checkboxes'

Create the template with checkboxes following the steps below:

1. Create a template. On the Form tab click + Add question then use these values:
   
   • Type: 'Checkbox'.
     
   • Question title: 'Insert text element A'.
   • Reference name: 'InsertTextElementA'.
2. Click + Add to form.
   
   
3. Create another checkbox question by clicking + Add question and use these values:
   
   • Type: 'Checkbox'.
     
   • Question title: 'Insert text element B'.
   • Reference name: 'InsertTextElementB'.
4. Click + Add to form.
   
   
5. In the template type a placeholder text '[TextElementA]' and select the placeholder.
   
   
6. On the Template tab click Text element then use these values:
   
   • Display name: '[TextElementA]'.
     
   • Asset Id: {{IfElse(Form.InserttextelementA, "859706897059020333", "")}}.
   • Placeholder: 'Generate new' (default).
   • Replace On Update: enabled (tick checkbox).
     
     

     The asset ID is the value found in step 7 from creating the text element (see above). When only the value 859706897059020333 is placed in the Asset Id field, the text element would always be inserted. In this example the text element only needs to be inserted when the checkbox is ticked, so that's why an IfElse() function is used.

7. The result looks like this:
   
   
   
   
8. Click Add to template.
   
   
9. In the template type a placeholder text '[TextElementB]' and select the placeholder.
   
   
10. Click + Add smart field.
    
    
11. On the Template tab click Text element then use these values:
    
    • Display name: '[TextElementB]'.
      
    • Asset Id: {{IfElse(Form.InserttextelementB, "859706990859386444", "")}}.
    • Placeholder: 'Generate new' (default).
    • Replace On Update: enabled (tick checkbox).
12. Click Add to template. The result looks like this:
    
    
     
    

    In the screenshot above Design mode is enabled on the Developer tab in the Word ribbon, so it's easier to see what is plain text or a content control.

     
13. On the Form tab the result looks like this:
    
    
     
    

    In the screenshot above Placeholder 1 defines where the question from 'Text element A' is shown and Placeholder 2 where the questions from 'Text element B' are shown. Optionally the placeholders can be renamed.

     
14. To see what the result is when a user creates a document, click Preview form.
    
    This is the result with Placeholder 1 and Placeholder 2 at their default position.
    Questions 'A1', 'B1' and 'B2' are grouped together at the bottom of the composer:
    
    
     
    

    In the example above it's okay that the questions are grouped together, because the template only contains a few questions, but if a template has many questions it's best practice to position each placeholder directly below the corresponding checkbox (or dropdown) as shown in the example below.

      
    This is the result with Placeholder 1 and Placeholder 2 at their modified position.
    Question 'A1' is shown directly below the 'Insert text element A' checkbox and questions 'B1' and 'B2' are shown directly below the 'Insert text element B' checkbox:
    
    
    
    In the document the result looks like this (with Update document):
    
    
     
    

    When Update document is applied the questions are shown when the checkbox was unticked when the document was created, but now is ticked. This is because the option Replace On Update is enabled (see step 6, creating the template). If Replace On Update was disabled then the checkbox would still be shown, but the question would not appear when the checkbox is ticked.

Related articles