Understand the HotDocs Scripting Language

Learning the Language

As you use HotDocs, you may need to tell HotDocs to perform a particular task, such as insert one template into another or perform some action based on an answer the user provides. Similarly, you may need to add up several dollar amounts, or find the number of years between two given dates. Or, you may need to search a user’s answer for a certain block of text.

To accomplish this, you must use the HotDocs scripting language, which consists of instructions, expressions, operators, and values—such as text, numbers, dates, or answers users enter. To help you learn this language, HotDocs provides you with instruction and expression models.

Specifically, an instruction model tells HotDocs to perform some sort of function, while an expression model retrieves a special value. Most models also include placeholders, which you must replace with a value. Possible values include text strings, number amounts, other models, and HotDocs variables. A model will not work until all its placeholders are replaced.

In addition to using instructions and expressions, you can use operators to control how the script is processed. Most operators are common mathematical signs, but there are also Boolean operators such as AND and OR. The operator AND means the statement to the left and the statement to the right must both be true. The operator OR means either the statement to the left or the statement to the right must be true. The operator ( ) means to perform the operation between the parentheses first. (See Use Operators When Scripting.)

Rules for Writing Scripts

Instruction and expression models are designed to help you accurately write scripts. However, there are still certain rules you must follow, particularly when it comes to replacing placeholders with values. Failure to follow these rules may result in syntax errors when HotDocs attempts to process the script during assembly.

When using literal values:

• Decimal numbers less than one must have a zero before the decimal point (0.125 not .125).
• Numbers cannot contain commas (1250 not 1,250).
• Dates must be in the form 3 JUN 1990.
• Text strings must be inside quotation marks.

To help you format these numbers correctly, use the Enter a Date, Enter a Number, Enter some Text, and Enter True or False expression models.

When manually typing the script:

• Component names must be entered exactly as they appear in the Components list, including capitalization.
• Components and operators must be separated by spaces.
• Operators must be entered exactly as they appear in the Operators list, including capitalization.
• Variables used inside a literal text string (or between quotation marks) in a computation must be inside chevrons (« »). If the variable name is not inside chevrons, the variable name—not the variable's value—will be merged as the answer. (For example, "«Employee Name» must wait «Number of Months» months before applying.")

If you want to include a chevron in a HotDocs text template either as a part of your document text or a literal text string, you need to double the opening chevron (but not the closing chevron), so that HotDocs does not interpret the chevrons (and any text between them) as a field. The output is a single chevron, as follows: input: ««some text», output: «some text».

• Keywords, such as TRUE, FALSE, AND, END IF, and so forth, must be in all capital letters.
• Only TRUE or FALSE can be used for a true/false value.
• If you want the computation to return a combination of text, variables, and values, you must concatenate (or join) the data with the Add ( + ) operator. Otherwise, HotDocs returns only the last piece of text, variable, or value.
• When using the RESULT expression, you must first set the computation to a value. If the computation will return text, set it to a specific value by typing text inside quotation marks at the start of the script. (To set a text computation to an empty value, type nothing between the quotation marks—not even a space.) If the computation will return a number, set it to a value by typing a number at the very beginning of the script. (To set a number computation to nothing, type 0 (zero).)

Writing the Script

There are two places in HotDocs where you can write scripts: The Computation Editor and the Expression field of the IF Field dialog box. Each of these places provides you with the tools you need to write the script. Which tools you use, however, depends on personal preference, as well as your skill level.

If you are learning the scripting language, it is suggested that you select and drag instructions and expressions from the models lists to the Script field. You can also drag operators and components from their respective lists into the Script field. If there are placeholders, replace them by dragging components or other models onto them. To correctly format literal values (such as text, numbers, dates, and true/false values) use the Enter... expression models.

If you prefer to use the keyboard rather than the mouse, press the Tab key to move from one field in the dialog box to the next. Use the arrow keys to select specific components, operators, and models, and use the Insert key to bring the selected element into the Script field. To replace placeholders in the script, insert your cursor in the placeholder text and then locate the value you want to replace it with in the lists below and press the Insert key.

Once you become familiar with the instructions and expressions, you can type your scripts directly in the Script or Expression field. To ensure you use the correct instruction and expression keywords and component names, you can access lists of these things using keyboard shortcuts and other options available in the script editor. When you do this, HotDocs displays an auto-complete list from which you can choose the instruction or expression you are typing. For complete instructions, See Use the Script Editor.