Posts Tagged ‘clear’


Unfortunately, the CLEAR instruction model doesn’t really have any use on its own.  Its job is simple: to remove all the options and option prompts from the specified multiple choice (“MC”) variable.  That’s it.  When used in conjunction with the ADD instruction (which adds options & option prompts to a specified MC variable), you end up with a pair of commands that can dynamically build MC variables on the fly, based on whatever data you desire.

For the sake of this example, lets say we are drafting real estate documents.  We have BORROWERS RPT, which collects information on…well, borrowers!  We have BORRS Full Name CO which constructs the full name of each individual borrower (ie: can only be used inside the repeat).  Lastly, we have BORRS Guaranteed MS, which is a multi select MC variable which asks which borrowers have guarantors.  Here’s how we’d build our BORRS Guaranteed MS variable:

ADD "«BORRS Name Full CO»" TO BORRS Guaranteed MS

That’s it.  We firstly clear the MC variable, then inside an ASK NONE/ASK DEFAULT pair, we add the full name of each borrower to the MC variable.  The user may now select borrower names from the MC variable for insertion into the template.  In conjunction with the list format applied to the variable, you can quickly and easily generate user-specified lists of any data from any repeat you have in your system.

There are far more uses for CLEAR/ADD, but this covers what we consider to be the most useful one.


Recently, we looked at how to use the ADD and CLEAR instructions in HotDocs to dynamically create an option for widows and widowers, so that regardless of gender of our client, the user was always presented with a gender appropriate reference, that still had an identical option under the hood.  This time, we’re going to look at the real power of these instructions: with dynamic repeating content.  For this article, we’re going to look at a situation where we have to address a single letter to multiple vendors and have those vendors specified by the user during the interview.  Here’s the pieces:

VENDOR RPT – repeating dialog that collects vendor data
VENDS Name Full TE – the full name of the vendor on VENDOR RPT
VENDS Addr Block CO – a computation that calculates for address block for each vendor (code not listed, it could just as easily be a text/memo field that is filled in)
LETT Vendors MS – a multi select, multiple choice variable that will ask the user which vendors they wish to send a letter to (dynamically created)
flt LETT Vendors CO – a filter that will look at the user selections in LETT Vendors MS, and filter out the ones that weren’t selected.
COUNTER – the HotDocs system variable that will return the number (as a number) of the current repeating dialog. This can ONLY be used inside a repeat instruction.

Here are the steps:

1) Clear LETT Vendors MS and ADD all vendors to it
2) Present LETT Vendors MS to the user for selection
3) REPEAT VENDORS RPT in the template with the appopriate filter, so only those vendors selected in LETT Vendors MS appear in the resulting document.

Firstly, somewhere in your interview process (you DO use interview computations to calculate, control and regulate data collection for your templates, right?), you will have ASKed the user to fill in the vendor details.  Presuming that we have already collected our vendor details, we now need to build the multiple choice variable.  So somewhere in your interview computation, but AFTER you have ASKed VENDOR RPT, we do this:

CLEAR LETT Vendors MS //clear first, then ADD
ADD "«COUNTER»|«VENDS Name Full TE»" TO LETT Vendors MS //the option is the counter, the prompt is their name
//you could wrap the add instruction inside an IF statement, if you are uncertain as to whether VENDS Name Full TE is ANSWERED() or some other logic particular to your system

We now have LETT Vendors MS containing a full list of all vendors.  So at somepoint after the above script runs, you would ASK LETT Vendors MS, most likely as part of a dialog that relates to the letter we are drafting.  Now for what our FILTER looks like.

"«LETT Vendors MS::a|b|c»" CONTAINS "«COUNTER»"

This is a little tricky.  Multiple choice variables store their results as text, but multi-select multiple choices store their values as an ARRAY of text – much like a repeat.  Because of this, a multi-select variable cannot be directly compared to a straight line of “regular” text.  Additionally, no multi choice variable can be compared directly to a number.  So there are three solutions in that one line of code.  The value of LETT Vendors MS is converted to a REGULAR line of text, using the chevrons embedded inside double quotes.  That’s the first solution.  The second solution is to use a custom list format, “a|b|c”, which means that each selection is split by a pipe | character.  I’ll explain this in a later!  The third solution was to wrap COUNTER in chevrons and quotes, which takes COUNTER – a numeric value, and converts it to a string.  With all of this going on, we can now use CONTAINS to correctly compare the selections of LETT Vendors MS and the value of COUNTER.

Now, for the template….

«VENDS Name Full TE»
«VENDS Addr Block CO»

Dear «Some Variable Here»

Some letter content here....

{-- conditional page break --}

