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.
In this topic Hide
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:
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:
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
See IF instruction for more information about writing conditions for IF instructions.
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.
Among others, conditional regions enable you to perform the following common tasks:
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.
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:
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:
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 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 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. See the HotDocs Scripting Language Overview for more information about creating scripts.
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:
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:
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.
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]
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]
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 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:
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.
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.
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.
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]