Parameters Overview
A Parameter is a named placeholder for a value a function needs to calculate its result. For example, the system function, TRIM has a single parameter called "text" that requires you to provide the string of text as the value you want the function to act on (trim white space from the beginning and end of the text string) to return the trimmed text as its result.
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 computations that use parameters.
A parameter is like a local variable, 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 computations 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’ system 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 placeholder 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 (04 July 2012), and place the result wherever the field appears (whether in a template, prompt, Additional Information field, 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 or to generate the assembled document name are not permitted to have parameters.