Models Overview
A model is a pattern that teaches you proper HotDocs scripting language syntax for an instruction or function or operator. For example, the model for the ASK instruction is ASK ⟦VAR,DIALOG⟧, while the model for the ANSWERED function is ANSWERED (⟦ v:VAR,DIALOG⟧).
Overview
You use models when you are writing a HotDocs script. Using models helps you to learn the syntax HotDocs expects you to use when using instructions or system functions to create a script.
Models appear on the Models tab of the Script editor. Most models include red placeholder text (see examples above) to indicate the type of item you need to add for the instruction, function or operator to work, as well as the location you need to place the item in the instruction, function, or operator. A model's placeholders can include certain value types, variables, or dialogs.
You most often replace value-type placeholders within a model with:
- Literals
- Variables (of the appropriate value type)
- Other models that represent either system functions or operators
You can substitute a value type in a model with any expression that evaluates to the type the model specifies.
There are two type of models in HotDocs Author:
Common Tasks
Among others, models enable you to perform the following common tasks:
Workflow
When writing a script (whether a computation or a dialog script), you can find the Models tab to the right of the Script tab. Once you determine the name of the function or instruction you want to use to achieve your goals, you can drag and drop the model for that item directly onto the Script tab. Once there, you can select any placeholder that model may have, then either type the expected item, or drag that item from either the Component tab, or if appropriate, another model from the Models tab.
Instruction Models Versus Expression Models
When you encounter a model that shows two red placeholders separated by a comma, it indicates two different things, depending on whether the model is an instruction model or a function model.
Instruction Models
An instruction model is a model demonstrating proper syntax for an instruction. The red placeholder indicates the item the instruction needs to operate on to complete the task the instruction encapsulates. For instance, the GRAY instruction has a single placeholder as follows:
GRAY ⟦VAR⟧
The ⟦VAR⟧ placeholder enables you to drag and drop the variable (or type the name of the variable) that you want HotDocs to gray-out and make unanswerable on the dialog where you add this instruction. The variable is the item the instruction acts on.
Also, with instructions, two red placeholders separated by a comma indicate that you should replace either placeholder (but not both) with the appropriate item, as with the ASK instruction model:
ASK ⟦VAR,DIALOG⟧
To satisfy the syntax of this model, it is sufficient to drag either a variable or a dialog from the Components tab onto the placeholder for VAR. When you do, the placeholders for both items disappear, leaving only the blue colored text for the name of the item you dragged onto the placeholders.
You can further distinguish an instruction model from an expression model because the instruction keyword by default appears in bold font.
Expression Models
An expression model demonstrates proper syntax when building an expression that uses system functions or operators (or any calculation that produces a value). The red placeholders indicate something very different for expression models than they do for instruction models. In the case of a system function, the red placeholders indicate the parameters the function takes as input. Rather than acting upon these items, the function needs them to perform its task and calculate a value.
Multiple Parameters
With expression models, the comma does not always indicate an either or situation (though it may do so). The comma can indicate that the function requires more than one parameter.
If the comma is outside the brackets that surround every placeholder (and thus there are multiple red placeholders, and the comma between the placeholders is black), then there are multiple parameters, and you need to replace the placeholders for each parameter, as with the MONTHS FROM function:
MONTHS FROM (⟦start:DATE⟧, ⟦finish:DATE⟧)
If the comma is red and located inside the brackets of a single placeholder, then there is only one placeholder to replace, and the comma indicates there is more than one option available you can choose from to replace that single placeholder with, as with the ANSWERED function:
ANSWERED (⟦v:VAR,DIALOG⟧)
There are also functions with multiple parameters where some of the parameters are optional. In such cases, these parameters do not show up when you drag the model onto the Script tab (though they do show up on the tool tip for that model when you hover your mouse over the model), as with the POSITION function:
POSITION (⟦in:TEXT, search for:TEXT⟧)
Such optional parameters do, however, appear in the documentation, as with the optional parameter "last instance: TRUE_FALSE" for the POSITION function. To be sure you understand all the parameters available for any function, you should always read the documentation for that particular function.
Common Reference Topics
Among others, the following reference topics may relate to this conceptual area: