HotDocs Author WorkflowCreate a template Upload a template Manage components

Single Select Variables Overview

A Single Select variable is a type of variable that represents an unknown selection from a list of values (options) you define. For example, using a Single Select variable, you can present your template user with a list of the fifty states in the United States—a Single Select variable enables your template user to select only one state.

Overview

Selection variables (both Single Select and Multi Select) are unique among variables because they present a list of options that you define in an interview—in a format like you would see in a standard multiple choice test. You can create Single Select or Multi Select variables using the HotDocs Field Editor or Component Studio. Both Single Select and Multi Select variables are typically:

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

Like other components, Single Select variables have properties that you can set to define how they perform in an interview and how HotDocs processes the variable in an assembled document. For Single Select variables, the most important property is the Option source property—a required property that enables you to select the source of the options you want to present to your template user in the interview. Because Single Select variables rely on option sources, it is useful to think of Single Select variables as the component that points to a specific set of underlying data values.

reverse

Common Tasks

Among others, Single Select variables enable you to perform the following common tasks:

Workflow

When you create a template from an existing document, the existing document usually contains placeholder text for content that is unknown. When content is unknown due to it representing a selection yet to be made by the template user, you can:

  • Create new Single or Multi Select variables to represent the individual unknown selections (either in the Field Editor or Component Studio)
  • Replace all placeholder text in the template with placeholder fields that reference your variables

When you create a Single or Multi Select variable, you start by setting the name property for the Single or Multi Select variable, which is used to identify the variable throughout Author and in the answer file. You then set the Answer type property, which you use to specify whether the type of answer you intend to gather is text, number, date, true/false, or record value type. You then are required to set the required Option source property—the property that points the data that contains the options you wish to present to the template user in the interview and the values you want in the assembled document. When you set the Option source property, you can either:

  • Use the Built in option source (selected by default), which enables you to quickly add rows (and potentially additional columns) of data to use for your selection variable
  • Select an existing component to use as the option source (such as a Fixed Table, Table variable, or repeated dialog) that contains the data values you wish to use

Once you have set the Option source property and ensured the option source contains the values you need (and that they are of the type you specified in the answer type property) you should then consider the Option labels property. The Option labels property enables you to choose which column of data contains the text you wish to display to your template user in an interview. This feature is useful if your option source contains multiple columns of data, with one column containing the options you want to present in the interview but another column contains the values you want in the assembled document. For example, one column may contain the text his or hers (that you want to appear in the assembled document) and another column may contain Male or Female (that you want to appear in the interview).

With the Option source and Option labels properties set, you should then consider the rest of the component properties. For example, you can set the Prompt property to provide instructive text (as opposed to the selection variable name) to help a template user answer a question during the interview. 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). Lastly, you can then group related text (and other) variables into dialogs to improve the usability and flow of an interview.

Once you have created the selection variable and set all of the properties you need, you can use the test feature to ensure the variable will behave as you desire when the document is assembled.

In the HotDocs Field Editor, the Assembly Value property enables you to select a column other than the column you set as the key as the source of the value you want HotDocs to place into the assembled document.

Important Properties

Like all variables, Single Select variables have properties you can use to edit how the variable appears in an interview, how the variable is processed during assembly, etc. In addition to the properties common to all variables, Single Select and Multi Select variables have the following unique properties:

Answer Type and Key Type

A selection variable has an explicit answer type you set using the Answer Type property, and you must ensure the selected option source has a compatible key type, or else the selection variable is in an error state.

The Options tab contains the Answer Type property, which enables you to set the value type of the answer the selection variable produces. This property takes the form of a drop-down list that enables to choose from the four primitive value types, as well as the Record value type, which is a type that combines at least two primitive types (these can be two text values, or a text value and a date value, etc.)

To the right of the Option Source, (and directly below the Single Select or Multi Select variables's Answer Type, the Key type of the selected option source appears. Just as with the Answer Type property, the available Key Type values are either text, number, date, true/false, or record. If the key type is undefined/indeterminate, for example if you did not select a key for the option source's key type, or the indicated option source does not yet exist, the Key Type is empty.

For Multi Select variables, appropriate Answer Type and Key Types include Text List, Number List, Date List, True/False List, and Record List respectively.

As you edit the selection variable, HotDocs checks the value of the Key Type of the currently selected option source against the value of the currently selected Answer Type.

  • If the types are compatible, there's no problem, if the types are incompatible, an error message appears immediately below the key type informing you that the key type of the selected option source is not compatible with the selected answer type.
  • If the key type is blank/indeterminate (due to an error), the validation message indicates that a key type could not be determined for the selected option source; the user should edit the option source to fix that problem.

There is a read-only Answer Type property in the upper-right corner of all other variable editors: Text Variable, Number Variable, Date Variable, True/False Variable, Table Variable.

 

When opening existing templates, if this property is not set, HotDocs assumes the Answer Type is Text.

Types of Option Sources

You can choose from four types of option sources for your Single Select variables, with each type being useful for different situations:

  • Built-in table – enables you to add rows (and potentially additional columns) of known data to a particular selection variable—without the need to create or point to another component. A built-in option source is selected by default when you create a new selection variable and is most useful for making quick, simple, text-based option sources.
  • Fixed Table component – enables you to create and columns and rows of known data that lends itself to organization in a tabular format. A Fixed Table is most useful for when you need to create complex rows and columns of data that contain text, number, and all other forms of data, when you need to use that data with any number of Single Select variables, and when you need the ability to refer to the values or expressions defined in individual table cells in scripting and expressions.

    this might not be the best example for best use case for fixed table components...

  • Table variable – enables you to present a table (with columns you define) in an interview for the purpose of collecting values you do not know from the template user by enabling them to type values (of a type you specify) into the rows of the table. Table variables are useful as option sources when you need to collect lists of data from your template user and then later present that same data to the template user as a list of options to choose from. For example, you could use a Table variable to have the template user enters the names, birthdates, and addresses of their children into one table early in the interview, and later on in that same interview, have the template user choose a child from that list to be the executor of an estate).

  • Repeated dialog – enables you to gather data whose values you do not yet know (you gather this info from your template users in the interview); also enables you to designate one or more variables on your dialog as a key to ensure your template users provide unique values for each "row" of data they provide

