One of the topics often kicked around on Notes discussion boards is about creating "dynamic subforms." This gives a main form the ability to determine, on the fly, which of its subforms will display for a particular document at a particular time. The applications for this feature are many. Imagine that a medical patient fills out an online information form asking for medical history. Based on answers early in the questionnaire, the form would display different subforms below for additional information. So a patient who checks "heart disease" would see a subform with more detailed cardiac questions. A patient who checks "arthritis" would see questions related to that condition.
The usual approach to subforms as a design problem is to place a fixed set of subforms on the main form and use hide-when formulas to control which subforms are displayed. This method does work, but the list of available subforms is hard-coded within Domino Designer, so it is difficult to maintain.
Another approach is to use computed subforms, but these have a non-dynamic property. Computed subforms are calculated only when the main form is first loaded and are not refreshed based on field changes while a document is open. The overall consensus among application designers is that neither of these approaches is ideal.
This tip contains a new approach to solving the problem of dynamic subforms. (At least it was new to me.) The code makes use of both computed subforms and hide-when formulas, but these features work together and are controlled by easily modified setup parameters, without invoking Domino Designer. The sample is on my Downloads page.
The main form is simple. It contains two hidden fields at the top, which are used to control the dynamic subforms. The remainder of the main form is simply 10 lines, each of which is a computed subform. (The number of subforms can be increased to at least 40.) For each subform line, the computation is simply the Nth element of a list of subforms. This list of subforms is stored in the setup parameter named Form Sections and retrieved into the main form via the field FormSections. (All setup parameters are visible in the view named Settings.)
The set of subforms that is available on the main form can be changed without using Domino Designer; just edit the parameter Form Sections. Of course, the list of subforms is retrieved only once, when the main form is opened.
So how do we control which subforms the document actually displays? There are two types of subforms: basic-field subforms that are always displayed when they are included on the main form; and variable-field subforms that are dynamically controlled. You can see the difference by looking at the hide-when formula for each subform. If there is no hide-when formula, then that subform is always displayed whenever it is included in the Form Sections list.
The variable-field subforms are displayed (and hidden) dynamically using the control field ShowSections at the top of the main form, along with the setup parameter named Section Formula. The parameter contains an @-function formula that is evaluated by the field to yield a list of subform names. That list is referenced by the hide-when formulas of the variable-field subforms. The result is that you can control how subforms are displayed and hidden just by changing a setup parameter, again, without using Domino Designer.
The formula mentioned above makes use of the DocType field on the Doc Basics subform as the key determiner of which subforms are displayed. In our medical example, this field would contain information about the patient that indicates if it's a cardiac, arthritis, or mental illness case, etc. Notice that a particular DocType can cause one or many subforms to display; there is not just a one-to-one mapping of doc type to subform. Since the subforms displayed are controlled by the formula, you can change the formula to refer to any field within the overall form or any set of fields. For clarity, I suggest that the formula use only fields on the basic-field subforms, rather than fields on variable-field subforms.
To make the subforms refresh automatically, the DocType field is marked as "refresh fields on keyword change." You can test this by editing one of the sample documents and changing the document-type keyword. You will see the set of subforms change immediately, which was the goal of this design challenge.
This design and the database sample are based on R6, and I believe the code uses features that do not work in R5.
I welcome comments from readers and any suggestions about how to improve the code.
Chuck Connell is president of CHC-3 Consulting, which helps organizations with all aspects of Domino and Notes.
Do you have comments on this tip? Let us know.
Please let others know how useful it is via the rating scale below. Do you have a useful Notes/Domino tip or code to share? Submit it to our monthly tip contest and you could win a prize and a spot in our Hall of Fame.
This was first published in March 2005