Lesson 7: Create Computation Variables

Overview

Some new Hobble Creek Publishing employees may need to complete a six-month probation period. When this probation period ends, however, depends on the employee’s first day of work.

In this lesson, you will use the HotDocs scripting language to calculate the date the probation period ends for new employees.

Like any language you speak or write, the HotDocs scripting language includes words, constructs, and rules you must follow in order to effectively execute a script. This syntax ensures that HotDocs will know how to process your script accurately. Failure to follow these rules may result in syntax errors when HotDocs attempts to process it. Fortunately, HotDocs includes several tools to help you learn how to use this language. You will learn about these tools in this and subsequent lessons.

There are certain words that represent certain things or tasks in the HotDocs scripting language. These words can be broken down into the following groups, or types:

• Instruction keywords tell HotDocs to perform some sort of function or opera­tion. For example, the INSERT instruction keyword tells HotDocs to insert another template in the current template.
• Expression keywords are used to generate an answer or retrieve a value. For example, the expression DATE + NUM MONTHS returns a date some number of months in the future.
• Operators are symbols or words that cause an operation such as addition or a comparison to be performed in a script. Most operators are common mathemat­ical signs, but there are also Boolean operators such as AND and OR that allow you to compare different values.
• Most instructions and expressions require values. A value is a user’s answer to a variable or other data which is needed to complete the expression or instruction so it can be processed or executed. Values are typically represented by variables, but they can also be literal text strings, numbers, file names, or even other expressions.

Using these different parts of the scripting language, you can begin creating scripts. To assist you with this, HotDocs provides instruction and expression models. A model is a pattern that shows exactly how the instruction or expression must be used. A model consists of the instruction or expression keyword(s) and placeholders, which you replace with variables, predefined answers, or other models.

There are two methods for writing a computation script:

• Using the instruction, expression, and component lists at the bottom of the Computation Editor, you can drag models and components from these lists and drop them into the script. This is useful if you are learning the scripting lan­guage, since it provides accuracy and helps you learn the syntax for using instructions and expressions. (You will use this method in this lesson.)
• You can type the script directly in the Script box. While doing this, you can access auto-complete lists that let you type a partial keyword or component name, then press a combination of keys to have HotDocs display a list of keywords or components it thinks you’re trying to enter. You can then select the keyword you want and HotDocs will merge it into the script. This method is useful for those more familiar with the scripting language. (You will use this method in later lessons.)

Start the Tutorial

If you are continuing immediately from Lesson 6, skip the instructions for opening the template and proceed to “Insert an Expression Model in a Computation Script.”

If you closed the template at the end of Lesson 6, complete the following steps.

Insert an Expression Model in a Computation Script

In the first paragraph of the Duration of Employment section, there is a date, August 1, 2009. This date falls on the first day of the sixth month of employment. You will create a Computation variable that calculates this date for the user. You will use several expression models to create the script.

To insert a Computation variable that produces a date

To make your work in this part of the tutorial easier, you can click and drag the lower-right corner of the Computation Editor to make it larger.

1. Select the text August 1, 2009.
2. Click the Variable Field button. The Variable Field dialog box appears.
3. Select Computation and type Probation End Date in the Variable box.
4. Click the Edit Component button. The Computation Editor appears.

   In this script, you will use the DATE OF ( NUM, NUM, NUM ) model, which lets you examine the different portions of a date (day, month, and year) and assign specific values to each portion. The resulting date value can be merged into the assembled document.

5. Scroll through the Expression models list until you see DATE OF( NUM, NUM, NUM ). (Expression models are arranged alphabetically.)
6. Click the model, drag it into the Script box, and release the mouse button. The expression is inserted in the Script box.

Replace a Script Placeholder with a Value

To help you identify which portion of the script you must replace with values, HotDocs assigns a different color to the placeholders. As you see, the DATE OF expression has three placeholders for required number values, which represent the day, month, and year, respectively.

You know the probation period ends on the first day of the month, so you want the first NUM placeholder to be replaced with 1. One way to enter a number in a computation is to use the Enter a Number expression model.

To replace the DATE OF expression with a Number

