Category: HotDocs Dialogs

GRAY, UNGRAY, SHOW and HIDE

These four commands are essential in presenting user friendly and user-proof dialogs in HotDocs.  When designing systems, it is generally best practice to show only those variables that require (or may require) an answer and HIDE or GRAY those that are irrelevant.  HotDocs provides a rudimentary manner to handle this automatically, but if you are designing complex systems, you may need to use these four commands. All of these instructions are used in dialog scripts only.

GRAY Var //grays Var, prohibiting data entry, but displaying the value (if any)
UNGRAY Var //UNgrays it, allowing data entry
HIDE Var //completely hide the variable
SHOW Var //opposite of HIDE

Here are some examples that should be fairly self explanatory…

//hide the company type, only showing it if relevant.
HIDE PARTY Entity Company Type MC
IF PARTY Entity Type MC = "Company"
SHOW PARTY Entity Company Type MC
REQUIRE PARTY Entity Company Type MC
END IF

//calculate a total amount, but gray it so it isn't editable
GRAY SALES Grand Total NU
SET SALES Grand Total NU TO ZERO ( SALES Amount NU ) + ZERO ( SALES Tax NU ) - ZERO ( SALES Discount NU )
//allow them to manually change it if they REALLY want to
IF SALES Grand Total Change TF = TRUE
UNGRAY SALES Grand Total NU
END IF

Instead of using a variable name, you can also substitute the “ALL” parameter….

GRAY ALL //grays everything on the dialog
UNGRAY ALL //ungrays everything

When building a system to really lockdown data entry, you may wish to write a dialog script something like this to force entry of everything in the correct order…

 

HIDE ALL
SHOW PARTY Entity Type MC
IF ANSWERED ( PARTY Entity Type MC ) //must have a type before we allow name entry
SHOW PARTY Name TE
IF PARTY Entity Type MC = "Company"
SHOW PARTY Entity Company Type MC
REQUIRE PARTY Entity Company Type MC
SHOW PARTY Entity Company Number TE
END IF
IF ANSWERED ( PARTY Name TE ) //must have a name before they can proceed further
//more SHOW/REQUIRE pairs here
END IF
END IF

All of these commands are dynamic as of HotDocs 6, which is a major step forward.  Whilst they may look like eye candy, these instructions serve to produce better and more accurate documents every time, simply by forcing/prohibiting better data entry.  When combined with REQUIRE, you really can obey the rule that “if a variable is visible, it must be answered and if it is invisible, it is irrelevant”.  When your systems can follow this rule, your users do not have to have any knowledge of what they are working with or understand the sometimes complex concepts behind the scenes – all they need to know is that if it CAN be answered, it SHOULD be answered and if it cannot be seen, don’t worry about it.

ERASE Var and ERASE Dialog

The ERASE instruction is one of the handier instructions in HotDocs if you are populating data dynamically more than once, or are using ‘temporary dialogs’ during your interviews.  Use of this instruction will completely erase the contents of a variable or dialog, but be warned: it will erase all iterations of that variable or dialog!

Let’s say we’re doing an Estate Planning matter – you have the client, their spouse, a list of children, trustees, executors and some random beneficiaries.  There’s a lot of entities in there.  If you’re working with a system by Basha Systems, there would likely be a central party list that functions as a contact database.  If you’re not, you have several repeats containing contact information.  Either way, the approach is the same.  The example I will use is a generic letter.  You want to program a generic free-style letter that can be sent to any entity on the matter.  But because you quite often wish to send letters to the same party consecutively (a few days apart), you want the generic letter dialog to retain the information of who a letter was last sent to.  Here’s how you do it.

Create your dialog as you ordinarily would – name, address, salutation etc – lets call our dialog Generic Letter DLG.  I won’t get into the import mechanics – all we’re showing here is the ability to clear an entire dialog easily.  On that dialog, we’ll create a button that points to the computation Generic Letter Clear CO.  The script of that is:

ERASE Generic Letter DLG

That’s it.  If the variables on the dialog are saved in the answer file, then the next time you hit that dialog, the details of your last generic letter appear.  If the user wants to use those details – great!  If they don’t, they simply click the button and everything on that dialog is erased and the user can pick a new entity to direct a letter to.  Be warned that you don’t use this on repeating dialogs, as it will erase the entire dialog and all of its iterations/repetitions.

DEBUG

