Expressions Overview

An expression is a single statement in the HotDocs scripting language that resolves to a value; an expression can range in complexity from a single literal value or a variable (which represents a value stored in an answer set) to a calculation based on any combination of literal values, variables, operators, or functions (whether system functions or computation components). For example, the expression YEARS FROM(DateVar1, TODAY) tells HotDocs to calculate the number of years between today's date and a value your template user supplies for DateVar1 in the interview.

Overview

An expression tells HotDocs to evaluate its elements and resolve all of them to a single value. The possible elements of an expression include one or more values that help HotDocs to calculate a final value from the expression. References to such values can include a literal, a reference to a variable, or a call to a function, among others. For example, when a placeholder field references a variable, the variable reference acts as a simple expression that HotDocs evaluates to locate and access the answer to the relevant interview question, and then pass in the answer as the value that replaces the placeholder field during document assembly.

Common Tasks

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

Workflow

To help you create expressions, Author provides system function and operator models. When you write a script on the Script tab of a computation or dialog, you can drag and drop a model onto the Script tab from the Model tab to its right. Once on the Script tab, the model shows you the syntax HotDocs expects to make the function or operator work properly. You can then drag a component from the Component tab onto the red placeholders of the model.

Alternatively, you can select the placeholders, then type the proper value. When typing, HotDocs provides an auto-complete feature that tries to help you by guessing what you are typing. If you push CTRL + SPACE BAR on your keyboard, a list of syntax features appears from which you can select the element you need. You use the down and up arrow keys to change the selected element in the list.

HotDocs also provides syntax highlighting and error validation to help you create your expressions. If your syntax is correct, elements appear in various colors and font weights to help you better read your script. If your syntax is incorrect, HotDocs underlines the offending element with a red squiggly line to alert you that there is an error in the syntax. If you do not have any errors in your syntax, you can test your expression by clicking the Test button at the top of the current component editor.

Possible Elements of an Expression

When you are creating an expression using the syntax of the HotDocs scripting language, the elements you can add to an expression include:

Literals – represent a specific known value. When you want to represent a known value in your expression, you type it as a literal. For example, you type a text literal within quotation marks, like this: "I am a text literal".
Variables – represent a value that is unknown to you at the time you create your expression. When you reference a variable in your expression, you are referencing a value that your template user provides during the interview, which HotDocs then stores in an answer set. A variable reference tells HotDocs to retrieve a value from the answer set when it evaluates your expression. You reference a variable by using its name within your expression, like this: VarA.

You can also use local variables in an expression.

Computations (with or without a list of parameters) – represent a value that is unknown to you when you write your expression. Using a computation's name as part of an expression causes HotDocs to evaluate that system function and pass a computed value of a certain type into your expression, since computations have a result type. If the computation requires parameters, when you type the name of the computation, you must include the list of parameters that computation has (if any) immediately following its name, enclosed in parentheses and separated by commas, like this: CompA(param1, param2, param3).
System functions (with or without a list of parameters) – represent a value that is unknown to you when you write your expression. Using a system function’s name as part of an expression causes HotDocs to evaluate that system function and pass a computed value of a certain type into your expression, since system functions have a result type. If the function requires parameters, when you type the name of the system function, you must include the list of parameters that computation has (if any) immediately following its name, enclosed in parentheses and separated by commas, like this: SystemFuncA(param1, param2, param3).

Operators – represent an operation you want HotDocs to carry out to further evaluation of your expression. There are two kinds of operators:
- A binary operator – a symbol or key word in HotDocs that computes a value by acting on exactly two operands. It uses a familiar (<operand1> <operator> <operand2>) syntax, and results in a computed value of a type that depends on the specific operator. A very common example is NUMBER + NUMBER, such as 2 + 4. The plus operator (+) arrives at a number result by adding the values of its two operands.
- A unary operator – a symbol or key word in HotDocs that computes a value by acting on exactly one operand. Some unary operators use prefix notation (<operator> <operand>), for example the unary minus operator: -5. The unary minus operator (-) immediately precedes its operand (5), and it arrives at a number result by changing the mathematical sign of its operand. Some unary operators use postfix notation (<operand> <operator>), for example the percent operator: 10%. The operand (10) is followed immediately by the operator (%), which arrives at a number result by dividing its operand by 100.
Formatting Marker Fields - the Field Editor offers placeholders for the majority of formatting marker fields, other marker fields can be added as expressions.

Single Line Expressions

Author enables you to create a single line expression and to add a placeholder field for that expression, all from within the Field Editor. While it's generally best practice to create a computation containing your desired expression to achieve the same functionality, if you are an advanced user and are confident that there will only be one reference to your expression in your template, then creating a single line expression using the Field Editor can be a simpler, more efficient way to achieve the functionality. For example, you can type the expression YEARS FROM(DateVar1, TODAY)into the Expression text box when adding a placeholder for an Other Expression in the Field Editor (and assuming you have the DateVar1 date variable) you can get the answer of that calculation placed directly into the template.

While you can apply formats to the expression, the expression editor does not provide the syntax highlighting and error validation available in the computations you write in the Component Studio.

Expression Examples

To better understand expressions, review the following examples. Remember, each expression implicitly tells HotDocs to calculate a single value by evaluating all the elements (whether these be one or many) in the expression. For more examples of expressions, see the example code provided for each function and operator.

Number Value Expressions

The following example expressions are classified as number value expressions because the expressions all resolve to a number value:

5 – a number literal, that HotDocs evaluates to a number value of 5
YEAR OF(Birth Date) – evaluates to a number value representing the year portion of the answer your template user would provide to a Date variable called Birth Date (e.g., if the answer to Birth Date is 4 JUL 1976, the expression evaluates to the number 1,976)
YEAR OF(Birth Date) + 18 – evaluates to a number value representing the year in which someone providing an answer to the Number variable Birth Date turns 18 years old (e.g., if the answer to Birth Date is 2000, the expression evaluates to 2,018)
MAX(Num1, Num2) – compares the two number values you specify and returns the greater of the two values (e.g., if Num1 evaluates to 5, and Num2 to 3, then the MAX function returns a number value of 5)

Text Value Expressions

The following example expressions are classified as text value expressions because the expressions all resolve to a text value:

First Name + " " + Last Name – computes a text value by concatenating the answer to First Name (a Text variable), a single space character, and the answer to Last Name (another Text variable)
FIRST(First Name, 1) – Gives a result that is a text value equal to the first character of the answer to First Name (a Text variable)
FORMAT(TODAY, "8 NOVEMBER 2018") – converts another value type (in this case, a date value) into a text value consisting of today’s date formatted as a text value according to the format you specify

Date Value Expressions

The following example expressions are classified as date value expressions because the expressions all resolve to a date value:

20 JUN 2019 – a date literal, that HotDocs evaluates to a text value of 20 JUN 2019
TODAY – evaluates to a date value representing the current date as supplied by the system clock
Signing Date + DAYS – evaluates to a date value representing the answer to a Date variable plus the number of days you add to the answer

True/False Value Expressions

The following example expressions are classified as true/false value expressions because the expressions all resolve to a true/false value:

TRUE – a true/false literal, that HotDocs evaluates to a true/false value of TRUE
ANSWERED (First Name) – evaluates to a true/false value of TRUE if the template user answered a Text variable called First Name in the interview
Client is Married AND Client has Children – evaluates to a true/false value of TRUE if both the True/False variable Client is Married and the True/False variable Client has Children are true

Common Reference Topics

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