HotDocs Author WorkflowCreate a template Add placeholders Group variables in dialogs Create regions and rules Customize an interview Upload a template

Dialogs Overview

A dialog is a HotDocs component that makes other components (usually variables) visible in an interview; you can group related variables together on a single dialog to improve an interview's usability and flow. For example, in an interview that asks variables such as Employee Name, Address, Job Title, Job Description, etc., rather than presenting these variables one at a time on several dialogs, or together with other unrelated variables, you can group all these related variables on a single dialog to make the order of questions in the interview more logical and the resulting interview easier for your template user to navigate.  

Overview

A dialog is the principal visual element of a HotDocs interview (i.e., it is the visual interface for the interview questions). When HotDocs generates an interview, by default, it auto-generates a dialog for each variable in your interview. Such auto-generated dialogs are basic and present only a single variable at a time. Also by default, HotDocs presents the variable as an implicit question, based on the name of the variable: e.g., First Name. If you create a template with several variables, your interview can seem tedious to your template user as they must navigate, one at a time through as many dialogs as there are variables. To solve this problem, HotDocs enables you to create custom dialogs, and to group variables that gather related data onto a common dialog. This reduces the number of dialogs and also makes the interview content and questions flow smoother.

Because the dialogs you create are also HotDocs components, they have properties that enable you to control how they behave. You can also affect a dialog's behavior in the interview by creating dialog scripts that enable you to do things such as hide a variable until a user answers a question that makes that variable relevant. Dialogs have other features (such as the concepts of parent and child dialogs and repeated dialogs), that not only enable you to present a visual interface to your template users, they also affect the structure of how HotDocs stores the data (answers) your template users provide.

Common Tasks

Among others, HotDocs enables you to perform the following common dialog-oriented tasks:

Workflow

Although you can create a dialog in the Field Editor at the same time you are creating related variables, you typically create a dialog in Component Studio after you finish creating your variables. Once you create your dialog, you then add variables to it. After you add the variables to the dialog, you can customize your dialogs's appearance and behavior by changing the layout of variables, adjusting any of the dialog's properties, or adding dialog elements. If you are using a custom interview, you add an ASK instruction to your interview computation to control when each of your dialogs appears in the interview.

Custom Dialogs

Creating a custom dialog enables you to group related variables together and design the look and feel of the interview. When HotDocs generates an interview from your template, it reads through the template and displays dialogs based on the order it encounters variables and dialogs in the template, as well as instructions and other logical elements. If you want your dialogs to appear in a different order than the order they appear in your template—for instance, if you want a certain dialog to appear first, even though variables that prompt HotDocs to present the dialog appear at the end of the template—you can use an ASK instruction to force HotDocs to display the dialog earlier.

Linked and Unlinked Dialogs

Custom dialogs also enable you to take advantage of the difference between “linked” and “unlinked” dialog behavior.

Linked Dialogs

All dialogs in HotDocs Author are “linked” dialogs by default. This means that by default, the Link Contents to this Dialog property is selected on the Behavior tab of the Dialog Editor in Component Studio. This property tells HotDocs that if this dialog appears in the interview, it must present all the variables you group on this dialog at the same time. Likewise, if the dialog has a child dialog, HotDocs presents the child dialog at this point in the interview. This property exists to make it easier for you to group related variables together so the interview presents related questions in a logical sequence. To enable this, when you create a variable in the Field Editor, you can choose to reference a linked dialog (by choosing a linked dialog from a drop-down list, or typing a new dialog name, and then clicking Create and Link). If you choose to reference a linked dialog, you instruct HotDocs to display that variable at the time the dialog linking to that variable appears in the interview. This means that no matter where in the template you create related variables, by choosing the same linked dialog, you ensure these variables get asked in the interview together. You can further choose the order in which these variables appear by arranging them using the Layout tab of the Dialog Editor.

Limitations

You can only assign a variable to one linked dialog per interview. Also, you cannot cause HotDocs to present that variable in the interview on its own (outside the context of another custom dialog). You can, however, assign a variable to both a linked and an unlinked dialog (though the potential complexities of such a scenario make it something you may want to avoid).

The list of Available Components (visible from the Contents or Layout tabs of the Dialog Editor) helps you keep track of which components you already assigned to a linked dialog and which are available for you to assign to the dialog you’re currently editing. This list can help you avoid unintentionally assigning a variable to a different linked dialog (doing so means the first linked dialog stops referencing the variable).

Unlinked Dialogs

An “unlinked” dialog is one where you choose to deselect the Link Contents to this Dialog property. If you do this, asking a variable from that dialog does not invoke the entire dialog (thus causing the other variables on that dialog (together with any child dialogs) to appear in the interview at that time). If you want to invoke the entire dialog you must you must add an ASK instruction at in the template to tell HotDocs to display that dialog. Invoking the dialog then causes all the other variables on that dialog to appear in the interview.

Uses

An unlinked dialog can prove useful if you want to include a variable in more than one dialog.

You can only cause HotDocs to display a variable in the interview one time. Assigning a dialog to both a linked and an unlinked dialog means that whichever dialog you ask first in the interview displays that variable. This can lead to unintended consequences, so use this capability with caution.

For example, you may want to include a variable in multiple dialogs so that you can have different versions of a dialog that appear based on how your template users answer a given interview question.

You can see if a particular component is associated with a linked or unlinked dialog by opening that component’s editor in Component Studio and checking the Info tab located on the Tools pane of the Dialog Editor.

Parent Versus Child Dialogs

Use a Dialog to Display Only Dialog Element Text

You can create a dialog that contains text only and no variables. You should be aware of some constraints on doing this, however.

If you want the dialog to appear during the interview, you must add an ASK instruction in the template where you want HotDocs to ask the dialog.

HotDocs considers a dialog with only dialog element text as answered, so if a user navigates through the interview using the Next button, HotDocs skips such a dialog. To force HotDocs to display a dialog, on the Behavior tab, select the Always stop option. This causes HotDocs to stop at this dialog when the user clicks the Next button.

Common Reference Topics

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