The HotDocs DEBUG instruction model is very simple, very powerful and very clear about its use.  DEBUG is used to…well, debug!  If you have templates or computations that are producing unexpected or incorrect output, using the DEBUG instruction may get you back on track just a little quicker.

There are two uses of DEBUG – in templates and in scripts (both Dialog scripts and computations).  Both uses have a very similar effect.

By placing a DEBUG instruction in your template or script, you tell HotDocs to display the Debugger screen.  With the debugger, you can manually step through a script or template while viewing extremely detailed information regarding each variable’s value.  You can add variables to watch lists, “step” the script (ie: manually tell HotDocs to progress the script line by line) and watch the variable values change with each step.  Using DEBUG, you can quickly identify what data is coming in/going out and what data is changing.  This will allow you to track down any errors quickly, as you can not only assess each computation or variable, but also the variable values that went into creating the problematic data.

Additionally, the Debugger contains a processing stack tab.  This is a sequential list of templates and components to be processed, in order.  It will also give you the reason as to WHY HotDocs has a particular item in the queue.

In the most general sense, the Debugger gives you a real look under the hood as to exacty how HotDocs is handling/treating your code.  This is invaluable if you simply cannot make your code produce the correct content.

CONCEAL VAR and OMIT VAR

A very brief HotDocs tip today – the CONCEAL and OMIT instruction models.  These two commands make working with HotDocs dialogs as answer sources a little cleaner and easier for users to work with.

In short, CONCEAL keeps a variable from showing in the “Select from Answer Source” dialog – it is simply hidden from the user, allowing for the more meaningful fields to be shown only.  OMIT does a similar thing, but hides a variable from the user in the “Edit Answer Source” dialog box – again, allowing only the meaningful fields to show to the user.

These two commands go hand in hand to pare down information that displays in dialog answer source manipulation.  Rather than trying to show an example, these two commands are best “tinkered” with on a case by case basis.  If you want to try something cool, try using dialog answer sources in a scenario where only ONE variable is not CONCEALed.  The variable still showing should be an identifier, such as a name or similar.  That way, a user will simply see a nice drop down to pick from and all the other data will ‘appear out of nowhere’ – just like magic!

This stuff is super simple and takes about 10 minutes to master.  Play around with dialog answer sources, CONCEAL and OMIT – it may actually be FUN.

ASK DIALOG and ASK VAR

The ASK instruction does exactly what it appears it will do – forces HotDocs to ASK (present to user) a specific variable or dialog.  ASK is quite often under utilized, as many developers permit HotDocs to generate a template interview.  For those developers in the know, there is a lot more functionality, flexibility and control possible when you write your own interview.  For those developers who design their own interviews, use of the ASK statement is absolutely critical.

In its simplest form, you simply ASK a variable or dialog.  Lets say we are designing a conveyancing/real estate master interview.  We have borrowers, lenders, their counsel and perhaps a guarantor or two.  The borrowers may not necessarily always have representation, nor will the borrowers always have a guarantor.  So here’s how our interview might look:
In its simplest form, you simply ASK a variable or dialog.  Lets say we are designing a conveyancing/real estate master interview.  We have borrowers, lenders, their counsel and perhaps a guarantor or two.  The borrowers may not necessarily always have representation, nor will the borrowers always have a guarantor.  So here’s how our interview might look:

ASK INTRO DLG //ask whatever intro/matter information we need
ASK PROPERTY DLG //get property information
ASK LOAN DLG //get loan related information

ASK BORROWER DLG //basic information - how many borrowers, any shared address for service - details common to all borrowers

IF ANSWERED ( BORR Num LMT ) //force user to specify how many borrowers there are going to be
ASK BORROWERS RPT //info for each borrower
END IF
IF BORR Counsel TF //did the user specify that the borrowers had counsel?
ASK BORROWER COUNSEL DLG
END IF
IF LOAN Guaranteed TF //did the user specify that the loan was guaranteed?
ASK GUARANTOR DLG //if so, grab guarantor details as well
END IF

With developer designed interviews and the ASK instruction used in conjunction with IF statements, we can minutely control the interview and user experience.  ONLY those dialogs necessary are presented to the user, which reduces the chance of erroneous data entry, while forcing the user to be presented with the dialogs and questions that are necessary to complete the specifics of each transaction.  Dynamically. Efficiently. Correctly.

« Older Entries

Basha Search

Loading

Basha Network

Basha Product Sites