This instruction will repeat the template infinitely whilever there are iterations inside VENDOR RPT, but will ONLY include iterations where the filter is true.  For the sake of this article, lets say there are three vendors: 1) John Doe 2) Jane Doe and 3) Billy Blogs.  When presented with LETT Vendors MS, it looks like this (brackets contains options):

(1) John Doe
(2) Jane Doe
(3) Billy Blogs

Lets say the user selects 1 and 3.  Here’s what our FILTER looked like:

“«LETT Vendors MS::a|b|c»” CONTAINS “«COUNTER»”

Here’s what happens when our template repeats:

Repeat #1: “1|3” CONTAINS “1” (evaluates to TRUE, John is included)
Repeat #2: “1|3” CONTAINS “2” (evaluates to FALSE, Jane is excluded)
Repeat #3: “1|3” CONTAINS “3” (evaluates to TRUE, Billy is included)

Congratulations.  Your multi select multiple choice variable has allowed you to quickly present a list of ALL vendors to the user and ask them which one gets a letter.  No databases (although you could use one), nothing too heavy; simply collect the vendors, build the multiple choice variable in HotDocs, ask which vendors get the letter, then repeat and filter for the selected values.

Now, I promised a bit more explanation on the whole “a|b|c” thing.  To do that, lets look at a concept called DELIMITING.  Delimiting is simply putting a specific character between each value you want to look at.  Common delimters are commas and pipes.  I prefer pipes, as they aren’t ever used in names, addresses and other pieces of data – they truly do identify the end of one bit of data and the start of the next one.  But lets say we DIDNT delimit our selections from LETT Vendors MS.  Lets say we have 14 vendors (wow!), and the user selected 1, 4, 5, 6, 12.  The value might look like this:


That’s right – its just a string of numbers.  This would mean our filter would “break” when repeating vendor #14.  Because the text “14” appears inside “145612”, even though the user did not selection option #14.  However, with delimiters, our value looks like this:


And 14 does NOT appear in that value, so the comparison is run correctly.

Clear as mud? Its a bit to get your head around, but when comparing multiple selections in multiple choice options, it is definitely best practice to delimit your strings and use CONTAINS instructions.


Two of the more useful instruction models in HotDocs for dynamic interviews and variables are ADD and CLEAR, which go hand in hand to dynamically construct multiple choice variables.  This is the first of two HotDocs tips, which will deal with the basic CLEAR/ADD instructions with “static” content.  The next article will be about dynamically building a multiple choice variable in HotDocs with a REPEAT instruction.

Lets say we wish to ask for a client’s gender (CLI Gender MC) and their marital status (CLI Marriage MC).  Because we have different language in our template that concerns married clients versus divorced or widowed clients, we need this variable.  However, if a client is a widow/widower, there are two options based on their gender.  Because our language content is the SAME for a widow or widower (with gender specific references), we only want ONE option to denote the widow(er) marriage status.  Here’s how we do it.  We create a computation (say, called build CLI Marriage CO)

CLEAR CLI Marriage MC //always CLEAR before ADD, as ADD simply appends options to the multiple choice variable
ADD "Single" TO CLI Marriage MC
ADD "Married" TO CLI Marriage MC
IF CLI Gender MC"Male"
ADD "Widow|Widower" TO CLI Marriage MC
ELSE IF CLI Gender MC"Female"
ADD "Widow" TO CLI Marriage MC
ADD "Widow|Widow/Widower" TO CLI Marriage MC

If the client is male, we add “Widow” as the option, but “Widower” as the prompt.  That’s what the pipe | character is for.  Anything BEFORE the pipe is the option. Everything AFTER the pipe is the prompt for that option, which is what the user sees.  Note that because we chose “Widow” as the generic option for someone who’s partner has deceased, we don’t actually need a prompt for the female specific entry – the option IS the prompt.  If there is no client gender specified, we run with a generic prompt, but the option NEVER actually changes for the widow(er) option.  That means we lessen our code on the template end of things, because our option value is generic.

So now, we have a dynamic looking MC variable that will produce its own options based upon the gender of the client.  No doubt, in the dialog that these variables appear on, you would have something like the following script:

IF !ANSWERED ( CLI Marriage MC )
build CLI Marriage MC

The dialog script basically says that if CLI Marriage MC is NOT answered, then run the computation that builds the options.  This would likely be a part of a SHOW instruction, so that the variable doesn’t show up until it has options.  Depending on your version of HotDocs, there may be alternate ways to structure this to ensure smooth running of the dialog.

And that’s all there is to it.  This is a very simple way to use logic and the CLEAR/ADD instructions in HotDocs.  It is far more powerful to use ADD in conjunction with a repeat, which we’ll be looking at in my next article.

Basha Search


Basha Network

Basha Product Sites