Conditional Region Overview

A conditional region is a set of instructions that tells HotDocs whether to include or exclude certain blocks of text from the assembled document, depending on how a user answers the questions in the interview. For example, you could mark a clause paragraph in your template as a conditional region, so that HotDocs will only include it in the assembled document if a user answers Yes to a specific true/false question.

Overview

A conditional region tells HotDocs that a condition must be met before a specific block of text is included in the assembled document. If the condition is not met, the text is not included in the assembled document. For example, suppose in an estate planning document there is a paragraph that lists children who will inherit parts of the client's estate. In the case of a client with no children, you can exclude the paragraph by putting a conditional region around that paragraph. Then, use a true/false interview question about the client's number of children ("Does the client have children?") to tell HotDocs whether or not to include the paragraph.

A conditional region is defined by:

An IF instruction
A matching END IF instruction

Any text or HotDocs scripting within the condition region is only processed by HotDocs if the IF instruction's condition is met.

A condition is a logical statement that HotDocs can tell is either true or false. You can base your condition on either:

the answer value for a specific variable
an expression that tells HotDocs if an answer meets your condition

For example, you may need to check if a user answers yes to a true/false variable (ClientHasChildrenTf) before a paragraph is inserted into the assembled document. The IF condition would look as follows:

IF ClientHasChildrenTf

You can also use ELSE and ELSE IF instructions in a conditional region to create further conditions that branch off from the initial IF instruction. For example, you could have an initial IF condition that tests if a user answered Yes to include a particular paragraph. Using an ELSE instruction, you can include an alternative paragraph in the assembled document that is included if the question is answered No or is unanswered.

Common Tasks

Among others, conditional regions enable you to perform the following common tasks:

Workflow

When you create a template, there are often sections of text (paragraphs, sentences, or individual words) that you want HotDocs to only include in an assembled document under certain circumstances. When you edit your template, you can add conditional regions that surround these sections of text, so that they are only processed by HotDocs when particular conditions are met. You can also use conditional regions in HotDocs dialog scripts and computation, to control which sections of the script HotDocs processes.

Condition

A conditional region uses a condition to check if a region of text should be included or excluded. Conditions are logical comparisons between specific values to determine a result of true or false.

For example, you may test if a user answered with a value greater than 10 for a specific variable, if a user answered true to a true/false variable, or if a user selected a particular combination of options, among others.

Conditional fields can use the following types of condition:

Variable condition – a simple comparison against the answer value of a variable
Other Expression condition – a condition you write using HotDocs scripting to produce a true or false result

Base a Condition on a Variable

To base a conditional region on a variable or computation, you select a variable and then have HotDocs compare that variable to a value. If the data gathered during the interview meets the condition, the condition evaluates to true and HotDocs includes the region in the assembled document. You can choose from the following:

Base a Condition on a Computed Value

To base a conditional region on an computed value, you need to write a computation or expression that creates a true or false outcome. If the data gathered during the interview resolves to true, the region is included in the assembled document. You can choose from the following:

Variable Conditions

Variable conditions enable you to specify a value and a comparison that a variable must match. Comparison types include equals ('='), does not equal ('=!'), greater than ('>'), less than ('<'). For example, ProductPriceNm > 100 tests if the value for a ProductPriceNm variable is greater than 100.

Expression Conditions

Expression conditions enable you to write a condition using HotDocs scripting to produce a true or false result. This type of condition enables you to write more complicated conditions that allowed by simple variable comparisons. For example, you can write a condition that requires the user to provide specific answers for multiple variables: SigningDate < 01 JUN 2015 AND CompanyType = "PLC". The script editor for expression conditions is accessible in the Field Editor when you create a conditional region and select the Other expression condition type. You can also base an IF instruction on a list value and a record value by using the LIST CONTAINS EXPRESSIONS operator as the basis for your IF condition within a computation or expression.

Branching Conditional Regions

In your template you may need to create multiple versions of text that HotDocs includes in a template under different conditions. The best method of accomplishing this in HotDocs is to use an IF instruction and the following instructions to create a branching conditional region:

ELSE IF – an IF condition processed by HotDocs if the preceding IF condition is false
ELSE – a conditional region included by HotDocs if the preceding IF condition is false

The ELSE IF and ELSE instructions enable you to create extra conditions that HotDocs processes if their parent IF instruction is false. For example, you may have two paragraphs – controlled by a true/false variable, InsertStandardClauseTf – to conditionally insert in your assembled document:

Paragraph A – included if the InsertStandardClauseTf variable is answered true;
Paragraph B – included if the InsertStandardClauseTf variable is answered false.

To accomplish this, you create an IF instruction around the paragraph A text with a InsertStandardClauseTf = TRUE condition. You can then add an ELSE instruction around the paragraph B text. If InsertStandardClauseTf is true, HotDocs includes paragraph A in the assembled document. If InsertStandardClauseTf is false, HotDocs includes paragraph B in the assembled document.

ELSE IF instruction

The ELSE IF instruction enables you to add an additional conditional region to an existing IF instruction. HotDocs only processes the ELSE IF condition if the parent IF condition is false. The HotDocs only processes the content inside the ELSE IF conditional region if the ELSE IF condition is true. The ELSE IF condition uses the same types of condition as the IF instruction: variable conditions and expression conditions. For example:

[IF IncludeClauseOneTf]

// Text for condition one.

[ELSE IF IncludeClauseTwoTf]

// Text for condition two.

[END IF]

ELSE instruction

The ELSE instruction enables you to add an additional conditional region to an existing IF or ELSE IF instruction. The text inside the ELSE conditional region is always included in the assembled document if the parent IF or ELSE IF instruction's condition is false. For example:

[IF IncludeClauseOneTf]

// Text for clause one.

[ELSE]

// Default clause text

[END IF]

Create a Conditional region

You can create a conditional region when you are editing a text template. When you are creating the conditional region, there are two types of condition you can use to control when HotDocs processes the content inside a conditional region:

Variable conditions
Expression conditions

Using a variable condition

Variable conditions are conditions that make a simple comparison between a specific variable's answer value and a value that you specify.

For example,

To do this, you select settings for the following variable condition properties in the Field Editor:

Variable – the variable in the template from which you take an answer; you can use the following component types:
Comparison – the type of comparison you will make between the variable's answer and the value, resulting in either a true or false result; see Operators Overview for a full list of available comparison operators for different variable types
Value – the value with which the variable's answer is compared; this can be a:

The combination of these properties enables you to construct a condition that determines whether the piece of text enclosed in the IF, Else, or Else IF conditions is included in the document. If the answer the user provides satisfies the comparison between the variable and its value, or in other words, if that equation evaluates to true, then the text you selected gets included in the final document.

When you choose a computation variable that includes parameters, the HotDocs Field Editor displays fields for the parameters. Parameters work in the computation to provide an end-result value. This end-result value is then compared to the value you type in the value field. To create a conditional region based on a variable, you need to specify the relationship between a variable, such as a date, number, or text, and the corresponding value a user provides as an interview answer. The comparison value you choose from the comparison drop-down in the Field Editor tells HotDocs how to compare your text in the value field with the user's answer to determine if the answer meets your condition.

For example, suppose you want HotDocs to include a conditional paragraph when the user's answer to the Text variable "Insurance Text" contains the word benefits. You would select Insurance Text as the variable, then select contains as the comparison, and, finally, type benefits in the value field.

Line Spacing for consecutive conditional regions

By default, HotDocs adds a paragraph mark after each IF instruction. When HotDocs assembles a document and processes the IF instruction, it removes the added paragraph marks. This can cause formatting errors in the assembled document. For example, separate paragraphs may incorrectly appear in the assembled document as a single paragraph, if HotDocs removes the paragraph mark that separates them. You can resolve this issue by spacing your paragraphs and IF instructions to include a paragraph mark that is not removed by HotDocs. You should always test your template to ensure that the spacing of your paragraphs is correct when using conditional regions.

Nested Conditional Regions

You can create a conditional region inside another conditional region. HotDocs will not process the nested conditional region unless the condition for the preceding conditional region is true.

For example, if HotDocs finds that ClientMaritalStatusMc was answered Married, HotDocs inserts the text with the spouse’s name and then checks to see if ClientHasChildrenTf is true. If it is, HotDocs inserts the names of the children.

This ruling affects the client, «ClientNameTx»«IF ClientMaritalStatusMc = "Married"»; and spouse, «SpouseNameTx»«IF ClientHasChildrenTf»; and the following children: «REPEAT ChildrenDlg:a, b, and c»«ChildNameTx»«END REPEAT»«END IF»«END IF».

However, if ClientMaritalStatusMc is not answered Married, HotDocs does not process the rest of the instruction, including the question about children in the marriage.

Qualifying instructions

When creating a conditional region, any variables inside the region should not be used in other conditions outside of the region, unless the subsequent conditions also test if the first condition is true.

For example, the following script only asks the ClientNameTx variable if the end user answers the IncludeNewClientTf as true. Then, later in the template, another dialog is asked based on whether ClientNameTx is answered.

[IF IncludeNewClientTf]

[ClientNameTx]

[END IF]

…

[IF ANSWERED(ClientNameTx)]

[ASK ClientAccountDetailsDlg]

[END IF]

However, this script contains an error: a user can reassemble the document using the same answer file and change the answer for IncludeNewClientTf. This will stop HotDocs from asking ClientNameTx again. However, a value still exists for ClientNameTx in the answer file. When HotDocs reaches the IF expression later in the template, ClientAccountDetailsDlg is asked.

To fully qualify this condition, create an IF expression that tests both True/False Variable A and Text Variable B before asking Dialog 1. For example:

[IF IncludeNewClientTf AND ANSWERED(ClientNameTx)]

[ASK ClientAccountDetailsDlg]

[END IF]