A HotDocs Field is a container where you tell HotDocs Author to either add data or take some other action during document assembly; a field also functions as a visual indicator of the place in your template where you want Author to do these things. For example, when you add a placeholder field for a variable, HotDocs colors the text in the field blue. Likewise, when you add an instruction field to create a conditional region, HotDocs colors the text in the field green. These colors act as visual hints to the type of fields you are adding and the roles they play in the template; that way, when you come back later, you can more easily remember how you structured your template.
Fields in plain text templates do not have colors, because the plain text format does not enable this.
In this topic Hide
In a DOCX template, a field appears as a box (a Microsoft Word content control) containing either a data reference or an instruction. As a HotDocs template author, you add the data reference as an expression (a statement that returns a data value) or an instruction (a keyword that tells HotDocs to do something to your template). The HotDocs Field Editor provides an interface that helps you to know which action to take.
If you add a data reference to a HotDocs field, during document assembly, HotDocs evaluates the expression you added and inserts the resulting value at that location in the assembled document. If you add an instruction, then during document assembly, HotDocs executes your instruction to manipulate the contents of the template. Such manipulations typically include repeating sections of your content or including or excluding other sections, all based on the data your template users provide during the interview HotDocs generates based on the fields you add to your template.
You can also tell HotDocs to manipulate the contents of the assembled document once the assembly process finishes.
These three types of field contents manifest as the three types of HotDocs fields you can add to your template:
The instructions and expressions you place within these respective field types can cause HotDocs to place new content into a template, remove existing content from a template, or replicate existing content any number of times.
Among others, a HotDocs field enables you to perform the following common tasks:
Adding HotDocs fields to your template is how you change a regular word processing document into a functional HotDocs template. You add a HotDocs field to the main body of a template using the Field Editor. In addition to the main body of the template, you can place HotDocs fields within a template's headers, footers, text boxes, comments, footnotes and endnotes.
From the main Action menu of the Field Editor, you can choose to:
You can add HotDocs placeholder fields to components (to text that HotDocs displays during an interview) in the following places:
For example, suppose your template has a text variable that asks for a spouse's name, and this variable appears in the first dialog in your interview. As well as having a placeholder field for that text variable in the template, you could also put a placeholder field for that same text variable in the title of the next dialog, that way after your template user answers the variable with their spouse's name, the title of the next dialog (instead of being titled "Spouse's details", ) might read: "Anne Watson's details".
If you use a placeholder field in a component's interview display text, you must ensure the template user provides an answer for that placeholder before the interview displays the component containing the placeholder field.
Placeholders fields act as placeholders for any kind of expression; however, the most common kind of expression you point to with a placeholder field is a variable (a type of component that enables you to prompt your template users for various kinds of data in the interview HotDocs generates from your template).
You add a placeholder field at a place in your template where you want HotDocs to place a data value during document assembly.
When you add the placeholder (using the Field Editor), you also choose the type of data you want to add. You most commonly use a placeholder field to replace (in an existing document) some data you don't want (such as a specific person's name) with a marker that enables you to ask your template users for that same kind of data (for example, an employee's name).
The following types of placeholder fields are available:
When you are creating a template from an existing document, it is best practice for you to first identify the common kinds of data you need to ask for in your template, and then use Component Studio to create the variables and other types of components you need. After, you use the HotDocs Field Editor to add placeholders to your template and point to the components you want to reference at each location. You can also, however, create a variable or other component directly from the Field Editor when you add your placeholder field.
An instruction field enables you to tell HotDocs to complete several kinds of actions, some during the interview, some during the document assembly process. You can add the following types of instructions using an instruction field:
To help you more easily recognize the different types of fields in your DOCX template, HotDocs colors the text within fields with colors that vary according to the type of the field you add. In addition, to help you notice fields where you set Advanced Properties, HotDocs adds various symbols within the field (on the right). The Field Appearance dialog box enables you to set your preferences for how much information appears within a field.
The colors HotDocs applies to the field contents does not extend to the field delimiters (by default, these are brackets in the same color as the unchanging text in your template). HotDocs applies the colors listed below only for the actual contents of your fields:
Fields where your template users set Advanced properties have the following field appearance:
Symbols that can appear in a field (depending on what your template users set in the Advanced Properties) follow:
If both a repeat and sort are present, the symbols should appear in the proper sequence, according to which your template users set first.