The HotDocs scripting language is a HotDocs Author-specific computer language you can use to tell HotDocs to accomplish certain tasks in your templates and interviews. For example, if you have questions in your interview that do not apply to minors, you can use a script to hide all such questions when a template user provides a date of birth indicating they are under eighteen years of age.
In this topic Hide
In barest terms, the HotDocs scripting language exists to enable you to add mathematical and logical operations to your template and interview. The mathematical capability of the scripting language enables you to calculate values you need to supplement answers your template users provide in an interview. The logical operations enable you to perform tasks such as exposing or concealing portions of your template or interview based on your template user's answers in the interview, or enabling you to gather a list of answers from a single question. You can review the different types of operations available in the language in the Full List of Instructions, Functions and Operators topic.
The focus on the two different purposes in crafting a script (calculating values, and crafting logical operations) leads to two different kinds of scripts:
The difference between these two types of scripts can be a bit blurry due to the existence of interview computations for Answer Intakes, and because you can calculate a value within a dialog script.
Among others, the HotDocs scripting language enables you to perform the following common tasks:
While you can create elements of a HotDocs script within individual HotDocs fields, you can only create a true HotDocs script within a computation component, dialog component, or an answer intake. This means that to create a script, you first must create a dialog or computation, then open the component for editing within Component Studio. Each of these components has a Script tab where you write your scripts. While the Script tab is initially blank, there are many aids (described below) that HotDocs provides to help you learn to write scripts.
In HotDocs Author, a script is a set of directions that tells HotDocs to perform an action or calculate a value. If you were to relate this to writing a human language, you could equate a script with a coherent paragraph on a given topic. A paragraph consists of building blocks called sentences. You can define a sentence as the smallest element of writing that expresses a complete thought. In the same way, 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.
You can carry this metaphor further. In a human language, a sentence contains building blocks of different types such as nouns, verbs, adjectives, conjunctions etc., which you combine into a sentence with a subject, object, and verb. Similarly, in the HotDocs scripting language are smaller syntactic elements you can combine to create a complete statement.
In addition, just as you can create a complete thought in someone else's mind by implying some elements of a sentence, there are some elements in the HotDocs scripting language that perform a similar role. For example. if you see a small child you don't know toddling towards some danger, you might simply yell "Stop!" Implied in that command is the following more complete thought: "Hey, you, stop walking (towards that road), or you'll get hurt!" This sentence has a subject (you), object (the road), and verbal (get hurt), as well as several other elements that are merely implied, rather than stated overtly. Some items in a HotDocs script can work in a similar way. Consider the system function TODAY. 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. You wouldn't often use this function as an entire statement within a script, but in principle, you could. Similarly, you might build an entire script from a single statement, just as you could conceivably craft a single sentence that reads like a paragraph. In general, however, a script consists of more than one statement.
Statements can consist of a single expression or instruction, or, it can include a combination of one or more expressions or instructions. These two kinds of building blocks work slightly differently. You can think of these scripting building blocks in this way: instructions and expressions enable you to tell HotDocs what to do, the functions and operators tell HotDocs how to do it, and the values tell HotDocs what to do it to, as well as alerting HotDocs to the outcome of the actions taken.
At the root of a statement using an instruction, is the instruction keyword, which you can relate to a verb in a human language. Sometimes an instruction works in harmony with another keyword to act on components or values, which you can compare to pronouns or nouns in a human language:
The first element in a statement based on an expression is the context in which the expression occurs. The context acts as an implicit command, which you can compare 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 very simple evaluation of a single variable or value, or it can be more complex, involving functions, operators, variables and values. No matter 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:
A template in HotDocs Author consists of boilerplate text interspersed with HotDocs fields. Almost every HotDocs field within a HotDocs template contains an instruction or an expression, and is, therefore, a statement in the HotDocs scripting language (this includes placeholder fields referencing a variable, since this is a single variable expression). You cannot however, add both an instruction statement and an expression statement to a single HotDocs field (unless that field is a placeholder field that references a computation component, since computations can contain both instructions and expressions).
As mentioned above, a HotDocs script, is a sequence of interrelated statements composed of instructions and expressions. These fit together similarly to how sentences in a human language work together to form a coherent paragraph on a given topic. While you deal with the same HotDocs language building blocks in HotDocs fields as you do while writing a script, they are packaged differently. The statements in a script are written to complete a specific task that is likely unrelated to the aims of the next field in the template.
Another difference between the fields in a template and the lines in a script is that in the HotDocs Field Editor, HotDocs provides you lots of support to guide you through the creation of the field's statement. In a HotDocs script, while there are writing aids (covered below), you are much more free to compose your logic in whatever way seems best to you.
To write a script, you first need a clear idea of the actions you want HotDocs to take – say you want to HIDE a variable on a dialog until your template user responds to a related variable's prompt. You then need to think logically about the steps required to achieve this (placing the variable to HIDE within an IF condition so that it only appears if a template user's answer to the related variable meets the condition that causes HotDocs to SHOW the first variable). Once you have a clear idea of the process you want HotDocs to undertake, you need to translate those steps into the appropriate instructions, functions and operators of the HotDocs scripting language so HotDocs can accomplish the tasks you want it to.
Suppose, for example, you need some of the variables in your template to appear in the interview only if your template user is from Hawaii. One of the things your script would need to do is check the answer to a variable asking for your template user's address to see if the address is in Hawaii. If the address is in the state of Hawaii, you would then instruct HotDocs to display any Hawaii-specific variables in the interview.
In plain terms, you want to tell HotDocs to:
Once you formulate what you want HotDocs to do in clear language, you can further shorten the clauses like this:
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:
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.
When you want to write a script, you don't have to start from scratch and try to remember exactly how to format scripts. Instead, you can use a model (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.
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. You initiate the auto-complete behavior by first placing your keyboard focus in a Script tab or expression editor, and then pressing 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:
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, OTH while 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.
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.
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
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:
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.
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.
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.
If you want to practice creating a dialog script, follow the steps below:
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.
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.
When you are creating a computation, you need to set the computation’s result type. This can be:
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.
If a variable name is not within chevrons, HotDocs uses the variable name—not the variable's value—as the answer.
Among others, the following reference topics relate to this conceptual area: