The HotDocs Computation Archive

Tut. 02 - The Computation Variable


An introduction to the four types of computation variables: text, number, date and true/false.

!!! Introduce SET here right after introducing variables. How to give the container contents: usually comes from the interview but you can fill it yourself.

• Introduction •

In the previous tutorial, you were introduced to the four types of information that HotDocs understands, or the four data types. In this tutorial we get hands-on experience seeing how HotDocs interprets and uses each of these kinds of information.

Section 1:  The Computation Variable - Let the Title Be Your Guide

In HotDocs, create a new computation variable. Call it whatever you wish. This is for experimentation as we go along. If you do not know how to create a computation variable, just edit a HotDocs template or create a new template (your manual will explain this), click the Insert Variable button on the HotDocs toolbar (it looks something like this: « » ), and select Computation.

When you create the computation, you will see a dialog that has a large text-entry area. This is where you create the script, or the computation. The first thing that you should notice is the title bar at the top of the dialog. It should say [Text] or Text Computation Variable.

In turn, type each of the following in the script area (removing the previous text each time), and notice how the title bar changes:

Type the items in green: The title bar should display:
x Invalid
Orange Sherbet Invalid. Why? A text string must always be enclosed in quotation marks
"Orange Sherbet" Text
"You are ... " + "what you eat" Text
Click the "Test" button (and the "Result" tab in HD 6 or higher; do this whenever asked to test a script). You will see that the result is You are ... what you eat
4 Number
4,000.00 Invalid
4,000 Invalid. Why? Only a decimal or a negative sign can be used with a number
4000.00 Number
4000 + 400 Number
Click the "Test" button (... and the "Result" tab for HD 6 or higher; always do this when looking at a result. We won't mention this step again.) You will see that the Result is 4400
4000 + 400 = 1 True/False. Why? Equations that include the answer will always be TRUE (correct) or FALSE (incorrect)
Click the "Test" button You will see that the answer is false. 4000 + 400 does not equal 1
01 JAN 2000 Date
1 JAN 2000 Invalid
01 jan 2000 Invalid. Why? Dates must be in the format: DD MMM YYYY, where "MMM" is the first three letters of the month in all-caps
01 JAN 2000 Date
Click the "Test" button You will see that the result is January 1, 2000, which is the default display format for dates
FALSE True/False
true Invalid
True Invalid. Why? True/false values must be in all-caps
TRUE True/False
"Orange Sherbet" Text
"Orange Sherbet" = "Dessert" True/False
"Orange Sherbet" = "Sherbet" True/False
Why isn't this a Text computation variable? All comparisons are either TRUE or FALSE
Click the "Test" button You will see that the result is false. The strings "Orange Sherbet" and "Sherbet" do not match character-for-character
"hunger" = "HUNGER" True/False
Click the "Test" button You will see that the answer is true. Why? Letter case is irrelevant when comparing strings. Other than letter case, the strings are identical
Summarize the purpose of the messages on the Title Bar The Title Bar provides two pieces of information: 1) The data type of the computation, and 2) whether the script has any errors

• Explanation •

Computation Variable Basics. You have created your first HotDocs scripts. We are working in the "computation editor" because it is an area where we can work interactively with HotDocs and get immediate feedback.

You have now seen that HotDocs can understand four types of information: text, numbers, dates, and true/false values. Note that HotDocs automatically recognizes what kind of information you are working with. As you saw in the previous exercises, as you changed the type of data or information you fed to HotDocs, it changed the title bar accordingly.

What you have been creating is called a computation variable. In other words, it is data that is computed from values, formulas and commands that you provide. The result or output of a computation variable is a value that is suitable for use in your document. As an aside, try the following:

Type your favorite food or dessert in the script area (remember to put it between quotation marks). You now have a text computation. Click on the down arrow of the drop-down list called "Format Example" or "Default Format" and notice that the formatting models are appropriate for formatting text. Select "LIKE THIS" and click the "Test" button. You will see the result of the computation formatted in ALL-CAPS.

Replace the computation script with your birth date in proper date format (DD MMM YYYY). Inspect the "Format" options again. They are now date formatting models. Select one and then click "Test" to see what value is returned by the computation. Try a few formatting examples.

Now change the computation script to any number you wish. Inspect the "Format Examples" and notice that they are now appropriate for number formatting. "Test" a few of these.

Section 2:  Providing Changeable Data

In your computation editor, select Text on the drop-list called "Variables" or "Components." Click the New button by the list. A variable creation dialog will appear. For Variable Name type TextVar. For Prompt, type Enter some text. Click OK.

Repeat the above procedure, selecting Date, Number, and True/False on the list and creating a New variable for each, calling them DateVar, NumVar, and TFVar, and giving each Prompt text appropriate to its data type ("Enter a number," etc.).

In turn, type each of the following values in the script area (replacing the previous text each time), and notice how the title bar changes:

Type the items in green: The title bar should display:
TextVar Text
"You are ... " + TextVar Text
Click the "Test" button and give an answer You will see that the result is You are ... [your answer to TextVar]
NumVar Number
NumVar + 4000 Number
Click the "Test" button and give an answer The Result is the sum of 4000 and your answer to NumVar.
TFVar True/False
Click the "Test" button and give an answer The Result is your answer to TFVar
DateVar Date
Click the "Test" button and give an answer The Result will be your answer to DateVar
What is a variable? A text, number, date or true/false value which can vary
"Chocolate " + NumVar Invalid
DateVar - NumVar Invalid
Why are the above invalid? You cannot mix and match different types of information

• Explanation •

In all of our examples until now, we have used static information, meaning that the dates, text, numbers, etc. were typed directly into the computation and would never change. This is not very useful in real life. This section introduces variable information, or in HotDocs jargon, variables. A variable is a holder for a specific type of information: text, number, date or true/false. As a holder, its contents can change. You might think of a variable as an empty box that can be filled, emptied, and re-filled. The contents usually come directly from the user, as you saw above.

When you use a variable in a computation, it is exactly as if you had placed a text, number, date or true/false value in the computation. When HotDocs encounters the variable, it will ask the user what the value should be. This value is then used in place of the variable. We will cover variables in much greater depth later on.

Section 3:  Remember the RESULT

In turn, type each of the following values in the script area (replacing the previous value as you go), and click the Test button to see the computation's result.

Type the items in green: Click the "Test" button:
1 1
Explain what RESULT is RESULT is the current answer of the computation
RESULT + 0.15
1. Why? The first answer, 10, was discarded and replaced with 20. The new RESULT, 20, was added to 30, bringing RESULT to 50. This answer was then discarded and replaced with 1
140. Why? RESULT carries the total forward. Line-by-line, here is what HotDocs sees:
50 + 40
90 + 30
120 + 20

And 120 + 20 provides the final answer: 140.
"Eat Chocolate" Eat Chocolate
"Eat Chocolate"
"Drink Chocolate"
Drink Chocolate
Rewrite the previous script so that it carries the answer forward "Eat"
RESULT + "Cholocate"
RESULT + "Cake"
Testing the modified script, what is the answer? EatChocolateCake
Change the script so that there are appropriate spaces One way is:
"Eat "
RESULT + "Cholocate "
RESULT + "Cake"
RESULT + " "
RESULT + "Turnover"
Apple Turnover
"Apple" + " " + "Turnover" Apple Turnover
"Apple Turnover" Apple Turnover. Always choose the most straightforward method!
"Cherry Pie"
Cherry Pie
"Cherry Pie" Cherry Pie
"Pumpkin Pie"
Pumpkin Pie
"Pumpkin Pie" Pumpkin Pie
Is it necessary to place RESULT at the end of the script? No. RESULT automatically becomes the answer for the computation
Explain when you should use RESULT Use RESULT any time you wish to carry forward the current answer, either to add to it or to alter it

• Explanation •

The main purpose of a computation is to manipulate information. In other words, it computes new information based on the information you give it. In HotDocs jargon, the computed result is known as the computation's Answer or Result. The answer may be some new text, a new number, a new date, or a true/false value.

There is an important lesson to learn about answers from the exercise above, so take careful note of it: a computation's answer is replaced every time you give it new information. That may well go against your sense of reason. In mathematics, an answer is cumulative. But not so in HotDocs. The computation's answer is replaced every time you provide new information. Forgetting this one point has caused endless grief for beginners.

A computation's answer will change from line to line. To carry the current answer forward, always use RESULT + Additional Value.

That covers the fundamentals. Now we will look more carefully at each type of information, or data type: text, number, date, and true/false.

•  •  •  •  •  •  •


• Contributors •