Text Variable Overview
A Text variable is a type of variable that represents an unknown text value. For example, if you want to ask a template user for their first name you would create a Text variable in your template to capture that specific item of data.
Overview
In HotDocs, a Text variable is a component that represents unknown text content in your template (i.e. a text value, such as a client name or business address, yet to be entered by the template user or computed by a computation). You can create Text variables using the HotDocs Field Editor or Component Studio and Text variables are typically:
- Referenced in the template by adding a placeholder field, indicating where HotDocs must place the variable's text 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, Text variables have properties that you can set to define how they perform in an interview and how HotDocs processes the Text variable in an assembled document. In fact, Text variables have a number of unique properties, which you can review below.
Common Tasks
Among others, Text variables enable you to accomplish the following common tasks:
- Adding a Placeholder Field for a Variable
- Creating a Prompt for a Variable
- Formatting an Answer
- Editing a Component
Workflow
When you create a template from an existing document, the existing document usually contains placeholder text for the text that is unknown. To enable template users to provide the unknown text, you:
- Create new Text variables to represent the individual unknown text values (either in the Field Editor or Component Studio)
- Replace all placeholder text in the template with placeholder fields that reference your variables
When creating a Text variable, you can set properties that define how to gather an unknown text value from a template user, how HotDocs stores that text 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 Text variable, which is used to identify the Text variable throughout Author and in the answer file. You can set the Prompt property to provide instructive text (as opposed to the Text 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 all caps). Lastly, you can then group related text (and other) variables into dialogs to improve the usability and flow of an interview.
Once you have created the Text 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.
Answer Suggestions
Text variables have a unique feature—known as answer suggestions—that enable you to help a template user more quickly answer an interview question by presenting a list of suggested text values that the template user can (but is not required) to choose from. For example, assume you want to ask the template user what one person's relationship is to another. Using answer suggestions, you can provide them a list of likely answers to choose from (mother, father, son, etc.) but also provide them a way to type their own answer (in case the user needs to enter a value outside of the suggested ones). You can style answer suggestions, and the way that the answer control is presented in the interview, in one of two following ways:
- A drop-down list control that includes a list with suggested values you specify (mother, father, son, etc.) and an editable text box where the template user can type their own answer
- A single or multi column set of buttons with one button for each suggested value you specify (mother, father, son, etc.), and an "other" option button that, when selected, enables the template user to type their own answer into an editable text box
You can access the answer suggestions feature in the Text variable's component editor. From the editor, you can perform the following tasks necessary to use answer suggestions:
- In the Display tab, set the Style on Regular Dialogs property to Single line with answer suggestions
- Set the Option source property, which designates which component contains the source of the options you wish to present as suggestions.
- Using the Suggestion text property, select the column of data from the Option Source that contains the options you want to display suggested answers
- As mentioned above, and using the Style property, select the visual style of the answer suggestions and the answer control
To learn more about the options you have for displaying suggestions to your template users, you can review the settings documented in the Text Variable Editor.
Text Variable Properties
Like all variables, Text variables have properties you can use to edit how the Text variable appears in an interview, how the Text variable is processed during assembly, etc. In addition to the properties common to all variables, Text variables have the following unique properties:
- Style on regular dialogs
- Single line – limits, to a single line, the text box that template users type their answer in during an interview
- Input mask – enables you to ensure your template user provides an answer in the correct form when answering a Text variable in an interview
- Single line with answer suggestions – enables you to suggest answers (that you define) to the template user when they are answering an interview question based on the current Text variable
- Suggestion text – enables you (once you have selected a source) to designate any column of data from the Option Source to display as possible answers to your template users in the interview; if you do not do this, the suggested text comes from the column you marked as a key in the option source
- Multi line – enables you to increase, beyond a single line, the size of the text box that template users type their answers in during an interview and to control the paragraph behavior
- Answer text box height – enables you to set the number of lines that the answer text box displays at during the interview
- Multi paragraph – enables you to control how HotDocs places an answer into a document when the template user presses Enter in a multi-line answer field
- Single line – limits, to a single line, the text box that template users type their answer in during an interview
- Length (characters maximum) – enables you to control the number of characters HotDocs allows in the answer
When to Use Text Variables
To better understand when to use a Text variable (as opposed to the other types of variables), consider the following:
- A Text variable is a type of variable that represents an unknown text value (such as a template user's first name)
- A text value is any value that you can express in alphabetic and numeric characters. For example, you would use a Text variable to gather a business address like 85 South Street, Hobble Creek, A01, even though such an answer uses letters and numbers.
- A Text variable is required to collect numbers that contain any non-numeric characters other than a comma or decimal (such as a letter, dash, hyphen, colon, etc.). For example, you would use a Text variable for phone numbers, Social Security numbers, ID numbers, etc.
Text Variables and Formats
When working with Text 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 names entered without capitalization (e.g. bob smith) to appear in the assembled document with capitalization (e.g. Bob Smith). HotDocs enables you to make such modifications to answers based on Text variables using text formats. To assist you in using text formats, HotDocs provides a set of commonly used text formats (such as formats that enable you to use all caps, all lowercase, 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: