HotDocs Templates Overview

A HotDocs template is a document-based HotDocs application you build in HotDocs Author to gather answer data from users and produce customized documents specific to each user. For example, you can create a HotDocs template from an existing Word document (by replacing all the changeable text – e.g., names, addresses, phone numbers, etc. – with placeholders), then generate an interview that turns those placeholders into questions, then lastly, assemble a customized document specific to each user who fills out the interview.

Overview

A HotDocs template is based on a document whose main content you want to use over and over for different users. The main text of such a document does not change, while the details that make it specific to a given user need to change to make the document work for more than one user. HotDocs enables you to convert a standard Word document into a HotDocs template where you replace the changeable text with HotDocs fields called placeholder fields that you can use to reference template building blocks called components. The main component types you use in your templates include:

Variables – A type of component that enables you to gather answer data from your template users
Dialogs – A type of component that presents other components (usually variables) in an interview
Computations – A type of component that enables you to use the HotDocs scripting language to give HotDocs a sequence of instructions and expressions that calculate a value

Once you build your template using the elements above, you instruct HotDocs to generate an interview. An interview is the mechanism HotDocs provides to gather data from your template users. With the data you gather in an interview, HotDocs assembles a customized document.

Types of Templates

There are three types or categories of HotDocs templates:

Template Type	Description
DOCX template	You create a DOCX template in Microsoft Word. You usually modify an existing document adding variables and HotDocs script to create a DOCX template, although you can also start with a blank document. The final document HotDocs assembles from the template is also fully editable in your word processor. Templates you create in Word have a .DOCX file name extension.
Plain text template	When you want your template to produce a plain text document without formatting (for example, a .TXT or .XML file), you use HotDocs Composer (a part of HotDocs Author) to create a plain text template.
Answer Intakes	Answer Intakes differ from DOCX and Plain text templates in one main respect: are not document-based; rather they consist of an interview computation where you call the components or files you want to appear in an interview. You most often use Answer Intakes to gather answers you intend to use to pre-populate other interviews, or to act as a master interview for large document sets.

Common Tasks

Among others, a HotDocs template enables you to perform the following common tasks:

Workflow

Before you create a template, if you have a complicated set of documents you want to turn into templates, you should plan your template authoring project before you begin creating any templates. In addition, before you can create a HotDocs template, you must first create a workspace where you can store your template. Once you actually create your template, you build out your template functionality by following the workflow in the diagram:

For a fuller explanation of the steps involved, see the HotDocs Workflow Overview topic.

Template Files, Component Files, and Answer Files

There are two files HotDocs uses to assemble a customized document from your HotDocs template:

The template file (.DOCX,.TTX, .HDINT) - The template file is the file HotDocs creates based on your original document. This file contains all of your unchanging text, as well as the placeholders and regions and rules you add to your template. The placeholders tell HotDocs where to put the information you collect during the interview so HotDocs can assemble a customized document for a given user. The regions and rules tell HotDocs how to process portions of the text based on how a template user answers certain questions in the interview. There are three types of template files:
- .DOCX – the file extension of a HotDocs template based on a Microsoft Word document
- .TTX – the file extension for plain text templates
- .HDINT – the file extension for answer intakes

The component file (.CMP) - The component file contains all of the components you create to enable HotDocs to gather and format the information you need to fill in the placeholders in the template file

When you test your template locally, HotDocs also generates another file to deal with the answers you add during the interview:

The answer file (.ANX) - When you test your interview, HotDocs enables you to save your interview answers locally in an answer file so you can reuse these answers if you want

Template Support Files

There are two additional files HotDocs creates in the background when you create a template file. These files support the template at various stages in its life cycle. HotDocs stores these files on disk inside the workspace folder with the template.

HotDocs only displays the actual templates in the template list that appears in the Workspace Explorer.

Component File

The component file contains all of the components you create to enable HotDocs to gather and format the information you need to fill in the placeholders in the template file. The name of the component file associated with your template appears in the template details pane of Workspace Explorer as a clickable link that opens the workspace in Windows File Explorer. The default name for the component file HotDocs creates for a given template is the template filename and extension, followed by the .cmp extension. For example, a DOCX template's component file name format is: TemplateFileName.cmp.

Template Configuration File

The template configuration file for your template "points to" or declares the association between every template and its component file. The configuration file also stores the values of the template properties you set in the Template Properties dialog. Conceptually, the configuration file is "part of" the template, and whenever you update your template properties using the Template Properties dialog, the values in the template configuration file update.

The default name for the configuration file HotDocs creates for a given template is the template filename and extension, followed by the .config extension. For example, a DOCX template's configuration file name format is: TemplateFileName.docx.config.

When you create a new template from within an existing template, HotDocs creates the new template and its configuration file and points the new configuration file to the same component file as the parent template.

Template Identifiers

The template configuration file also contains a template identifier number that helps HotDocs to update the template properly. This identifier also helps HotDocs keep things in sync between HotDocs Author and HotDocs Advance and enables Advance to recognize the template when you upload it. If you need to upload the same template twice, you can generate a new template identifier.

You can edit a Template Identifier manually if you need to. Template Identifiers must use hexadecimal format (0-9 and A-F).

Auxiliary Templates

From any HotDocs template you can create a reference to, and thus, use, another template as an "auxiliary" template to augment the contents and functionality of your current, or "parent" template.

There are two ways to reference an auxiliary template from a parent template:

Use a placeholder field - if you use a placeholder field to reference another template, when HotDocs generates the interview for the parent template, as soon as it reaches the placeholder field for the auxiliary template, it generates the interview for the auxiliary template (before it finishes generating the rest of the parent template's interview). Likewise, when HotDocs assembles a document from the parent template, at the location of the placeholder field referencing the auxiliary template, it embeds the content from the auxiliary template within the parent template's assembled document, and the content of the auxiliary template becomes part of the assembled document.
Use an ASSEMBLE instruction - An ASSEMBLE instruction tells HotDocs to wait to present the interview and assemble the auxiliary template after completing this entire process for the "parent" template. The place you add the ASSEMBLE instruction to the "parent" template does not affect when HotDocs presents the interview or assembles the auxiliary template. ASSEMBLE tells HotDocs to wait until it has finished these processes for the parent template before initiating them for the auxiliary template.

"Auxiliary" and "Used in" in Workspace Explorer

By default, the Workspace Explorer does not show auxiliary templates in the list it displays of the templates in your workspace (you can change this setting using filters). On the other hand, when you select any template, if it references any other template, an expandable panel appears in the right pane labeled Auxiliary Templates. It also displays the number of auxiliary templates you reference from the current template. You can expand the list to review the names. Clicking the name of an auxiliary template opens it for editing.

If the template you select in the left pane acts as an auxiliary to another template, another expandable panel appears to the right labeled Used In. This also indicates the number of templates that reference your current template. You can expand the list to review the names. Clicking the name of a template opens it for editing.

Auxiliary Templates Only

While any template you reference from a parent template acts as an auxiliary to the parent, you may also make these templates available to your template users on their own. You may, however, find it useful to restrict certain templates to act only as auxiliary templates. If you want to ensure that you never upload such templates to HotDocs Advance, you can set the Auxiliary Template Only property in the Template Properties Dialog Box.

If you create a template by selecting content within a parent template, then, in the HotDocs Field Editor, choose to make that content into an auxiliary template, by default HotDocs sets this property on the new template you create. You can change this property setting at any time.

Limitations on HotDocs Templates

When creating a HotDocs template, please consider the following limitations:

Text Boxes in Word Templates

You cannot place variables inside Word text boxes. Alternatives to using text boxes may include creating a single table cell to place your variable. Refer to Microsoft Word's help file for specifics on creating these type of boxes.

Active Synchronization Applications

HotDocs does not recommend storing your templates using active synchronization and backup applications, such as SharePoint or OneDrive. These applications cause various errors when used in conjunction with HotDocs Author because they are actively accessing file data while the same files are open in HotDocs Author. This can occur when you store your templates directly on them or on a local drive which is constantly synchronized. HotDocs recommends a dedicated network file share instead.

You can have such application(s) running on your system, however, be sure to pause the synchronization while using HotDocs templates, Workspaces or answer files. Alternatively, you can disable the synchronization features, such as the Office File collaboration feature in the OneDrive settings. Similar settings can be found in other applications; refer to their respective user guides.

Excel Charts in Auxiliary Templates

You cannot embed Excel charts into auxiliary templates. If you want to show a chart in an auxiliary template, HotDocs recommends converting it to a JPG or using a snapshot. Excel charts can be embedded in templates which are not auxiliary templates.

Word Comments in Templates

HotDocs advises removing all Word comments prior to uploading or assembling a template. Comments can be used in assembled documents. If you require comments in your templates, consider adding a comment to a field.

Common Reference Topics

Among others, the following reference topics relate to this conceptual area: