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

About this article

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

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

Prerequisites

Library and at least one Dynamics modules enabled Templafy Desktop and Office VSTO add-in installed Tenant admin/owner access or Space owner access At least one text element uploaded in the Text elements Library

 

The Text element smart field is only available in Word. Text element insertion is only supported with the Documents Library and is not supported with the Text elements and Email elements Libraries. Text element insertion is not supported when distributing a default template to end-users via Library Configuration tab.

 

What is a 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. 

It should be noted that working with dynamic text element insertion (the inserted text element will also contain questions) is only supported when using a dropdown question, utilizing a checkbox or a flexible dropdown question will not bring in the questions related to the text element.

 

Furthermore, 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 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 utilized 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 IDs inside a document. Creating a Text element smart field can be achieved following these steps: 

1. In the 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 Control isn't supported for text element insertion (additional explanation below).
3. Click Add smart field
   This step doesn't apply if you are adding the very first smart field in the template 
4. Click on More
5. Click on Text element
6. Enter a Display Name
   The display name will be displayed in the Template tab once the smart field has been added.
7. 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
8. Select the Placeholder
   When creating a Text element smart field, a Text element placeholder will be inserted in the response form. The Text element placeholder displayed in the document response form will dictate where the text element response form should appear for the end-user. By default, a new Text element placeholder will be generated. If a Text element 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.

   
   
   
9. Optionally, turn on Replace on update
If Replace on update is checked, the inserted text element might be replaced when using the document content updater. By default, it's unchecked, disabling updates.
10. Click Add to template
    
    • The smart field will be injected into the template and will be displayed in the Template tab

 

Once the smart field has been created, it can be edited, or deleted. Remember to reorder Text element placeholder in the response form if the text element that will be inserted also contains a response form. The Text element placeholder can be renamed by editing the question in the response form. Also, if the text element and the document are using the same questions, the Share value option in the response form should be used.  Achieving complex text element insertion can be achieved by editing the binding of the Text element smart field and adding functions, conditions, and operators.

 

It should be noted that Text element can only be inserted into Content Controls that are either Block or Cell level. Inline Content Control is not supported for insertion of Text element, because it is assumed that the Text Element will contain more than 1 line of text. To verify if the text element binding is correctly set up, one can turn on "Design mode" in Word and ensure that textElement is displayed on both sides of the content control:  The use of a Text element in a Shape or Text Box is not supported. You can only insert a Text element in a paragraph or table cell.

 

Text element smart field examples

 

Inserting a text element using static insertion in a document in Word

Create a Text element smart field linking to a text element containing a response form with two questions (Monthly salary and Currency, highlighted in red in the response form preview), and reordering the Text element placeholder to ensure that the text element questions will appear at the right place in the response form of the document. The complete response form  can be previewed by clicking on Preview form in the Form tab.

 

 

Inserting a text element using dynamic insertion in a document in Word

Create a Dropdown question in the response form using " Employment" as the Reference Name, linking to "EmploymentType" data source, and displaying the Name column. The data source itself contains text element asset IDs in the "InsertEmploymentType" column. Therefore, we will be using {{Form.Employment.InsertEmploymentType as a binding in the Asset Id field of the Text element smart field. 

Each text element contains different questions:

• Permanent contains one "Start date:" question 
• Temporary contains two "Start date:" and "End date:" questions

When generated by the end-user, the text element inserted into the document will depend on the answer provided for the "Employment" question of the response form.

 

It should be noted that working with dynamic text element insertion (the inserted text element will also contain questions) is only supported when using a dropdown question, utilizing a checkbox or a flexible dropdown question will not bring in the questions related to the text element The column in the data source containing the Asset Id (in the example below this is the InsertEmploymentType column) needs to be of typeText in the Schema.

 

EmploymentType data source

 

 

Related articles

How to upload files to Libraries? What are text element placeholder and slide placeholder in the response form? What is the binding syntax used in smart templates? What are smart fields? How to get an overview of the smart fields created in the template? What are functions, conditions, and operators? How to show or hide a question based on the answer to another question (gating questions)