Number Variable Overview

A Number variable is a type of variable that represents an unknown number value. For example, if you want to ask a template user for a loan amount, you would create a Number variable in your template to capture that specific item of data.

Overview

In HotDocs, a Number variable is a component that represents unknown numerical content in your template (i.e. a number value, such as currency, decimal number, or other amount that can be calculated). You can create Number variables using the HotDocs Field Editor or Component Studio and Number variables are typically:

Referenced in the template by adding a placeholder field, indicating where HotDocs must place the variable's number value in the assembled document
Added to a dialog, so the variable's question appears in the interview; template users can then type the value allocated to the variable
Used in a computation to supply an item of data used by the computation's script

Like other components, Number variables have properties that you can set to define how they perform in an interview and how HotDocs processes the Number variable in an assembled document. In fact, Number variables have a number of unique properties, which you can review below.

Common Tasks

Among others, Number variables enable you to accomplish the following common tasks:

Workflow

When you create a template from an existing document, the existing document usually contains placeholders for the numerical content that is unknown. To enable template users to provide the unknown numerical content, you:

Create new Number variables to represent the individual unknown number values (either in the Field Editor or Component Studio)
Replace all placeholders in the template with placeholder fields that reference your variables

When creating a Number variable, you can set properties that define how to gather an unknown number value from a template user, how HotDocs stores that number value as an answer, and how to format that answer when assembling a document. For example, you start by setting the name property for the Number variable, which is used to identify the Number variable throughout Author and in the answer file. You can set the Prompt property to provide instructive text (as opposed to the Number variable name) to help a template user answer a question during the interview. You can set the Default format property to define the pattern that HotDocs uses to format the template user's answer in the assembled document (such as a whether or not to include commas in the number). Lastly, you can then group related number (and other) variables into dialogs to improve the usability and flow of an interview.

Once you have created the Number variable and set all of the properties you need, you can use the test feature to ensure the variable will behave as you desire when the document is assembled.

Number Variable Properties

Like all variables, Number variables have properties you can use to edit how the Number variable appears in an interview, how the Number variable is processed during assembly, etc. In addition to the properties common to all variables, Number variables have the following unique properties:

Display decimal places – Enables you to choose the number of places after the decimal point you want HotDocs to display and round to
Units – Enables you to choose characters (e.g. a currency symbol) you want to appear to the left of the answer text box in the interview
Minimum – Enables you to set a minimum value for an accepted answer
Maximum – Enables you to set a minimum value for an accepted answer

When to Use Number Variables

To better understand when to use a Number variable (as opposed to the other types of variables), consider the following:

A Number variable is a type of variable that represents an unknown number value (e.g. values that can be used in arithmetic, such as loan amounts, client age, etc.)
A number value is any value that you can express using only numeric characters. For example, you would use a Number variable to gather an amount of currency (such as 950), but not a value that contains a combination of text and numbers (such as an ID number like A236ABC)
With the exception of commas and periods used as thousands separators or decimal points, you cannot use a Number variable to gather answers with any non-numeric characters (such as a letter, dash, hyphen, colon, etc.). For example, you do not use Number variables to gather values that contain hyphens (e.g. the Social Security number 555-55-5555) or values that contain colons (such as the time of day 12:30), even though these values are often thought of as "numbers." For values with hyphens and colons, use a text variable with the appropriate input mask.

Number Variables and Formats

When working with Number variables, there are times when you may want to control how a template user's answer to an interview question is displayed in an assembled document. For example, you may want currency amounts entered with commas (e.g. 9,999) to appear in the assembled document without commas (e.g. 9999) or spelled out in full (e.g. Nine Thousand Nine Hundred and Ninety-Nine). HotDocs enables you to make such modifications to answers based on Number variables using number formats. To assist you in using number formats, HotDocs provides a set of commonly used number formats (such as formats that enable you to use round to the nearest whole number, remove zeros entered, and more) when you install Author.

You can either format a single instance of the placeholder field that references the variable, or you can format every placeholder field that references that variable throughout the template. You can also create your own custom format, should you need a format not included in the commonly used formats.

For more information on formats, you can read the Formats Overview and the Formatting an Answer document for more information.

Common Reference Topics

Among others, the following reference topics may relate to this conceptual area: