Option Sources Overview

An option source is any set of data a selection variable can use to display a list of options; you enable a selection variable to display that data by setting a key on the data set, then using the selection variable's Option Source property to point to that data. For example, to make a Fixed Table component available as an option source, you mark at least one column as a key, then in either a Single Select or Multi Select variable, you use the Option Source property to choose that Fixed Table component as the source of the options the selection variable presents to your template user.

Overview

An option source is a tabular data structure you can associate with a selection variable by designating at least one column in the table as a key that uniquely identifies the contents of each row; by default, this column's contents populates the selection variable's Option List. When you create a new selection variable the default option source for that selection variable is a Built-in Table (included as part of the selection variable). If this default option source does not provide all the capabilities you need in an option source, you can use one of the following types of tabular data structures as an option source:

It is possible (but not desirable) to choose an option source that refers back to the selection variable from which you are choosing an option source. For example, if you choose a repeated dialog as an option source, and that dialog contains the selection variable you want your template user to choose an option from, this results in an error condition.

Common Tasks

Among others, an option source enables or informs the following common tasks:

Workflow

You create an option source by creating any of the component types listed above as option sources. Once you've created the component, you need to mark at least one column in that component as a key. This key ensures that each row of data in the component contains uniquely identifiable data. The component now exists as a fully potentiated option source. All that is needed thereafter is to create a selection variable that points at that component using the Option Source property of the selection variable in question. Alternatively, simply create a selection variable and use the default option source it contains.

Types of Option Sources

There are two types of option sources you can point to with a selection variable:

Direct option sources
Indirect option sources

Direct Option Sources

Direct option sources are those where you know what the data is before your user runs the interview. Direct option sources include:

Built-in tables – A simpler form of a Fixed Table component that only allows you to create columns of text-based data that is the default option source in a selection variable and is included as part of the selection variable
Fixed Table components
Table Variables (when you add a known set of data to your table using a script)

In the case of Fixed Table components, you create the data directly in the component file of the template as you build your template.

Indirect Option Sources

Indirect option sources are those you where you do not control or know the data available before running the interview. Indirect option sources include:

Table variables (when your template user provides all the data during the interview)
Repeated Dialogs (with Row ID)
External data sets (e.g., data that comes from a third-party database during the interview)

Built in Tables

Built in tables are simpler forms of a Fixed Table component where all columns are of type text. When you create a selection variable, its default option source is a Built in Table. If you create a selection variable from the Field Editor, the Built in Table appears in-line as a single column called Key.

As with all option sources, this Key column requires that contents of this column must be unique for each row in the table. The Key column therefore ensures that at least one cell on each row contains unique content that HotDocs can use to identify each row.

In addition, the Key column enables you to type the values you want as possible answers for your selection variable. Unless you use the Option Labels property in Component Studio to choose another column to display to your template user in the interview, the values you type in the Key column also become the list of options that appear in the interview. Likewise, unless you use the Assembly Column property in the HotDocs Field Editor to designate another column as the one whose values you want HotDocs to replace the placeholder field with during document assembly, HotDocs replaces the placeholder field for the selection variable with the appropriate value from the Key column during document assembly.

Built in Table Example Use Case

Suppose you want to ask your template user for their gender. When you create your selection variable (Gender), HotDocs provides you with a Built in Table. In the first row, you type Male; then you immediately add another row and type Female. If you Test this selection variable, you can see that your user can now choose from a drop-down list that contains Male and Female. If you test your entire template, you can see that the value that replaces the placeholder field pointing to the selection variable gets replaced with whichever gender term you choose in the interview.

But, what if you really want to ask your template user if their child is a Boy or a Girl (but you still want the answer to be Male or Female for your purposes in the template)? Not a problem. If you need to present values in the interview different from those you need to place into your assembled document you can click the Edit button to the right of the Variable field in the Field Editor. From the editor, you click the Add Column button; then in this column, in the first row type Boy and in the second row, type Girl. You then use the Option Label property in the Display tab to designate the second column as the one you want to present to your template users.

In like manner, you can add another column containing his in the first row and hers in the second, then use the Assembly Column property in the Field Editor to choose the third column as the one you want HotDocs to use for replacing the placeholder field with during document assembly.

To do this kind of thing yourself, open the lesson on gender pronouns in the Author tutorials.

Option Sources and Keys

Because every option source corresponds to a table of data, the data in an option source is organized in columns and rows. A selection variable presents one of the column names as the title of the list of options (the rows for that column) it displays to the template user in the interview. In order to point to a specific row's contents within a column, the selection variable depends upon keys to uniquely identify each row in the option source.

Keys

A key is a value in a row of an option source that uniquely identifies that row/option within the option source and provides the answer for any selection variable where that option is chosen; a key can be a value in a single column or a composite value that spans multiple columns. For example, for an option source that is a table containing a list of employees with columns for First Name, Last Name, Birthdate, Start Date, Salary, and Employee Number, the column of values that most easily works as keys to uniquely identify an employee would be the Employee Number. If the table lacked that column, you might choose to create a composite key by flagging the First Name, Last Name, and Birthdate as key columns. Taken together, the values from these columns could act as keys to uniquely identify each row of data to return individual employees.

There are two types of keys you can create in an option source:

a simple key (you designate only a single column as the key)
a composite key (you designate more than one column as a key)

When using a composite key, you must ensure that at least one key is not optional, otherwise, an error results, as there would be no way for HotDocs to ensure the uniqueness of the data you want it to use to act as a key.

When you work with an option source, if possible, you should mark only a single column as a key to establish uniqueness. This makes your answer unambiguously readable and concrete. A key defines the answer to a selection variable. Because the value is the key, a single column as a key returns a more concise value. This leads to "data integrity," or more concretely unique data.

Of course, when you use an indirect option source, you do not control what the key or keys associated with that data is. You define the columns that exist in the answer – you must make at least one of these a key column.

Common Reference Topics

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