Local Variables

When writing more complex computation scripts, you may need to create temporary or special-purpose variables that are only used or needed in a particular computation or dialog script. Such temporary variables create a maintenance burden since they always show up in component lists and can require extra explanation for whoever maintains your templates in the future. To make your HotDocs scripting more maintainable, and easier to read, use local variables in these situations.

A local variable is somewhat similar to a regular variable, but instead of being usable anywhere in your template, it is only defined in the "local" context of a specific computation or dialog script. Local variables are useful in scripting situations where you would otherwise resort to defining a regular HotDocs variable just to keep track of temporary information that is not meaningful anywhere else but in this one script.

As an example, suppose you're writing a computation to remove spaces that may have been entered as part of an account number.  You could do this using a WHILE instruction (link) to loop through each character of the account number, removing spaces as you find them:

SET Index TO 1

WHILE Index <= LENGTH( Account Number )

IF MID( Account Number, Index, 1 ) = " "

SET Account Number TO FIRST( Account Number, Index -1 )

+ LAST( Account Number, LENGTH( Account Number) - Index)

ELSE

INCREMENT Index

END IF

END WHILE

Notice how this script relies heavily on the “Index” number variable. It keeps track of our position as we look through each character in the account number. This is a good example of a variable that should be defined “locally” instead of being defined in the Component Manager (as you would have done in earlier versions of HotDocs). As a local variable, Index is meaningful (and has an answer) only in the context of this script. You can create a local variable called “Index” in another computation as well, but the two would be isolated: setting one computation’s local Index to a certain value would have no effect on the other computation’s local Index. In fact, local variables do not store their answers in the answer file like regular HotDocs variables. These answers are stored in a special temporary location and are discarded as soon as the computation or script finishes running.

Here is a table that summarizes the differences between traditional HotDocs variables and local variables:

You can use regular HotDocs variables (perhaps with “Ask automatically”, “Warn when unanswered” and “Save in answer file” all turned off) in every instance where you could use a local variable. However, there are advantages to using local variables when possible, and these advantages become more significant as your template automation projects grow larger and more complex:

• Large or complex component files are easier to maintain when component lists are not cluttered with temporary variables.
• Naming local variables is easier, and scripts using local variables can be easier to read, because the name only has to make sense in the context of the script where it’s defined and not in a global component list.  In the above example, it is realistic to call the local variable “Index” instead of needing to call it “Account Number Index Temp,” for example.
• Reusing components by copying them from one component file to another becomes less complicated because such copy operations no longer need to bring along additional temporary variables.

To Create a Local Variable

1. Insert a variable, selecting Computation as the variable type.
2. At the Variable Field dialog box, click the Edit Component button to open the Computation Editor.
3. Click on the Locals tab.
4. Create a local variable
   1. Clicking the left-hand column of the Parameter table and enter a name
   2. Click the right-hand column to select the type of variable this will represent.
5. Click the Properties tab and enter the computation you want to use your local variable in. Drag and drop from the Parameters and Local Variables list at the bottom left.

You can tell at a glance whether local variables or parameters have been defined for the current computation or dialog script by looking at the Locals tab.  If the Locals tab has an asterisk (*) on it, at least one local variable or parameter has been defined.

To view the defined local variables and drag them into your script as necessary, choose “Parameters and Local Variables” from the Components drop-down in the bottom left of the script editor.

You can define a local variable that has the same name as a regular variable elsewhere in the component file.  In such a situation, HotDocs recognizes the local name before looking for the other component. For example, suppose you have a computation variable that defines a local variable called “Temp Number,” and there is also a number variable called “Temp Number” defined in Component Manager.  If you refer to “Temp Number” within the computation where the local is defined, you will get the local answer associated with it.  However, referring to “Temp Number” in the template, or in another script, will retrieve the regular answer from the answer file.