The HIDE, CONCEAL, and OMIT instructions are used to manipulate variables in a dialog script, particularly variables that are used in answer sources (or pick lists).

The following table shows how HIDE, CONCEAL, and OMIT instructions are treated in various contexts, followed by an explanation of why these instructions work the way they do:

Just as a database table is a collection of records, with each record containing data for one or more fields, an answer source (also known as a pick list answer file) is a collection of answer groups, with each group containing answers to one or more variables.

One example of an answer group might be the name, phone number, and street address of an individual. These are three independent answers, but they are grouped because they all relate to the same person. The following table shows three groups of answers saved in an answer source:

Suppose a template developer wants to use this sample answer source to let users select answers in a template. The users must provide the name, phone number, and committee role of each person on a committee. The developer wants the dialog that gathers this information to look like this:

Suppose further that the developer has decided to list only names—not phone numbers, or street addresses—in the Select from Answer Source dialog. To accomplish these objectives, the developer must create a dialog that includes all the variables (Name Variable, Phone Variable, Street Variable, and Role Variable), and includes the following script:

  CONCEAL Phone Variable
  HIDE Street Variable
  CONCEAL Street Variable
  OMIT Role Variable

Why does the developer CONCEAL Phone Variable in the dialog script? Because the developer wants Phone Variable to show up in the dialog, but not in the Select from Answer Source dialog. That is the purpose of CONCEAL.

Why does the developer HIDE Street Variable in the dialog script? In fact, why is Street Variable included in the dialog at all if it isn't going to be displayed? Because the Edit Answer Source dialog box must include all variables associated with the answer source being edited. And the only way HotDocs knows which variables make up an answer group is by seeing them in the original dialog. (See the following explanation about including the Street Variable variable.)

Finally, why does the developer OMIT Role Variable in the dialog script? Because, although Role Variable appears in the dialog, it is not part of the answer group at all (therefore, the user must type in each person's role). OMIT identifies this fact and keeps Role Variable from appearing in either the Select from Answer Source dialog or the Edit Answer Source dialog.

Why Street Variable must be included

To illustrate the problem that would occur if the Street Variable variable were not included on the dialog, assume the answer source shown above is presented during the interview, but Street Variable is left off (it is italicized below to represent this).

Now suppose the user inserts a new row between Sally Jones and Elvira Lemon. Because Street Variable is not included in the Edit Answer Source dialog box, HotDocs doesn't know it is part of the answer group. So when the insert happens, HotDocs inserts space for only the two included variables:

Later, when the answer source is used in other templates that do use Street Variable, the variables won't be matched up correctly.