HotDocs Scripting Language Overview

The HotDocs scripting language is a specialized computer language used in HotDocs Author to instruct the software to perform specific tasks within templates and interviews. For instance, if you have questions in your interview that are not relevant to minors, you can use a script to hide those questions when a template user enters a date of birth indicating they are under eighteen years old.

Overview

The HotDocs scripting language is designed to be user-friendly, even for those with little experience in scripting. Its vocabulary is limited to approximately 40 words, making it easy to learn and use. The language recognizes two types of commands: Instructions, which tell HotDocs to perform an action, and Computations, which tell HotDocs to calculate something.

The HotDocs scripting language allows you to incorporate mathematical and logical operations into your templates and interviews. With its mathematical capabilities, you can calculate values that supplement the answers your users provide during an interview. The logical operations enable you to perform tasks such as revealing or hiding portions of your template or interview based on the template user's answers, or gathering a list of answers from a single question. You can find a comprehensive list of available operations in the Full List of Instructions, Functions, and Operators topic.

Two Types of Scripts

There are two types of scripts in HotDocs, each with a different purpose:

Computations – These scripts allow you to calculate a value of a given type, and to encapsulate requests for answers and other similar tasks into a reusable set of instructions and expressions. HotDocs stores computations in your template's component file which you edit in the Computation Editor. You can reference a computation using a placeholder field.
Dialog scripts – These scripts enable you to control the appearance of various elements in your interview and the flow of your interview. You can only create and reference dialog scripts within a Dialog Editor

While the difference between these two types of scripts may seem blurry due to the existence of interview computations for Answer Intakes and the ability to calculate values within a dialog script, it's important to understand the distinct purposes of each type of script.

Common Tasks

Among others, the HotDocs scripting language enables you to perform the following common tasks:

Workflow

To create a HotDocs script, you must first create a computation component, dialog component, or an answer intake. Once you have created one of these components, you can open it for editing within Component Studio and navigate to the Script tab to write your script. While the Script tab is initially blank, HotDocs provides various aids to help you learn how to write scripts. Whilst you can create elements of a HotDocs script within individual fields, a true HotDocs script can only be created within one of these components. When a template is assembled, HotDocs reads the script and carries out the commands that you have specified.

The Parts of a Script

In HotDocs Author, a script is a set of instructions that tells HotDocs to perform an action or calculate a value. To understand the structure of a script, you can use a metaphor of writing a paragraph in a human language. A paragraph consists of building blocks called sentences, and a script consists of building blocks called statements. A statement is the smallest syntactic unit in the HotDocs scripting language that tells HotDocs to complete a task or to calculate a value.

Just as a sentence in a human language contains different types of building blocks such as nouns, verbs, adjectives, and conjunctions, a statement in the HotDocs scripting language consists of smaller syntactic elements that can be combined to create a complete statement.

Some elements in the HotDocs scripting language can work similarly to implied elements in a sentence. For example, the system function TODAY has an implied series of commands that use your computer's system clock to return a date value that corresponds to today's date. While the keyword TODAY is both the name and the whole body of the function, there is an implied series of commands that use your computer's system clock to return a date value that corresponds to today's date. While you could use this function as an entire statement within a script, it's more common to use it as part of a larger statement.

Instructions and expressions in the HotDocs scripting language act like transitive verbs. For example, the SET instruction is: SET [variable] TO [value]. The IF expression is IF [variable] is True (or False), then DO this. However, much of the information is implied in these statements.

Language Elements of a Statement

A statement in the HotDocs scripting language can consist of a single expression or instruction, or it can include a combination of one or more expressions or instructions. Instructions and expressions enable you to tell HotDocs what to do, while functions and operators tell HotDocs how to do it. Values, on the other hand, tell HotDocs what to do it to and provide information about the outcome of the actions taken. By combining these elements in various ways, you can create complex scripts that automate the process of creating documents.

Statements Based on an Instruction

In the HotDocs scripting language, a statement based on an instruction consists of an instruction keyword, which can be compared to a verb in a human language. The instruction keyword acts on components or values, which can be compared to pronouns or nouns in a human language.

Instructions are keywords in the HotDocs scripting language that tell HotDocs to perform an action on a component, such as ASKing a dialog at a specific place in the interview or using the HIDE instruction to hide a variable during an interview until the variable becomes pertinent.
- Other keywords include system functions, system local variables, and operators. Just like instructions, these keywords act as verbs which cause HotDocs to generate a value or perform a task. Additionally, there are other keywords that act as supplementary instructions and do not perform any action on their own. Examples of these keywords include TO (as in SET exampleVar TO Value) and ALL (as in HIDE ALL). Since keywords tell HotDocs what to do, they act as verbs, just like instructions.
Components are uniquely named building blocks of a HotDocs template with attributes and rules (properties) that define their appearance and behavior in an interview, the way they handle answer data, and how HotDocs applies that data when assembling a document. They can act within a script as a stand-in for an as-yet-unknown value, similar to how a pronoun acts as a stand-in for a noun in a human language.
Values are pieces of data of a type that HotDocs knows how to process. They can be known or unknown. If a value is unknown, it can be represented by a component such as a variable, which can be used to ask the template user to supply that value. Once the user answers the question the variable represents, HotDocs can store that known value as an answer. If you want to pass a known value within a script, you must use the appropriate literal syntax for that value type. In the HotDocs scripting context, values act as nouns do in human language. They can act as subjects or objects within a sentence. Just as a verb can act on a noun, an instruction, function, operator, or other keyword can act on a value, whether it is a known or unknown value. A value is always of a certain type, such as text, number, date, record, or list. The type acts as a modifier to the value, indicating its nature. For instance, the value "5" can be interpreted as either a number or a text value, depending on its type. To express a quantity as a date value, you would need to declare the value as a number value and provide it in the appropriate literal syntax.

Statements Based on an Expression

In a statement based on an expression, the context in which the expression occurs acts as an implicit command, similar to a verb in a human language. The context acts upon the expression like a verb does to a noun phrase. An expression can be a simple evaluation of a single variable or value, or it can be more complex, involving functions, operators, variables, and values. Regardless of its complexity, an expression always resolves to the single value it is meant to calculate. What happens with that value is determined by the context in which the evaluation occurs.

Context is a circumstance (usually based on location) that provides an overriding implicit command to an expression. The context acts as a transitive verb, but only an implied one. For example, if an expression is part of a computation, the context gives the implicit command to return a value of a particular type. Similarly, if an expression's context is a placeholder field, then the implicit command is for the expression to replace the placeholder field with the value it calculates. In a dialog script, the implicit command to an expression is to calculate a value, but do nothing with that calculation. Instead, dialog scripts are meant to effect the appearance of dialogs and their variables within an interview, using commands such as HIDE, SHOW, GRAY, UNGRAY, etc. In its relationship to its context, an expression is similar to a noun phrase that is the object of the implied verb of the context.
Expressions are single statements in the HotDocs scripting language that calculate a single value. They take the form of an evaluation of one or more values, variables, operators, or system functions. As an example, the expression YEARS FROM(DateVar1, TODAY) uses the system function YEARS FROM to calculate the number of years between an unknown value that your template user supplies during the interview for a variable called DateVar1, and the value returned by the system function TODAY. An expression always resolves to some value, and a value in the HotDocs scripting language is comparable to a noun in human language. Therefore, an expression can be thought of as a noun phrase that receives the action of the verb implied by the context in which you create the expression.
System functions are named calculations in the HotDocs scripting language that take zero or more values as inputs (parameters) and produce a single value as a result. The HotDocs scripting language includes system functions, but also enables you to create your own functions (computations). They act as evaluators of data and return a value, making them closer to a noun than a verb. The system function FIRST takes a text value and a number value as inputs. The number value indicates how many characters the function should count from the start of the text, moving from left to right. For example, if you provided the text value "Mississippi" and a number value of 5, the function would return the value "Missi". This function modifies the noun "Mississippi" by returning a substring of the original value. Functions are labeled as adjective (ish) in the diagram above because they modify values in a similar way to how adjectives modify nouns in human language.
Operators are symbols or words that cause HotDocs to carry out an operation or a comparison in a computation or expression. They operate on two values to produce a result, just as conjunctions and comparatives do with nouns in human language.
Variables are a type of component that represents an unknown value. They can be defined to gather that value from a template user, store that value as an answer, and format that answer when assembling a document. Within an expression, a variable represents an unknown value and performs a similar function to the role a pronoun plays in a human language.
Values – see the discussion on Values under Statements Based on an Instruction, above.

HotDocs Fields versus HotDocs Scripts

A template in HotDocs Author is made up of boilerplate text interspersed with HotDocs fields. Almost every HotDocs field contains either an instruction or an expression, making it a statement in the HotDocs scripting language. Placeholder fields referencing a variable are considered a single variable expression. However, you cannot add both an instruction statement and an expression statement to a single HotDocs field, except for placeholder fields that reference a computation component, which can contain both instructions and expressions.

In contrast to the fields in a template, a HotDocs script is a sequence of interrelated statements composed of instructions and expressions. These statements work together to complete a specific task, one that is likely unrelated to the aims of the next field in the template. While the same building blocks are used in both HotDocs fields and scripts, they are packaged differently.

When creating a HotDocs field in the HotDocs Field Editor, HotDocs provides support to guide you through the creation of the field's statement. In a HotDocs script, there are writing aids available, but you have more freedom to compose your logic in the way that works best for you.

Accessing Values in the HotDocs Scripting Language

To access a value in the HotDocs scripting language, you need to know where that value is located. The only permanent memory in HotDocs is an answer set, so you need to know the syntax for accessing this data. For example, if you want to access a value in a text list in the answer file, you need to use the syntax of a list literal - [0, 1, 2]. The left bracket indicates the beginning of the list, the commas indicate individual values in the list, and the right bracket indicates the end of the list. In this example, there are three values in the list.

Dot Operators and Cell Lookup

The HotDocs scripting language also contains a special feature to enable you to lookup individual cells in tabular data, such as in a Fixed Table component. For instance, if you create a Fixed Table component called Employees with columns for First Name, Last Name, Birthday, Hire Date, etc., and you supply the corresponding data for the following individuals:

Susan Smith
Barney Franklin
WIll Frederickson

You can write a script to use Barney Franklin's Hire Date using the dot operator.

You use Fixed Table components, which act only as data stores, in conjunction with a Selection variable which enables you to choose an Option Source. In this example, you would create a Selection variable called Employee List and choose the Fixed Table component Employees as your Option Source. Then, to access Barney Franklin's hire date, you would use the dot operator to specify the proper cell as follows:

Employee List.Hire Date

IF ANSWERED Employee List

SET

Access to a cell is case sensitive. If your column name is Hire Date, and you try to access that with hire date, the look up fails.

Write a Script

To write a script, you first need a clear idea of the actions you want HotDocs to take. For example, you may want to HIDE a variable on a dialog until your template user responds to a related variable's prompt. To achieve this, you need to think logically about the steps required to achieve this and translate those steps into the appropriate instructions, functions and operators of the HotDocs scripting language.

Suppose you need some variables in your template to appear in the interview only if your template user is from Hawaii. To accomplish this, your script needs to check the answer to a variable asking for the template user's address to see if the address is in Hawaii. If the address is in the state of Hawaii, you would instruct HotDocs to display any Hawaii-specific variables in the interview.

In plain terms, you want to tell HotDocs to:

Hide the Text variable Client Address Island unless your template user needs it.
Therefore, check if the answer to Client Address State contains the word "Hawaii."
If it does, show the Text variable Client Address Island.

Once you formulate what you want HotDocs to do in clear language, you can further shorten the clauses like this:

Hide Client Address Island.
If Client Address State contains the text value "Hawaii,"
Show Client Address Island.

You can now translate this into a HotDocs script as follows:

HIDE Client Address Island

IF Client Address State CONTAINS "Hawaii"

SHOW Client Address Island

END IF

This script syntax is very close to normal speech; however, there are some important things to remember when writing a script:

You must type instructions, functions and operators in ALL CAPITALS using the exact keyword HotDocs requires to recognize that you are writing a script (HotDocs provides clues to help you)
You must type variable names exactly as they appear in Component Studio, including any capital letters and spaces
You must put quotation marks around any text you want to treat a as literal text value (as with the text "Hawaii" in the example above)
You must use the correct type of value (e.g., a variable or a dialog) with each instruction, function or operator. The CONTAINS instruction you see in the example above requires you to provide a text value before and after CONTAINS in order for the instruction to work – in this case, Client Address State before CONTAINS and the literal text value "Hawaii" after

To avoid getting into trouble with any of these rules, it is best to practice writing scripts by using script models, as in the dialog script example available below.

Use Script Models

When you want to write a script, instead of starting from scratch and trying to remember the correct syntax, you can use a model to follow. This is a pattern that teaches you proper HotDocs scripting language syntax.

On the far right of the Script tab, HotDocs provides a Components tab and Models tab:

The Components tab contains a list of components available in your current component file for you to use in your script.
The Models tab contains a list of models that demonstrate the proper syntax for instructions, functions and operators.

When you drag an instruction, function, or operator from the Models tab and drop it onto the script editor, HotDocs highlights in red (and within brackets) the parts of the models that act as placeholders for values. You can then either type information into those placeholders or replace them with the proper reference by dragging and dropping components from the list of components available on the Components tab.

The list of models changes depending on which component editor you are currently using. For example the list of available models changes between the Dialog Editor and the Computation Editor.

Looking at the example we've been following above, you can create the first line of that script by dragging the HIDE instruction from the Models list and then dragging the Text variable Client Address Island from the Components list.

Use Auto-complete

Writing a script can seem daunting when you are staring at a blank Script tab. To help you with this, HotDocs provides in-line hints to help you if you don't remember the keywords needed for instructions, functions, and operators. To use the the auto-complete feature, you first need to place your keyboard focus in a Script tab or expression editor, and then press CTRL + SPACE BAR.

When you do this, HotDocs displays an auto-complete drop-down list at the cursor position. You use the down and up arrow keys to change the selected element in the list. The list includes:

All components in the current component file
All instructions valid in the current scripting context (that is: computations versus dialog scripts)
All system functions and operators valid in the current scripting context
Any parameters or local variables you previously defined in the current scripting context
All other key words that can occur in scripts

The above items all appear in alphabetical order.

HotDocs then inspects the word (if there are any) immediately to the left of your current cursor position. HotDocs uses any text there to filter the list so the list only displays items that include the word to the left of the cursor (as appropriate). Also, if any of the items in the drop-down start with the word found to the left of the cursor, HotDocs highlights the first such item. (If nothing in the filtered list starts with the word, the list still appears as noted, but without highlighting any item.)

If you type enough letters that the filter finds only one word that satisfies the filter (for example, typing "OTH" eliminates all words but OTHER), HotDocs inserts this word for you. Otherwise, you can use the up and down arrow keys to move a highlight through the auto-complete list. When you press ENTER, HotDocs inserts the currently highlighted item into the script at the cursor location, and the auto-complete list disappears. You can also dismiss the list by pressing ESC, moving the selection elsewhere with the mouse, or in some other way causing the script editor to lose focus.

With the list visible, if you type or delete characters, the filtering updates as expected.

Make Your Script Easy to Read

While having a long horizontal line of script might make sense to a computer, a human reading and looking for errors may have trouble, especially as your scripts get longer and more complicated. The following is an example of what NOT to do:

HIDE Client Address Island IF Client Address State CONTAINS "Hawaii" SHOW Client Address Island END IF

To make a script more readable, first, break it up into one action per line. Using the same example above you can break the one long line into:

HIDE Client Address Island

IF Client Address State CONTAINS "Hawaii"

SHOW Client Address Island

END IF

You should also always leave END IF (and other END) instructions on their own lines. This makes it easier to spot sections of the script that are conditional or should in other ways be considered as a unit.

Syntax Highlighting

When you write a script in a script box, HotDocs also provides syntax highlighting to help you see when you do things properly and when you make mistakes. To do this, HotDocs combines colors and bold text to help make your script even easier to read. HotDocs uses Bold for instructions, functions and operators, blue for variables, and maroon for literal values, as follows:

HotDocs only recognizes a word as a literal value and colors it maroon if you surround the word with quotation marks. The quotation marks tell HotDocs not to evaluate this word as a variable or other script element.

HIDE Client Address Island

IF Client Address State CONTAINS "Hawaii"

SHOW Client Address Island

END IF

To make the script even easier to read, you can have HotDocs add some useful tab spaces to your script when you click the Format Document button. This makes it clear at a glance which sections of the script are conditional as it indents all the lines that form the conditional region.

HIDE Client Address Island

IF Client Address State CONTAINS "Hawaii"

SHOW Client Address Island

END IF

Use Script Error Validation

In addition to the above, HotDocs provides other aids to enable you to correct errors in your script. For instance, if you make a mistake in your script, HotDocs adds a red squiggle under text that meets the following conditions:

Text that does not correspond with an existing variable, component, instruction, etc.
Misplaced operators, instructions, variables, etc.
White space that is out of place
Incomplete commands or statements

To fix an error in your script:

Make sure the text you entered as script corresponds to existing variables, components, instructions and operators
Make sure all operators, instructions and commands are correctly placed within the script
Make sure all commands and statements are completed (for example, you must conclude an IF command with an END IF)

Use Local Variables and Parameters as Needed

Parameters (available on computations) and local variables (available on both dialog scripts and on computations) enable you to create data points that exist only within the context of the computation or dialog script. This can be useful in keeping your component file's list of components less cluttered and more usable.

You add a parameter from just below the computation's Name field
You add a local variable from just below toolbar on the Script tab

Local Variables

A local variable is a variable you create and use only within a computation, dialog script, or an answer intake as a placeholder for temporary data pertinent only with that script. Sometimes when you write a script you may find you need a temporary variable that isn't used anywhere else in your template, for example: you may need a Number variable to act as a counter when you're calculating repeats for a repeated dialog. Rather than creating a real variable that sits in your component file and clogs up your list of components, you can make a local variable that exists only in your dialog script. You need to SET the value of a local variable before you can use the variable.

Parameters

A parameter is a placeholder you create within a script to "pass in" a value external to your script. A parameter therefore enables you to provide an initial value to a computation that depends on a value outside your computation. Passing in a value enables you to encapsulate sections of a script that you may want to repeat with slight variations, or even from multiple different scripts using the value you provide as the parameter. For example, you may need multiple scripts that perform the same operation within their particular context. Instead of creating the same script multiple times, you can create a computation that takes as a parameter the value you want to operate on. In each of the multiple locations, you can then "call" the computation and "pass" the value into the other scripts as a parameter. Writing scripts in this way is called encapsulation and makes your scripts easier to read and manage, and helps you keep errors from entering your scripts.

Important General Considerations when Writing a Script

When writing a script, to avoid errors, you can either drag and drop a model into your script, or use the lookup feature. When manually typing the script:

You must add component names exactly as they appear in the Components list (including capitalization)
You must ensure that spaces separate the names of components and any operators
Operators must appear exactly as they do in the Models tab, including capitalization
Keywords, such as TRUE, FALSE, AND, END IF, and so forth, must appear in all capital letters
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.

Whenever you are creating a computation, you must ensure you set the RESULT type property to the appropriate value type for the computation to work.

You can also choose to set the RESULT type to NONE when defining a custom interview computation.

Example Dialog Script

If you want to practice creating a dialog script, follow the steps below:

Set up a template:
1. Create a template
2. Create a dialog using Component Studio (call it Test)
3. Add two Text variables called Client Address State and Client Address Island.
Open Component Studio,
Double-click the Test dialog to open the Dialog Editor, then click the Script tab in the Dialog Editor.
In the Models tab to the right, click to expand the Dialog Instructions list
Drag and drop the HIDE instruction onto the Script tab so you can see the model HIDE ⟦VAR⟧.
Hover your mouse pointer over the ⟦VAR⟧ placheolder. The tooltip tells about the placeholder and the types of items you can replace the placeholder with.

HotDocs cannot evaluate a model on its own. You must replace a model's placeholders with the correct type of component or value. The red text of a model tells you the type of value you need to replace it with for HotDocs to process that statement. This can be any variable (var), or one of a specific type of components (such as a, text, number, dialog, etc.), or an expression.

From the Components tab (to the right of the Script tab), drag and drop the Client Address Island Text variable onto the ⟦VAR⟧ placeholder, which disappears as the Client Address Island (in blue font) takes its place.
In the Models tab, open the General Instructions list and select the IF instruction; then drag and drop the IF onto a new line.
Return to the Models tab and open the Logical Operators list.
Select TEXT CONTAINS TEXT and drag it onto the ⟦EXPRESSION⟧ placeholder in the IF instruction.
From the Components tab, drag and drop Client Address State onto the first ⟦TEXT⟧ placeholder.
Delete the second ⟦TEXT⟧ placeholder and type "Hawaii" in its place (including the quotation marks – these tell HotDocs this is a "text literal" and not a variable).
Press ENTER; then click the Models tab.
From the Dialog Instructions list, drag and drop the SHOW instruction onto the new line.
From the Components tab. drag and drop Client Address Island onto the ⟦VAR⟧ placeholder.
Press ENTER; then on the Models tab, expand the General Instructions list and drag and drop END IF onto the new line.
In the toolbar on the Script tab, click the Auto Format button (this normalizes the tab spaces and indents).

Script Writing Recap

Write down what you want HotDocs to do
Rewrite your original words into short clauses
Translate your regular English into HotDocs script:
- Use script models
- Use auto-complete
Use one line per instruction or function
Put END instructions on their own lines
Use the syntax highlighting and error validation to see when you write things properly, and when you're making a mistake
Use the Format Document button to add useful indents

Script Syntax Rules to Remember

Models are designed to help you accurately write scripts. However, there are still certain rules you must follow to make sure HotDocs understands what you want it to do. Failure to follow these rules may result in syntax errors when HotDocs attempts to process the script during assembly.

Rules for Using the Script Editor Tab

When you are creating a computation, you need to set the computation’s result type. This can be:

Text
Number
Date
True/false
None

If the result type you select does not match the result of the script you write, HotDocs shows an error and will not process the computation.

Rules for Replacing a Model with 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).
You must write dates in the form 3 JUN 1990.
You must put text strings inside quotation marks.

Rules for Manually Typing the Script rather than Using a Model

You must enter component names exactly as they appear in the Components list, including capitalization.
You must separate components and operators by a space.
You must enter operators exactly, including capitalization.
In a computation, you must put variables you reference inside a literal text string (i.e., between quotation marks) within brackets, as follows: "«Employee Name» must wait «Number of Months» months before applying.]

If a variable name is not within chevrons, HotDocs uses the variable name—not the variable's value—as the answer.

You must type keywords, such as TRUE, FALSE, AND, END IF, and so forth, in all capital letters.
You can only use TRUE or FALSE 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, as in the example provided in the TEXT + TEXT model. Otherwise, HotDocs returns only the last piece of text, variable, or value.

Tips and Tricks

It is important to remember when creating expressions within a DOCX template that the script elements you include in the Word template can control the final look of the assembled document.
When you're writing an expression in a HotDocs Field, you can use a bar "|" as a hard return. If you have smart quotes on, you can lose a hard return -- the bar ensures it stays. Another solution to this issue is to use the Preserve Empty Paragraph property in the Advanced Properties for a HotDocs Field.

Common Reference Topics

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