HotDocs Author WorkflowCreate a template Upload a template Manage components

Multi Select Variable Overview

A Multi Select variable is a type of variable that represents an unknown selection or selections from a list of values (options) you define. For example, using a Multi Select variable, you can present your template user with a list of the fifty states in the United States—a Multi Select variable enables your template user to select one or more states (or alternatively, to choose None of the Above).

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 a Multi Select variables using the HotDocs Field Editor or Component Studio. You typically use a Multi Select variable by:

  • Referencing it in a template by adding a placeholder field, indicating where HotDocs must place the Multi Select variable's answer value in the assembled document
  • Adding it to a dialog, so the Multi Select variable's question appears in the interview
  • Using it in a computation to supply an item of data used by the computation's script

Like other components, Multi 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 a Multi Select variable, 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 Multi Select variables rely on option sources, it is useful to think of a Multi Select variable as the component that points to a specific set of underlying data values.

reverse

Common Tasks

Among others, Multi 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 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 Multi Select variable, you start by setting the Name property for the 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 (which is 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 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.

Selection Variable Properties

Like all variables, Multi 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 variable'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 or Multi 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 or Multi 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 Multi Select Variables

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

  • A Multi Select variable is required when you want to present a list of options (such as a list of loans you wish to apply for) in an interview and you want the template user to only be able to make one or more selections.
  • With a Multi Select variable, you can set a property to easily provide a None of the Above option, in addition to the list of options provided in the option source.
  • If you want to require the template user to make just one selection from a list of options, you would use a Single Select variable.

Multi Select Variables and Formats

When working with Multi Select variables, there are times when you may want to control how the template user's answers to an interview question based on a Multi Select variables is displayed in an assembled document. For example, assume you have a question in an interview that presents a list of options your template user can choose from (e.g. a list of fruits) and you want their selections to be comma separated in the assembled document (e.g. Apples, Bananas, and Cherries) and your template user chooses three of their favorites. You can use the list format a, b, and c to enable a template user's selection (or entry) of apples bananas cherries in an interview to display as apples, bananas, and cherries in the assembled document. HotDocs enables you to make such modifications to answers based on Single Select variables using list formats. To assist you in using list formats, HotDocs provides a set of commonly used list formats (such as formats that enable you to separate the selections with and or or, use the oxford comma, 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.

Multi Select Variables and Scripting

As with Single Select variables, the answers a Multi Select variable stores in the answer file are the keys defined in an option source. HotDocs stores the answers as a list of keys that correspond to one of the following types:

  • Text
  • Number
  • Date
  • True/False

If a template user chooses None of the Above, in the interview, HotDocs also stores that answer as a list value (NOT an _unanswered _value); however, the list contains zero items, expressing "answered, however nothing was selected."

Multi Select Variables and Record Values

Just as with Single Select variables, the answers gathered by Multi Select variables are the names of the columns in your option source that act as keys to uniquely identify the rows in your option source. Since Multi Select variables enable your template users to choose more than a single option, HotDocs needs to store multiple keys as a single answer value. HotDocs does this by storing the keys in the answer as a single record value. A record value represents a row of data such as that you find in a table. If your template user only chooses a single answer, the answer gets stored as a row containing a single cell.

Multi Select Variables and Scripting

As with other variables, you can access Single Select or Multi Select variables in the HotDocs scripting language using literals. You can also use various instructions, functions, and operators with Multi 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 Multi Select variables.

Multi Select 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: