WHILE Instruction
The WHILE instruction tells HotDocs to repeatedly process a script until the condition you specify is met.
The WHILE Instruction is only available when you are creating a script in the Component Studio and cannot be used in the template.
The WHILE expression enables you to repeatedly process (or loop through) a region of script. If you don't include an INCREMENT instruction that keeps track of how many loops you perform, HotDocs continues to process the region of script until it hits the Maximum WHILE iterations limit. You cannot use the COUNTER instruction to keep track of your WHILE loops if you're using a WHILE instruction inside a repeat instruction, as WHILE loops do not affect the COUNTER value.
You must use an END WHILE instruction after the WHILE instruction to close the condition.
| Instruction name | Model | After you drag and drop the model into the script tab: |
| WHILE | WHILE ⟦EXPRESSION⟧ | Replace ⟦EXPRESSION⟧ with an expression that evaluate to true or false. |
Example
In the following example, you want to create a list 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 duplicate 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 test 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 Behaviour tab.
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.