When you use numbers in scripts, they must be for­matted a certain way. Using the Enter a Number model lets you type a number and have HotDocs format it for you. This reduces the chance of error when HotDocs tries to process your script.

1. From the list of Expression models, drag Enter a Number (located near the top of the list) and drop it onto the first NUM placeholder.
   

   The Enter a Number dialog box appears.

2. Type 1 and click OK.
   

   The number 1 replaces the first NUM placeholder.

Replace Placeholders with Other Expressions

You can also replace placeholders with other expressions.

The second NUM placeholder represents the numeric equivalent of a month. You cannot simply enter a number like you did for the day, because the month you want depends on the date the employee starts working. Instead, you should use the MONTH OF( DATE ) expression, which examines a date and returns the numeric equivalent of the month.

The MONTH OF ( DATE ) model returns a number value that corresponds with the month portion of the date the user enters. For example, if a user types July 1, 2007, this expression returns a value of 7, since July is the 7th month of the year.

To replace the placeholders in a computation with other expression mod­els

1. Drag MONTH OF( DATE ) from the Expression models list onto the second NUM placeholder.
   

   The DATE + NUM MONTHS model takes a date and adds a specified number of months to it. For example, if a user’s answer to a date question is March 17, 2007 and six months needs to be added to it, then this expression returns the result of September 17, 2007.

   You want the MONTH OF expression to return the number for the month six months after the employee starts working. In other words, you want to add six months to the employee’s start date. The DATE + NUM MONTHS expression helps you do this.

2. Drag DATE + NUM MONTHS onto the DATE placeholder that is in the parentheses following MONTH OF.

   Your script should look like this:

Replace a Placeholder with a Variable

Placeholders are often replaced with HotDocs variables. The DATE + NUM MONTHS expression has two placeholders—DATE and NUM. (MONTHS is a keyword that remains in the finished script.) The DATE placeholder needs to be replaced with the date the employee started working.

To replace a placeholder in a computation with a variable

1. Drag Start Date from the Components list onto the DATE placeholder.
2. Using the Enter a Number expression model, replace the NUM placeholder in the DATE + NUM MONTHS expression with the number 6. HotDocs will add six months to the Start Date. Your script should now look like this:

On Your Own

The YEAR OF ( DATE ) model operates similar to MONTH OF ( DATE ) model. Here it is used to make sure the correct year is returned for the new date.

Replace the remaining NUM placeholder in the script with YEAR OF( Start Date + 6 MONTHS). (Follow all of the instructions for replacing the second NUM placeholder in the expression given earlier.)

When you are finished, the script should look like this:

To summarize, this script produces a date that falls on the first day of the month, six months after the employee started work. The first value in this script, 1, specifies the first day of the month. The second value, MONTH OF( Start Date + 6 MONTHS ), determines the month of the start date and adds six months to it. The third value, YEAR OF (Start Date + 6 MONTHS ), determines the year of the start date (plus six months).

Test the Computation

Because some computation scripts can be quite complex, it is often helpful to test a computation script to make sure it calculates the correct result.

To test the Computation variable

1. At the Computation Editor, click Test. HotDocs opens a test assembly window showing the Start Date variable.
2. Type 5/12/2010 in the Start Date answer field and click the Result tab. HotDocs keeps you in the dialog to show you it has reformatted the answer you entered.
3. Click the Result tab again. HotDocs displays the answer November 1, 2010. This is the date the new employee’s probationary period ends. This is correct.
4. Click the Interview tab and change the date to 7/12/2010.
5. Click the Result tab twice. HotDocs displays the updated answer January 1, 2011.
   

   HotDocs correctly calculates the date here as well, because the script uses the Start Date + 6 MONTHS expression for both the month and the year.

6. Close the test assembly window to return to the Computation Editor, and then click OK.
7. At the Variable Field dialog box, click Replace Once. The variable is inserted in the template.

   Now when users assemble this document, HotDocs is able to calculate the day the probation period ends.

Conclusion

You are now finished with this lesson. In it, you learned how to create a Computa­tion variable that uses expression and instruction models to calculate a date in the future.

If you do not want to go on to Lesson 8 at this time, click the HotDocs Save and Close button to close the template. Then exit HotDocs.

If you are continuing on to Lesson 8, click the Save button to save your work.