Parameters

When building complex templates or template systems, you may need to duplicate portions of script or logic multiple times. These duplications may be exact or with minor changes. Duplicating script or logic makes templates difficult to maintain because as times goes by and the logic needs refinement, you may introduce errors if you do not update each instance of the logic consistently. To make your HotDocs scripting more maintainable, and often easier to read, encapsulate reused logic in computation variables that use parameters.

 

A parameter is like a local variable for a computation, but instead of initializing the parameter in your script (as you might initialize a local variable using the SET instruction), the initial value of the parameter is copied into your computation from wherever the computation was invoked.

 

For example, this computation determines whether a particular child is under 18 years of age:

Computation name: Decedent Child Under Eighteen

Script:

AGE( Decedent Child Birthdate ) < 18

The part of the script that determines whether a child is a minor may need to be duplicated in numerous places.  You could define similar computation variables that only differ in the date variable to which they are referring, causing unnecessary extra work and cluttering up your components list, or you could use parameters.

 

Parameters allow you to write the logic only once:

Computation name: “Under Eighteen”

Parameter: “person” (Date)

Script:

AGE( person ) < 18

Instead of referring to another date variable (“Decedent Child Birthdate” in the former example), the computation refers to a local parameter. So, whenever this latter computation is referred to, instead of simply referring to it by name, we must also provide a date as “input” to the computation:

Under Eighteen ( Decedent Child Birthdate )

The very same computation can be referred to (“called”) from elsewhere using different date variables or date expressions:

Under Eighteen ( Beneficiary Birthdate )

Under Eighteen ( Beneficiary Birthdate + 5 YEARS )

 

In this way, parameters essentially allow you to write computations that work much like HotDocs’ built-in expression models. They allow you to re-use script logic rather than duplicating entire computation variables to perform the same action on different values. This is very much like defining functions within other programming environments.

As a more complex example, let’s consider a longer computation that calculates the date of the nearest Monday on or after a given date.  It uses a parameter and a local variable.

Computation Name: “Next Monday”

Parameter: “origin date” (Date)

Local Variable: “days away” (Number)

Script:

// Find the number of days between origin date and Monday (which is day of week no. 2)

SET days away TO (2 - DAY OF WEEK( origin date ))

// If origin date is later in the week than Monday, add 7 days to get to next week

IF days away < 0

SET days away TO days away + 7

END IF

// calculate the date

origin date + days away DAYS

A computation with parameters can be referred to (called) from any other computation or script. It can also be used in merge fields, either directly in a template or in literal text: «Next Monday(TODAY):04 July 2012» will use the above computation variable (Next Monday) to calculate the next Monday after the current date (TODAY), format it according to the given format example (04 July 2012), and merge the result wherever the field appears (whether in a template, prompt, resource, etc.).

When you add, remove, or change the parameters of a computation, you are changing the way that computation is referred to by its callers. In this way, changing the types or order of a computation’s parameters is akin to changing the computation’s name: care should be taken to not break things.

For users with a prior knowledge of programming it may be useful to think of HotDocs Parameters as Value Parameters. Therefore any change made in the script does not change any variable that has been passed in when calling the computation.

Computations used as filters on REPEAT instructions are not permitted to have parameters.

To create a computation variable that accepts a parameter:

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 and create a parameter by clicking on the left hand column of the Parameter table and entering a name, then the right hand column to select the type of variable this will represent.
4. Click on the Properties tab and enter the computation that you would like your new parameter to complete. In the computation use the parameter (drag and drop from the Parameters and Local Variables list at the bottom left) as the placeholder for the variables you would like to use later.
5. Click OK on the open dialogs to return to the template.

To use this computation variable from another computation or script,

1. Open the Computation Editor for the computation from which you wish to use your computation with parameters.
2. From the list of Available Components in the lower left corner, drag and drop your computation with parameters into the script.  HotDocs will automatically generate placeholders for each of the parameters required by the computation.
3. Drag and drop variables or values to replace the placeholders as you would do when replacing placeholders for the built-in expression models.

To use a this computation variable from a field in a template

1. Click on the Variable Field button on the HotDocs tab and select Computation from the Type list.
2. At the Variable field use the drop-down list to find and click on the parameterized computation. You will now see a table with available parameters, and an empty Expression column.
3. Click the button to the right of the table and drag the variable you would like to use from the Variables list up into the Expression field. (You can also manually enter or edit expressions here.)

To test a computation that includes parameters

1. Create a computation that includes parameters.
2. Click the Test button.
3. To facilitate testing, HotDocs presents an automatically-generated dialog to gather values for the computation’s parameters. Enter a value for each parameter.  (Note that this dialog is only part of a test assembly for the computation.  In actual usage, the call to the computation would specify the parameter values.)
4. If your computation causes subsequent dialogs to be asked, enter values for those additional variables as well.
5. Switch to the Result tab as necessary to view the result of your computation given the values you entered.
6. Switch back to the Interview tab to test results given other input.

Just as with regular computations, you can also use the DEBUG instruction to step through a computation line by line and observe how the values of parameters and other variables are affected by your script.