Variables Overview

A variable is a type of component that represents an unknown value; you can define how to gather that value from a template user, how HotDocs stores that value as an answer, and the format HotDocs gives that answer when assembling a document. For example, if you want to ask a template user for a date of birth, you would create a Date variable in your template to capture that specific type of data; you can also set format properties on that variable that tell HotDocs to place that date in your assembled document in a numerical format, or you can format a date answer as text.

Overview

In HotDocs, the term variable acts as an umbrella term to describe components you create to represent unknown content in your template (i.e. the values yet to be entered by the template user or computed by a computation). You can create variables using the HotDocs Field Editor or Component Studio. Variables are typically:

Referenced in a template by adding a placeholder field, indicating where HotDocs must place the variable's answer value in the assembled document
Added to a dialog, so the variable's question appears in the interview
Used in a computation to supply an item of data used by the computation's script

There are several types of variables, each designed to capture values of different types from the template user during an interview:

Variable Type	Description	Example Value
Text variable	Represents an unknown text value, such as a client name or business address.	85 South Street, Hobble Creek, Utah
Number variable	Represents an unknown number value, such as currency, decimal numbers, or other amounts that can be calculated.	23.50
Date variable	Represents an unknown date value, such as a birth or loan commencement date.	05/05/1990
True/False variable	Represents an unknown true/false value, such as the answer to a yes or no question (and often used when creating a conditional region).	True
Single Select variable	Represents a single unknown selection from a list of values (options).	Female
Multi Select variable	Represents one or more unknown selections from a list of values (options).	California, Utah, and Georgia
Table variable	Represents one or more rows of unknown values arranged into columns whose names and types you define.	John Smith, 555-55-5555, Father Jane Smith, 555-55-5554, Mother
Image variable	Represents an unknown image, to be uploaded to Advance by a user in interview.	image.jpg, image.png

In addition, there are also local variables, a specific kind of variable you can create when using HotDocs scripting to add additional functionality to a computation or dialog. Local variables can be either text, number, date, or True/false type, and are called "local" to indicate their purpose, which is to represent an unknown value pertinent only within computation or dialog script.

Like other components, variables contain properties that you can set to define how they perform in your template and are grouped together throughout the Author interface. You can review these properties below.

Common Tasks

Among others, variables enable you to accomplish the following common tasks:

Workflow

When you create a template from an existing document, the existing document usually contains placeholder text for the content that is unknown. To enable template users to provide the values for this unknown content (or to compute it using a computation), you:

Create new variables
Replace all placeholder text in the template with placeholder fields that reference your variables.

You can create a variable in Component Studio or when adding a placeholder using the HotDocs Field Editor. Whichever method you use to create a variable, you can set properties to define how they perform in your template. For example, you start by setting the Name property for the variable, which is used to identify the variable throughout Author (and also in the answer file). You can then set as many properties as you need, for example:

You can set the Prompt property to provide instructive text to help a template user answer a question during the interview (without this property set, the interview uses the variable name as the instructive text)
You can set the Default format property to define the pattern that HotDocs uses to format the template user's answer in the assembled document (such as all caps).

Once you have set all of the variable properties you need, you can also group related variables into dialogs to ask multiple interview questions at once and to otherwise improve the usability and flow of an interview. Lastly, you need to ensure that you have added placeholder fields in your template that reference the variables you created and edited (and that they are in the correct locations in your template and are referencing the correct variables).

At any stage during variable creation or editing, you can use the test feature to ensure the variables you create will behave as you desire when the document is assembled.

Variable Properties

As mentioned above, every variable has properties that you can set to define how they perform in your template. You can edit these properties in Component Studio (and in the pop-up variable editors you can open from the Field Editor). In these editors, similar properties are grouped together and (in many cases) organized into tabs. For example, all variables types have the following property groups:

Variable Property Group	Property Group Purpose	Variable Editor Location
Component identity properties	Enables you to define how the variable is identified when authoring a template (such as the Name and Option source properties).	Top of Variable Editor
Display	Enables you to define how the variable appears to the template user during the interview (such as the Prompt property and Style on regular dialogs properties).	Display Tab
Behavior	Enables you to define how the variable behaves during the interview and how HotDocs processes the variable during document assembly (such as the Warn When Unanswered and Default format properties).	Behavior Tab
Notes	Enables you to define how you want to remind yourself about the component and its role in the template (the Notes property).	Notes Tab
Additional information	Enables you to provide information (text or URL) to help template users better understand or to give directions for how to answer a question in an interview (the Additional information property).	Bottom of Variable Editor

Variable Types and Their Properties

The variable properties that you can set depend on the variable type. For example, a Number variable has a display decimal place property while other types of variables do not. To learn about each variable type's unique properties see the following individual variable component editor topics:

Unique Name

You must give a variable a unique name within the template: variables in the same component file cannot have the same name, even if their variable types differ. This is because HotDocs uses the variable name to identify individual variables when generating an interview or assembling a document.

The Relationship Between a Variable and a Placeholder Field

Because variables and placeholder fields work so closely to accomplish the purpose of your template (and because both have their own set of similar properties), it can be easy to confuse variables and placeholder fields. To better understand how variables and placeholder fields interact, consider the following:

A variable is the component you create to gather answers from a template user in an interview. In addition, variables have properties you can set that define how they perform in your template. However, neither the variable itself nor any of its properties contain information about where in the document a value should be placed. To determine where a value should be placed in an assembled document, you use a placeholder field.
A placeholder field is a type of HotDocs field you add to a template that defines where HotDocs should place an answer within a document and to define which component HotDocs should refer to when generating an interview and assembling a document. In addition, placeholder fields also have field properties you can set that define how the components they refer to perform in your template. For example, you can set the default format property of a Text variable in order to capitalize all of the characters in the template user's answer. However, there may be a specific instance in your template where you wish to override the variable property. You can accomplish this by using the Field Editor to set the format field property for the specific placeholder field.

Single Variable, Multiple Placeholder Fields

You can refer to a single variable any number of times using any number of placeholder fields. For example, assume you have created a template from a document where an employee's full name is needed in five different locations. To accomplish this, you only need to create one single variable, EmployeeFullName. Once the variable is created, you then add placeholder fields in each of the five locations you want to reference the EmployeeFullName variable. There is no need to create different variables for each instance of the employee's full name and, using field properties, you can still use the same variable even when you need to the employee full name to display differently in each location. For example, by setting the format property at the field level, you can format the EmployeeFullName variable in all caps in one location, have the name display in the assembled document exactly as entered by the template user in the interview in another location, and more.

Variables, Values, Answers, and Answer Types - A Technical Perspective

To better understand variables (and HotDocs in general) it is useful to know the technical relationship between variables, values, and answers. For example, a value is a piece of data of a type that HotDocs knows how to process, a variable is a component you can use to collect a value from template user, and an answer is a value that HotDocs stores for later use. Since you do not know (in most cases) what values your template user will enter in during an interview, variables are said to represent unknown values. However, once a template user types their response to an interview question, their answer (now considered an answer value) becomes associated with the variable. Variables, values, and answers are also related in the following ways:

A variable defines what type of value your template users can enter in response to an interview question and therefore defines what type of answer is stored for later use (for example, a Text variable enables a template user to enter text values)
You can create a Multi Select variable (or place variables on a repeated dialog) to enable template users to enter more than one answer to the same question in an interview
Various variable properties affect values, answers (such as formats), or both (such as an input mask).
Answers (as they are stored in the answer set) are technically a name/value pair—with the variable name representing the name and the answer provided by a template user being the value in the pairing.
Each variable has a property called Answer Type that tells you exactly what type of value the variable accepts. This property is "read only" for the four basic variables (Text, Number, Date, True/False), plus the Table variable. You can set this property for Single Select or Multi Select variables, since their Answer Type must accord with the Key Type of their current option source.

Variables and Formats

You can also use variables to control how an interview's answer is displayed in an assembled document, regardless of how the template user originally typed the answer. You can achieve this by setting a variable property—the Default format property. When you set a default format for a variable, HotDocs sets the format for every placeholder field that references that variable throughout the template. To assist you in using formats, HotDocs provides a set of commonly used formats when you install Author (which you can manage in Workspace Explorer > Options > My Formats). Should you need a format not included in the commonly used formats, you can create your own custom format.

You can also set the format for an individual placeholder field using the HotDocs Field Editor (doing so overrides any default format you set). See Formatting an Answer for more information.

Variable Name, Title, and Prompt Properties

Each variable has display properties that specify the text used to identify the variable in the interview. These are the Name, Title, and Prompt properties you see when editing a variable in Component Studio. Each property displays text in a different location in the interview. For example, the prompt text typically appears next to the variable's answer text box; the title text typically appears in the answer summary. See Component Type and the Presentation of Prompts, Titles and Names in HotDocs Interviews for more information.

Variable Dictionary

If you want to ensure consistent naming of HotDocs variables across your set of HotDocs templates, you can create a variable dictionary. This is a file you create that describes a common set of variable names you can use when creating HotDocs variables. When using a variable dictionary, Author suggests common variable names to template authors in the Field Editor. Variable dictionaries do not restrict the variable names that template authors may use in a template; authors can still name variables however they want. See HotDocs Variable Dictionary Overview for more information.

Common Reference Topics

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