WHILE EXPRESSION; END WHILE

PlaceholderA marker in an instruction or expression model that indicates where a value must be substituted. This value must be a literal value or a variable. Instruction and expression models help the developer use the correct syntax in a script. Replace With
EXPRESSIONA command in a script that retrieves a special value. Expressions help calculate dates, sums, and so forth. An expression that results in true or false

A True/False expression can be as complicated as it needs to be, but it must result in either true or false. For example, the expression YEARS FROM( Child’s Birth Date, TODAY ) produces a number (the age of a person), not a true or false valueIn an interview, it represents a user's answer. In a script, it represents data that must be used in executing the script. (The value can either be a literal value or a user's answer.)—it is not a True/False expression. But the expression YEARS FROM( Child’s Birth Date, TODAY )> 17 can only result in true or false. It is a True/False expression.

The WHILE EXPRESSION instructionA command in a script or template that performs a special task, such as inserting a template or asking a dialog at a specific place in the interview. allows you to repeatedly process (or loop through) an answer or set of answers until a certain condition is met, such as a certain answer is found or a limit is reached.

Before using the WHILE instruction, you should understand the following:

  • The WHILE instruction must be used in a computation or dialogIn template development, represents the component in which the developer groups variables and other components. In document assembly, represents the group of questions in the Interview tab of the assembly window where users enter their answers. scriptOne or more instructions and/or expressions that generate a value or execute some kind of procedure.—it cannot be inserted directly into a templateA word processor or form document that has been converted to HotDocs format so that it can be automated. When in template format, changeable text in the template can be replaced with variables. Other instructions can be added as well, such as instructions that create lists, condition text, and insert other templates..
  • When using the WHILE instruction inside of a REPEAT instruction, the WHILE instruction will not affect the underlying COUNTERAn expression that keeps track of the current number of repetitions in a repeated dialog. Each time a new repetition is added, the COUNTER is increased. 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. associated with the REPEAT instruction. If you need to count something within a WHILE loop, you must create your own temporary counter. Additionally, to access repeated variables in a WHILE loop, you must use explicit indexing.
  • Unless the instructions inside the WHILE loop include an instruction that increments the temporary counter, the WHILE instruction will repeat until the Maximum WHILE iterations limit is reached. You can specify this property at the ComponentA template resource file that displays or stores information about the user input/answers to merge in the final document. Examples of components include variables, dialogs, dialog elements, merge text groups, and formats. File Properties dialog box. (See Change Component File Properties.) To avoid problems like this, make sure you increment the temporary counter.

In the following example, you want to create a listTwo or more answers to one question merged in the document. of signers in a will. Since the signers may include both beneficiaries and fiduciaries, you want to merge both lists into one. Because some fiduciaries may also be beneficiaries, you will want to remove any duplicateThe process of copying a variable to create a new one. names. To loop through the list of fiduciaries, you will use the WHILE instruction:

SET Signer Count TO 0

REPEAT Beneficiary Information

INCREMENT Signer Count

SET Signer Name[Signer Count] TO Beneficiary Name

END REPEAT

REPEAT Fiduciary Information

SET Lookup TO 1

WHILE Lookup <= Signer Count AND Fiduciary Name != Signer Name[Lookup]

INCREMENT Lookup

END WHILE

IF Lookup > Signer Count

INCREMENT Signer Count

SET Signer Name[Signer Count] TO Fiduciary Name

END IF

END REPEAT

In the first part of this script, the Beneficiary Information dialog is repeated, and as answers are entered, their values are set to be used for Signer Name (which is the variable that will be repeated to insert all the names of the signers). Then, in the second part of the script, as the Fiduciary Information dialog is repeated, HotDocs uses the WHILE expression to testThe process of testing a variable or other component to make sure it looks right and works correctly. whether the name of the fiduciary is the same as any of the beneficiary names. If it is not, it will likewise be added to the Signer Information dialog. (When you insert the REPEAT instruction for the Signer Information dialog in the template, clear the Ask Automatically option at the Dialog Editor (Options tab). See Control Whether Dialogs are Asked Automatically for details.)

In the next example, you need to remove unwanted space characters from a user's account number. Here, the WHILE instruction is used to repeat an answer, character by character, so that HotDocs can check to see if there are space characters in the answer. If there are, HotDocs removes them and rewrites the answer.

SET Count Index TO 1

WHILE Count Index <= LENGTH( Account Number )

IF MID(Account Number, Count Index, 1 ) = " "

SET Account Number TO FIRST( Account Number, Count Index -1 ) + LAST( Account Number, LENGTH(Account Number) - Count Index)

ELSE

INCREMENT Count Index

END IF

END WHILE

This script uses a temporary counter (Count Index) to keep track of which character in the answer HotDocs is looking at. Any time the answer is repeated and HotDocs finds a space character, it removes it by concatenating the characters before and after the space character. HotDocs then makes sure that the new character it is now examining isn't a space character either. If it is not, HotDocs increments the temporary counter, moves to the next character, and repeats this process.