Use Variable Inserts to Insert Sub-templates on the Fly

From HotDocs Wiki

Jump to: navigation, search

During template automation, developers use INSERT instructions to merge text, typically boilerplate language, into a main-level document. However, you, as a developer, may not always know, at design time, which templates you want to insert.

When this situation arises, you can use an extended insert, which allows you to specify the template's file name during document assembly, rather than during template development.

Note: The technique described below is only necessary for compatibility with HotDocs 2008 and earlier. For HotDocs 2009 and later, INSERT instructions have been enhanced to support variable insertions directly. The workarounds listed below are therefore deprecated and may not be supported in a future version.

For example, say there are hundreds of sub-templates that could potentially be inserted in the main document. It wouldn’t make sense to try to automate the template to account for each of these sub-templates—especially when new sub-templates are being created and added to the group on a regular basis. Using an extended insert, however, you can script your integration such that it specifies the name of the inserted file when you assemble the document.

To create an extended insert requires two parts—creating a Text variable and then creating an INSERT instruction that inserts the value of the Text variable. How this works is, during assembly, your integration passes the inserted template’s file name to HotDocs as the answer for the Text variable. HotDocs then uses that value as it processes the INSERT instruction, and the text of the inserted template is merged in the assembled document.

To create an extended INSERT instruction

  1. Create a Text vaiable in your template. (The answer for this variable will be the file name of the template or templates you want to insert. It can also include other scripting, such as IF instructions.)
  2. Click in the template where you want the inserted template to appear.
  3. Click INSERT Field. The INSERT Field dialog box.
  4. Enter the file name for any tmeplate and click OK. The instruction is merged in the template.
  5. Replace the file name with the name of the Text variable you created in Step 1, enclosing the variable name in angle brackets, like this (FileNameVariable represents the Text variable):

«INSERT "<FileNameVariable>"»

You can test this process by inserting the Text variable in the template and then test assembling the template. When prompted for an answer for an answer to the Text variable, enter a full INSERT instruction in the answer field (for example, «INSERT "InsertedTemplate"»). The text of the inserted template is merged into the assembled document.