Dynamic Section Inserts
Dynamic Section Inserts derived from an equation using field data to name a library resource to insert into the form
This feature creates a manageable way to design a form and designate a library resource to dynamically insert based upon a name constructed from field data mapped into the form.
A feature of the Documaker Workstation/Policy Production System (PPS) called Logos, Stamps and Signatures (LSS) provides the inspiration for this solution. That feature tied the insertion of components to WIP database record entries, where this implementation will use field data defined insert “equations”.
Business Definition (BDF)
Inserts equations are defined within the business definition (BDF). A separate tab for the Inserts appears in the portion of the screen where other ancillary definitions occur.
An example of an Inserts definitions looks like the following.
Within this tab, you may add, delete and edit Inserts. Keep in mind that a form reference to an insert equation is a “copy”. If you modify or remove an existing insert equation in the BDF, you will have to visit any forms using that item and reselect (reapply) the appropriate named insert equation.
The Name is used to associate the insert with a given form section. Description can be any text that will help or remind the user of the purpose of the given equation. The Equation itself allows a combination of (static) text and field mapped values that when resolved will designate a specific library section to fetch and insert.
An Insert equation may contain static text and one or more fields. Curly braces delineate where field values substitute within the equation. In the equation above, State and City are field references. The percent (%) character before a field name indicates that field is optional to a successful evaluation. The field “City” in this example is optional since the percent character is present.
Optional does not mean the field is unmapped or blank. Rather, “optional” means that if a matching resource is not found in the library when using that value, then that reference can be removed and another attempt at evaluation will occur using the remainder of the equation. Optional elements remove one-at-a-time (from right to left) until a valid resource name is found or the equation has no optional elements left.
Consider this example where the equation is:
LSS_{KEY1}_{%LOCID}_{%JURISDICTN}_{%SUBLOCID}
Now assume the field values found mapped (or entered) within the form are the following:
- LOCID = ABC
- SUBLOCID = XYZ
- JURISDICTN = GA
- KEY1 = ANYSTATE
Since there are three variable components that are optional, the search for resources will be performed in this order until a matching library section is found.
- LSS_ANYSTATE_ABC_GA_XYZ
- LSS_ANYSTATE_ABC_GA
- LSS_ANYSTATE_ABC
- LSS_ANYSTATE
Notice that on each subsequent evaluation that the underscore character preceding each optional field is removed when that optional field reference is removed. The space, hyphen (-) or underscore (_) that precedes and optional field are also removed if the field reference is removed.
The evaluation process stops when a matching resource is found for insertion into the form. If the current field(s) value(s) yield no matching resource after all optional fields are removed, then no insert occurs.
More about the management of the inserted section occurs later in this document
Forms Manager
On any form where an insert should be applied, simply associate the appropriate Insert equation by selecting the name form those defined within the BDF.
The section defining the insert equation must also define the fields to be used by that equations. The section may be visible or hidden. If the section is visible, the field within the section may be visible or hidden on that section. All that is required for the insert evaluation to occur is for a section to define the appropriate property and then have the field values mapped, assigned, or entered manually.
Keep in mind that if field values are entered manually, a different resource may be selected at the point where each field changes.
If an existing insert section is already present due to an earlier mapping and the equation field values change, the previous inserted section will be removed and a new section will take its place. If the evaluation of the equation finds no matching resource section, any existing insert is simply removed an no new insert will take its place.
When an insert is applied, the new resource section is logically inserted immediately follow the defining section.
A repeated (duplicated) section defining an insert – whether duplicated by trigger or scripting – will have opportunity to evaluate and insert a new section based upon the fields mapped onto that section.
Using Test Manager results to demonstrate, see below the initial form will trigger multiple occurrences of the “Person” section. (Depicted on the left)
On the right, we see that as the fields map in each (separate) Person section, the insert equation evaluates and a different resource sections inserts based upon the field values from that copy of the section.
Continuing this example, the resulting PDF page might appear as follows. In this example, the Person section is hidden, so you only see the resulting inserted section.
Library Manager
In the library, you would define all the resource names you expect generated by the resulting equation. Based upon the example above, what is depicted blow might be appropriate.
The section located by the insert equation may contain any content that you wish. In general, the purpose of these sections is to provide additional (and optional) information into the form and therefore should not be large or multiple-page sections that might require splitting across pages. The system will try to maintain the positioning of the inserted section adjacent to the section that defined it.
Keep in mind, since this section is inserted dynamically, the placement will be “relative” to the section that defined the insert equation which called for it. If the controlling section is hidden, the newly inserted section will still use the relative positioning. Therefore, it is important to make sure that your hidden section has a proper placement within the form to achieve the desired pagination effect.
If the evaluation of the insert equation does not yield a matching resource name from the library, the insert will not occur. This is not considered an error and no message will appear.
Thin-Client
The thin-client model will not automatically perform insert equation evaluations. If field values change that change any insert equation, this will be applied once the transaction is saved back to the server.