Repeats and Lists Overview

Repeats and Lists Defined

You can include lists of answer s in your documents by repeating variableA component that is used to represent changeable text (such as names, dates, numbers, etc.) in the template. Types of variables include Text, Date, Number, True/False, Multiple Choice, Computation, and Personal Information.s and enabling your end-users to supply as many answers as necessary. You repeat variables by surrounding the variables with a REPEAT instructionAn instruction that repeatedly asks the same variable(s) so that users can provide two or more answers for a given question. REPEAT instructions are used to create lists of answers in the document.. Instead of collecting and merging a single answer, as variables normally do, the repeated variable can mergeWhen HotDocs pulls an answer from the answer file into the document during assembly. an entire listTwo or more answers to one question merged in the document. of answers into the assembleSee document assembly.d document.

For example, the following shows a REPEAT instruction inserted into a template:

This shows the list of answers the REPEAT instruction merged into the template:

Create and edit a REPEAT instruction

You can create a list of repeated answers by inserting a REPEAT instruction around one or more variables. For example, perhaps you want to insert a list of personal property items with their associated values. You can create a variable for each of the two data types (items and values), and then repeat them.

When you create the REPEAT instruction, you are asked to create or select a custom dialog to control the instruction. During the interview, the user can answer the dialog over and over again, until they have listed all their pertinent property items.

You also have the option to limit the number of answers a user can supply for a repeated variable. HotDocs merges these answers into the finished document.

Additionally, you can use the REPEAT instruction to repeat any text, instructions, or other parts of a template. Everything inside a REPEAT instruction becomes repeatable together with the variables.

Repeats in a Table

Often, you may need to repeat information within a word processor table. This is best done by repeating a single cell or an entire row.  

Repeats with Computation Variables

Instead of inserting a REPEAT instruction directly in a template to generate a list of answers, you can also use a REPEAT instruction in a Computation variable to create your list of answers. Using a computation enables you to quickly insert a list in more than one location in the template.

Repeat Return Options

By default, when HotDocs inserts a REPEAT instruction in the template, it includes a return character (similar to a paragraph mark in a word processor) after the instruction. During assembly, as the instruction is processed and removed from the assembled document, this return character is likewise removed. Depending on several factors, you may prefer to keep HotDocs from adding this character, or you may want to add a return character only under certain situations. You can specify an option that controls this. See also, Understand How Smart Returns are Inserted After Instructions.

Edit Repeats

You can make changes to REPEAT instructions after they have been created, including editing the repeated dialog's contents, adding a filter, choosing an answer-sorting order, and adding punctuation to the list of answers.

Punctuate, Sort and Filter Your Lists

If you’re inserting a list in sentence style, you must choose the punctuation you want for the list. If you don’t choose a punctuation style, the list runs together without any punctuation or spaces—for example, DanielNathanEmilyKate. Once you select a punctuation style, HotDocs punctuates the list automatically—for example, Daniel, Nathan, Emily, and Kate.

When assigning a format, note that formats with all capital letters only capitalize the conjunction in the sentence, for example, the word AND. Individual answers in the list are either mergeWhen HotDocs pulls an answer from the answer file into the document during assembly.d as the user types them or merged as you have formatted them using a variable-level example format.

You can also have HotDocs alphabetize your list automatically, in either ascending or descending alphanumeric order (for example, A to Z and 1 to 9). You can also sort based on any repeated variable. If there’s more than one repeated variable in the REPEAT instruction, you can sort on two levels—for example, first on State, then on City (or cities within the state).

You can also create a computation script that filters a list so only the entries that meet some condition are merged into the assembled document. For example, you could create a list of all the children in a family and then limit the list to include only those who are under the age of 18.

Choose a Presentation Style

You can choose how a repeated dialog appears during an interview, either by presenting the list as a series of dialogs, or as a single spreadsheet with multiple entry points.

Your options include:

  • Repeated Seriescauses a regular dialog to appear with an answer field for each variable. When the user answers the questions in the dialog, they can either click the Add Another button to add another repetition to the dialog, or they can click Next to move to the next dialog in the interview.
  • Spreadsheetcauses a single dialog to appear with a column for each variable and an unlimited number of rows. The user fills in as many rows as they need. (The spreadsheet format lets the user see all the answers at one time and makes it easier to change answers. However, a dialog with several variables can make a spreadsheet too large to view easily.)

Customize REPEAT Titles

You can customize the titles used for each repetition in a repeated series of dialogs. For example, perhaps you need to ask the user for a list of beneficiaries. By default, HotDocs displays this list in the interview outline using an incremented number, followed by the dialog title:

This approach may work in some situations, but in others, it may be better to customize the title for each repetition so the user knows what's in that particular dialog. For example, maybe you want the topmost icon in the list to use a generic title (like List of Beneficiaries), but you want the name of the beneficiary to appear for each individual repetition in the interview. This way, the user can easily review what's in each dialog, like this:

To accomplish this, you must do the following:

  • Assign a generic label (such as List of Beneficiaries) to the repeated series.
  • Create a computation script that merges the user's answer to Beneficiary Name in the title. If you don't give an answer, the script merges other text that shows the user that the dialog is unanswered. Otherwise, HotDocs merges an unanswered variable placeholder in the title.

Additional Options

You can further customize REPEAT instructions in the following ways:

  • Control How Many Rows are Visible in a Spreadsheet DialogBy default, when displaying a spreadsheet dialog, HotDocs always shows 10 rows of the spreadsheet. If you need to show more or less than this number of rows, you can enter a specific number at the Dialog Editor. (This option doesn't limit the number of answers a user can give—it only controls the number of answers that can be viewed at any given time.)
  • Limit the Number of Answers Allowed for a Repeated DialogAt times, you may want the user to enter only a specific number of answers in a list. You can use the LIMIT instruction to limit the number of times a dialog repeats. Once the user reaches the limit, they can not enter anymore answers.

  • Get the Sum Totals for Repeated Number VariablesYou can use a Computation variable to find the sum total of a repeated Number or Computation variable. For example, you may need to find the grand total of a series of dollar amounts.
  • Make a List Appear as one or More ColumnsSometimes it makes more sense to have your list of answers appear in columns, rather than in a punctuated sentence. If you want to make the list appear in a column, include a hard return after the text in the REPEAT instruction.
  • Count the Number of Entries in a ListYou can use a computation script to determine how many times a user answers a repeated dialog. You can also use a built-in Number variable that numbers a list of answers automatically.
  • Retrieve a Specific Answer from a ListAt times, you may need to retrieve a specific answer from a list of answers. For example, maybe you have created a list of employees, but later in the document you need to merge the name of just the second employee in the list. You can do this by using explicit indexing. To do this, you type the index number of the answer you need between brackets, just after the variable name.
  • Retrieve Information Other Than Answers from a REPEAT InstructionYou can use a Computation variable to retrieve information (other than a list of answers) from a REPEAT instruction.