HotDocs Fields Overview

A HotDocs Field is a container where you tell HotDocs Author either to 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, by default, 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.

Overview

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:

  • Placeholder fields – act as a pointer or reference to the type of data you want to add at that location, as well as its source (e.g., variables, expressions, computations, and auxiliary templates). Placeholder fields also indicate the place in the template where HotDocs should insert the data values from these data sources. HotDocs does not insert the data until document assembly.
  • Instruction fields – indicate where HotDocs should execute a specific instruction during document assembly.
  • Marker fields – indicate where HotDocs should format and punctuate text.

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.

Common Tasks

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

Workflow

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:

  • Add placeholders where you want HotDocs to add data and other content during document assembly
  • Add instructions where you want to surround template content with conditional or repeated regions
  • Instruct HotDocs to perform other operations, such as changing the formatting language

HotDocs Fields within Components

You can add HotDocs placeholder fields to components (to text that HotDocs displays during an interview) in the following places:

  • The properties Title, Prompt, Additional information, etc. on components such as variables and dialogs
  • The Text property on Dialog Elements (Text Element, Divider, Script Link and Web Link)
  • Non-key columns on Fixed table components, Single Select variables, and Multi Select variables

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.

Placeholder Fields

HotDocs Author WorkflowCreate a template Add placeholders Group variables in dialogs Create regions and rules Customize an interview Upload a template

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.

Instruction Fields

HotDocs Author WorkflowCreate a template Add placeholders Group variables in dialogs Create regions and rules Customize an interview Upload a template

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:

Field Appearance in DOCX Templates

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.

Field Content Colors

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:

  • Placeholder Field Colors
    • Blue (RGB 0,0,255)—variables and expressions
    • Medium Blue (RGB 0,64,128)—sub templates
  • Instruction Field Colors
    • Green (RGB 0,128,0)—IF/ELSE IF/ELSE/END IF
    • Maroon (RGB 128/0/0)—REPEAT/END REPEAT
    • Red (RGB 255,0,0)—LANGUAGE
    • Purple (RGB 128,0,128)—ASK
    • Orange (RGB 255,128,0)—ASSEMBLE

Flags and Comments

Fields where your template users set Advanced properties have the following field appearance:

  • All Advanced field properties indicators display as gray
  • Advanced field properties are typically shown using single-character symbols (listed below)
  • If more than one symbol is visible, they are slightly separate from the other field content, but are all adjacent to one another
  • If you configure other comments to display, the comment appears before the other symbols, also in gray color

Symbols that can appear in a field (depending on what your template users set in the Advanced Properties) follow:

  • ¢—the field contains a comment, but comments are not showing
  • •—the field contains “preserve empty paragraph”:
  • Placeholders:
    • ˘—the field contains unanswered text
    • ƒ—the field contains a font name
    • ◊—the field contains any fill/padding properties
    • For adding another template:
      • ˆ—the insert field contains “keep header”
      • ˇ—the insert field contains “keep footer”
  • For REPEATS:
    • ↑↓—the repeat field contains a sort order
    • Ω—the repeat field contains a filter

If both a repeat and sort are present, the symbols should appear in the proper sequence, according to which your template users set first.

  • For ASSEMBLEs:
    • ▫—the assemble field contains the "no interview" flag

Field Removal during Assembly

When assembling DOCX templates into documents, the HotDocs fields are removed and either completed or replaced by the data gathered in interview as appropriate. 
 

Avoid putting a paragraph marker with an associated section break directly next to a placeholder field. If the paragraph marker is removed with a HotDocs field then this may cause unexpected behavior, for example headers and footers not assembling properly.
Instead consider putting the section break on its own line, or separating the field and paragraph marker with a single space.

Common Reference Topics

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