When to Use Single Select Variables

To better understand when to use a Single Select variable (as opposed to the other types of variables), consider the following:

  • A Single Select variable is required when you want to present a list of options (such as a list of marital statuses) in an interview and you want the template user to only be able to make one selection.
  • If you want to enable the template user to make multiple selections from a list of options, you would use a Multi Select variable.
  • If you want to ask your template user a simple Yes or No question, you could consider using a True/False variable.

Single Select Variables and Formats

When working with Single Select variables, there are times when you may want to control how a template user's answer to an interview question is displayed in an assembled document. For example, you may want options that are presented to the template user with capitalization (e.g. Bob Smith) to appear in the assembled document in all capitals (e.g. BOB SMITH). HotDocs enables you to make such modifications to answers based on Single Select variables using text formats. To assist you in using text formats, HotDocs provides a set of commonly used text formats (such as formats that enable you to use all caps, all lowercase, and more) when you install Author.

You can either format a single instance of the placeholder field that references the variable, or you can format every placeholder field that references that variable throughout the template. You can also create your own custom format, should you need a format not included in the commonly used formats.

For more information on formats, you can read the formats overview and the Formatting an Answer document for more information.

Restrictions on column names

When using a Built-in table, you cannot name a column with a whitespace character, for example a space, as the first or second character.

Selection Variables and Scripting

As with other variables, you can access Single Select variables in the HotDocs scripting language using literals. You can also use various instructions, functions, and operators with Single Select variables.

Scripting Aids

As with other components, HotDocs provides an auto-complete feature on the Script tab that provides an alphabetized drop-down list of items you can choose from to complete a script statement HotDocs suggests these items as you type. There is also a Component Studio keyboard short cut (CTRL + SPACEBAR) to help you choose values for Single Select variables.

Selection Variables and Dot Operators

In HotDocs scripting language syntax, the dot operator enables you to access the entries in a real, or in a "conceptual record" (a row of data). For example, when you want HotDocs to place text in the assembled document other than the template user's answer to a question posed by a selection variable, you use a dot operator. The dot operator is a syntactic shortcut to accessing a value in an option source. This takes the form of SelectionVar.Name; this is a shortcut for accessing the underlying option source (say a Table component). The above then translates to TableComp.ColumnName.

For example, suppose you want to present the template user with a list of state abbreviations to choose from, but you want HotDocs to place the full state name in the assembled document. This first requires you to create a Table component with columns for, and data containing both the abbreviations and the full state names. Next, you create a Selection variable (being sure to select the state abbreviation column as the Option Labels). You then locate in the template the location where you want HotDocs to place the full state name during assembly and add your placeholder field using the HotDocs Field Editor. In the field properties box, under X, select or type the name of the State Name Selection variable, and press the period key (which in this context is the dot operator) to display the column names of the state name Fixed Table component. Your selection of (for example) US States.Full Name instructs HotDocs to present the US States Selection variable to your template users in the interview (where the display column containing the state abbreviations appears), but at assembly, to replace the placeholder field with the value from the Full Name column.

Supported Instructions

Selection variables support the following instructions and functions in the HotDocs scripting language:

Dialog Scripting Instructions

Selection variables also support the following dialog scripting instructions:

SET Function Considerations

At the time of the SET or DEFAULT, HotDocs looks up each item in the option source. Only if the item is present in the option source does HotDocs assign that value as the answer. For example, if you SET SelectListVar TO {"a", "b", "c"}, but SelectListVar's Option Source only defines "a", "c" and "d" as options, then the answer excludes b, and the answer becomes {"a","c"}

SELECTION Function

You can use the SELECTION function with Multi Select variables, as in the following:

IF SELECTION (SelectListVar, 2) = "Option 2"

Then do something

END

Operators

You can use the operators = and != to compare either Single Select or Multi Select variables. You can also use the + operator to concatenate the values of one Single Select variable or one Multi Select variable to another one.

Common Reference Topics

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