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

Place a Dialog in the Interview (ASK Instruction)

In HotDocs Author, the ASK instruction enables you to tell HotDocs to present a dialog or variable at a certain point in the interview. The ASK instruction appears in the Field Editor as Place a Dialog in the Interview. You can also use the ASK instruction within a computation.

Overview

The ASK instruction tells HotDocs to add the selected dialog to the interview at the location you add the ASK instruction. In general, the ASK instruction tells HotDocs to display a dialog in the interview as soon as it processes the ASK instruction. There are two areas where you can use this instruction:

  • Directly in the body of a template – if your template uses a default interview, enables you to place a dialog or variable in the default interview
  • In a computation – enables you to ask any number of dialogs or variables in a series – such a computation basically defines its own interview

Common Tasks

Among others, the ASK Instruction enables you to perform the following common tasks:

Caveats with the ASK Instruction

Since (except in cases of a REPEAT dialog) It is usually an error to have the same dialog or variable appear multiple times in the same interview, HotDocs ensures that your template users can only navigate to one of instance of the same dialog or variable by placing the following restrictions on the ASK instruction:

  • If you ASK anything that is already part of the interview, HotDocs ignores the ASK instruction
  • If you ASK a variable linked to a parent dialog, HotDocs adds the parent dialog to the interview, rather than only adding the variable
  • If you ASK a dialog linked to a parent dialog, HotDocs adds the parent dialog and all its children, rather than only adding the child dialog
  • If you ASK a variable or dialog not linked to a parent dialog, HotDocs adds that component directly to the interview  – UNLESS (as described above) that component is already part of the interview; in that case, HotDocs ignores the ASK instruction

Use ASK in a Template

When you insert an ASK instruction directly in a template, the instruction can ask only one dialog or variable at a time. If you want to ask several dialogs in a specific order, you must insert individual ASK instructions for each dialog. Some template authors like this approach to adjusting or extending a template’s default interview.

Use ASK in a Computation

Some template authors prefer to group ASK instructions together by creating one computation that asks several dialogs, and then inserting just the Computation variable into the template to extend the default interview. In either case, during assembly, the dialogs appear in the interview outline in the order of the ASK instructions.

Using ASK to define a custom interview computation enables you to control the entire interview by using a series of ASK and other instructions in a single computation.

Use ASK to Create a Custom Interview

At some point, you may want to encapsulate the logic of your entire interview into one computation. To do this, you designate that computation as a custom interview for the template. Assigning a custom interview means HotDocs no longer processes the text of the template itself to define the interview; instead, HotDocs relies exclusively on the computation you specify.

If a template is extremely large or complex, encapsulating the interview logic in a custom interview computation can have performance benefits for users of the interview. Using ASK to define a custom interview computation enables you to control the entire interview by using a series of ASK and other instructions in a single computation.

Use ASK to Create a Popup Interview

Using a script link dialog element on a dialog, you can create a popup interview by calling a computation that contains ASK instructions. A popup interview is similar to a custom interview, but is typically more limited in scope (asking only specific pieces of information for some specific purpose). In addition, your template users must click a button or hyperlink during the regular interview to cause the popup interview to appear.

Implicit Versus Explicit Component Asking

By default, when HotDocs generates an interview from your template, it includes or "asks" each variable and dialog used in the template. This is not always desirable. Sometimes, you need to use a variable or a dialog without HotDocs asking it in the interview. In this case, you can clear the "Ask Automatically" option on those components you need to reference without impacting the flow of the interview.

You must of course use care; clearing ASK automatically means HotDocs never implicitly adds that component to the interview. By clearing the "Ask automatically" option, you are taking full responsibility for when (if ever) this variable or dialog appears in the interview:

  • If the variable or dialog never needs to appear in the interview, this is very straightforward. The component doesn't appear unless it's included on another dialog that does appear in the interview.
  • If you do need to ensure the variable or dialog does appear in the interview in a certain circumstance, use the ASK instruction to explicitly include the component.

Common Reference Topics

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