Articles in this section

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

Updated

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

  Prerequisites

  Important

  • 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 section.

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. 

  Important

  • Dynamic text element insertion (the inserted text element will also contain questions) is only supported for dropdown or checkbox form fields. When a flexible dropdown is used then the questions from the text element will not be shown.
  • A nested text element (text element used in another text element) is not supported.
    Form fields that show up cannot include dropdowns that trigger additional form fields to show up. This means only two levels of gating questions are supported: the initial question and the additional questions shown depending on the user's choice in the first question    .

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:

TextElement_CopyAssetID.png

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.

      Important

    • 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 needs to be placed in its 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.
    TextElement_SelectTextElement.png
  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.
      TextElement_AddTextElement.png
  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.

        Note

      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 'Sign Off' if that is the content of the text element.
      TextElement_PlaceholderEdit.png 

                                                                                                                              
      TextElement_PlaceholderName.png

       

  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.
    TextElement_Added.png

  Important

  • A text element cannot be inserted as an inline content control because it is assumed that a text element might contain more than 1 line of text. So the text element control control needs to be placed in it's own paragraph (it cannot be placed in the middle of a sentence).
    To verify if the text element binding is correctly set up, you can turn on 'Design mode' in Word and ensure that textElement is displayed on both sides of the content control:

    ValidTextElementBinding.png
  • Using a text element in a Shape or Text Box is not supported.
    You can only insert a text element (content control) in a paragraph or table cell.
  • If a text element and the document are using the same questions, you can use the Share value option in the properties of a Form field. This way a question is only shown once.

Text element smart field examples

Example 1 dropdown

In this example a text element is inserted using dynamic insertion, using a dropdown. In the example the data source 'EmploymentType' is used:
TextElement_Example1_DataSource.png 

  Note

The 'InsertEmploymentType' column in the data source containing the asset ID's needs to be of type Text in the Schema.

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

  • Question title: 'Employment type'.
  • Data source: 'Employment_type'.
  • Label column: 'Name'.
  • Reference name: 'Employment'.
    TextElement_Example1_Form.png

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}}.
    TextElement_Example1_SmartField.png                                                                                    

      Note

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

The result looks like this:

TextElement_Example1_Final.png

When generated by the end-user (use Preview Form), the text element inserted into the document will depend on the selected option in the 'Employment' dropdown question. Each text element contains different questions:

  • Permanent: Only contains a 'Start date' question.
    TextElement_Example1_Result1.png
  • Temporary:  Contains a 'Start date' and 'End date' question.
    TextElement_Example1_Result2.png
Example 2 checkbox

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:
    TextElement_Example2_FinalTeA.png
  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 and B2. Save the text element as 'Text element B.docx'. The result looks like this:
    TextElement_Example2_FinalTeB.png
  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.
    TextElement_Example2_UploadedAndCopyId.png 

      Tip

    • You can also save the asset ID to the Description field of the text element, so it's shown below the text element name.

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: 'Insert_text_element_A'.
  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: 'Insert_text_element_B'.
  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.Insert_text_element_A, "1100995797609873408", "")}}.
    • Placeholder: 'Generate new' (default).
    • Replace On Update: enabled (tick checkbox).

        Note

      • The asset ID is the value found in step 7 from creating the text element (see above).
      • When only the value 1100995797609873408 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:
    TextElement_Example2_SmartFieldA.png
  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.Insert_text_element_B, "1100995797477490688", "")}}.
    • Placeholder: 'Generate new' (default).
    • Replace On Update: enabled (tick checkbox).
  12. Click Add to template. The result looks like this:
    TextElement_Example2_ResultTemplate.png 

      Tip

    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:
    TextElement_Example2_FormTab.png                                                                          

      Note

    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:
    TextElementAandB.gifIn 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:
    TextElementAandBOrder2.gif
    In the document the result looks like this (with Update document):
    TextElement_Example2_FinalResult.pngWhen 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 to

conditions multiply tech_role
Was this article helpful?
0 out of 1 found this helpful

Comments

0 comments

Article is closed for comments.