HotDocs Author WorkflowCreate a template Upload a template Manage components

Table Variable Overview

A table variable is a type of variable that represents one or more rows of unknown values arranged into columns whose names and types you define. For example, when you add a table variable to a dialog, a template user can add as many rows to the table as they need to hold the data they supply.

Overview

A table variable enables you to gather data that lends itself to organization in columns and rows. You can add a table variable to a dialog, including a repeated dialog. When you add a table variable to a non-repeated dialog, your template user can add as many rows of answers to the table as they need (similar to the behavior in a spreadsheet dialog on a parent repeated dialog). HotDocs stores that data as a Record List value in the answer set. When you add a table variable to a repeated dialog, your template user can answer the questions the table variable represents as many times as needed, adding tables as needed, and as many rows to each table as they want. HotDocs stores this data in the answer set as a list of record list values.

Table Variables as Option Sources

Similar to a fixed table component, you can also use a table variable as an option source for a selection variable. With a table variable, however, you only define the columns, while your template user supplies the rows of data during the interview. Once your template user supplies the row data for a table variable, you can use a selection variable to present a choice of that data to your template user.

Table variables enable you to create multiple columns that specify what type of values (e.g., text, number, date, etc.) each column can contain. You can also specify one or more columns you want to act as a row identifier (a key). It is best practice to specify a single column as a key, since this makes it easier for you to access your data from a Selection variable. If you need to specify more than one column as a key (because no single column is sufficient to ensure that the data in each row of your table is unique e.g. Last Name), you will be required to select only one column as the value that will appear in the assembled document (see assembly value).

Common Tasks

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

Workflow

While you can create table variables from the HotDocs Field Editor, the extra screen space in the Table Variable Editor is particularly useful when creating columns for your table variable. You open the Table Variable Editor from Component Studio by creating a table variable, or selecting an existing table variable, or you can click the Table Variable Editor button in the HotDocs Field Editor.

When you create your table variable, you name your columns and specify the type of data you want each column to contain, and finally, designate one or more columns as row keys. If you want to use your table variable as an option source for a selection variable, when you finish defining your table, you need to create a selection variable, and choose your table variable as the option source for the selection variable.

Table Columns

When you create a table variable, you must define the columns you want your table variable to display to the user. You must to provide the following information for each column:

  • Key  —  set the column as being part of the table's key; the key is the data that uniquely identifies a row in the table
  • Type — you choose the type of the value each column can accept as an answer by selecting one of the following types from the drop-down:
  • Name — a unique name for the column
  • Optional — if you set a column to be optional, the interview will not prompt users to complete any fields in the column they leave unanswered

Composite Keys

You may set more than one column set as a key. Keys that use multiple columns are known as composite keys. The values a user enters for the columns in a composite key must be unique in aggregate; individual columns may have the same value. For example, suppose you have a composite key made up of the text columns Name and Department. A user may enter John Smith and Sales for one row, and John Smith and Human Resources in another row. However, the user could not enter John Smith and Sales in a subsequent row, as this value has already been used, and the combined Name and Department value must be unique.

Data Rows

In an interview, the table variable displays the columns you defined to the user. The user can then add as many rows as they require, adding answers as appropriate to each column in the row.

Table Variables and Lists

Because a table variable has columns, by its nature it lends itself to gathering data that you can then tell HotDocs to add as a list during document assembly. To do this, once you define the table and its columns, you add a placeholder field that references an expression; then type the word LIST at the beginning of the expression, followed by the name of the table variable, a dot, and then the name of the column whose values you want to use as the answer. If you want to format the individual items in the list, you then type a colon, followed by a format example. If you want to format the list itself, you follow this with another colon, and then the list format you want to use, as in the following example for a table variable where you want to build a list based on a column that collects answers that are text values:

LIST TableTest.Third:LIKE THIS:a, b, and c

If you were gathering a list of names in the Third column of this table, HotDocs would add the names to the final document as follows:

JASON PARTRIDGE, PHILIPPA STOUT, HENRIETTA MORGAN, FELIX MARKS, and PATRICK ANDERSON

If you want to, you can create your own formats, both for lists and for the individual items in the list.

Table Variables and Scripting

As with other variables, to access table variables in the HotDocs scripting language, using you need to use the proper syntax. This means that when you reference data values in a script, you need to use a literal value.

Table Variables and Dot Operators

The table variable name, followed by the dot operator, and a column name, "projects" thus evaluates to a list of values of the type of that column, for example: TableName.ColumnName.

CLEAR Instruction

The CLEAR instruction can be used with a table variable reference to remove all currently defined record values in the table's answer. if the table is repeated, and the CLEAR instruction occurs within an appropriate repeat context, CLEAR clears only the list in the appropriate repeat slot.

ADD Instruction

The ADD instruction can be used with a table variable to append a single record value to the table's answer (or, if repeated, the answer for the current repeat index). The specific value added can be any expression that results in a record value, which must contain at least the key columns designated for the table, but may also contain values for any other columns defined in the table.

If you attempt to ADD a record with a duplicate key, the result is that nothing happens – nothing is added.

SET and DEFAULT Instructions

The SET and DEFAULT instructions can be used with a table variable reference to replace the (entire) answer for that table with something else. In doing so, standard record semantics (as previously discussed and implemented) apply.

ERASE Instruction

The ERASE instruction can be used with a table variable reference to erase all answers for that table variable, including repeated answers.

Common Reference Topics

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