Description of the com.com.jFormTK JFormField Run-Time Functions
|Table of Contents...|
|About 'JFormField' Focus Events...|
|Pre / Post Processor Description|
1. Run-time Address Book Methods...
2. Run-time Assignment Statement Processing
3. Run-time pre / post IF Statement Processing
|Using the com.com.jFormTK Common DATA BASE in Assignments...|
|Unexpected Forward Referencing|
Pre / Post Processor Description
The com.jFormTK Package has the capability to invoke pre Processor and post Processor Methods designed to make run-time adjustments to a specific JFormField. This process works as follows:
1) The following JFormField Methods are designed to activate and control the pre Process functions:
public void setPreProcess()
public void setPreProcessFlag(boolean flag)
public void setPreProcessObject(Object variant)
public void setPreProcess(boolean flag, Object variant)
Also, there are a set of the same Methods for the postProcess capability
2) The above methods are designed for use in your Application Form JFormForm Sub-Class. They flag the com.jFormTK system routines to invoke a JFormForm preProcessor [or postProcessor] "Override" Method before the associated JFormField gains focus [pre Processor] OR when a JFormField losses Focus [post Processor]. The preProcessor [or postProcessor] "Override" Method is passed a "Reference" to the current JFormField. If more than one JFormField is to be processed, then the preProcessor [or postProcessor] "Override" Method shall perform a DO CASE [Java switch statement] designed to perform a unique set of run-time Java code for each specific JFormField.
The com.jFormTK Application developer can pass information to the pre / post Processor Methods by employing the Object variant field when setting up the pre/post Processor processing in the JFormForm Sub-Class. If an Object variant parameter is used, then the following Methods are designed to fetch the variant for the run-time processing:
public Object getPreProcessObject()
public Object getPostProcessObject()
3) If the JFormForm Sub-Class pre/postProcessor Override
method is not found, then the preProcessor OR postProcessor
Methods from the JFormForm Parent-Class is used and an error window is
presented to the com.jFormTK developer.
More run-time Capability
The above preProcessor OR postProcessor ability should be sufficient to accomplish any run-time processing you may need. However, in an effort to make the development of run-time processing requirements as easy to use as possible, the following additional com.jFormTK run-time functions are available:
Note: In order to understand the following run-time features, the reader should have an understanding of how the com.jFormTK System references "specific" JFormField instances. See the "com.jFormTK Referencing" document for a detailed description of the JFormField ID implementation.
The following sections describe each of the above run-time capabilities:
2. Run-time pre / post Assignment Statement Processing
public void setPreAssignment("Assignment String")
public void setPostAssignment("Assignment String")
where the "Assignment String" is constructed as follows:
Example 1: "Form1.test2 = Form1.test1"
- Set the Form test2 field to the Text Value of the Form1 test1 field.
Example 2: "test2 = test1"
- Same as Example 1 if the associated object is on the Form1 Form, i.e. the Form Fields in the ID are not required for fields that are hosted by the same com.jFormTK Application Form.
Example 3: "test3 = test1 test2"
- Set the test3 field to the difference between the test1 and test2 JFormField of the same com.jFormTK Application Form.
Example 4: "Form2.fieldA = test1 + test2"
- Set the fieldA field of the Form2 Form to the sum of the Host Forms test1 and test2 text values.
Comment: These dynamic run-time operations are generally performed on
"Numeric" fields. However, if the B and C fields are
"Text" fields, then the "+" operator will perform a concatenation of
the two [B and C] objects
Note that using "this" in a JFormField Assignment String commands the com.jFormTK to use the ID for the current JFormField instance. For example: field1.setPostAssignment("this = this + <c>10") will increment the Field1 field value by 10. Also note that the following Assignment Statement will also increment the Field1 object by 10: Field1.setPostAssignment("this += <c>10")
There are two additional control properties to the run-time Assignment implementation.
Generally, a com.jFormTK Application designer would not use these flags. By default, a run-time Assignment shall be performed only when the field is first processed. However, here are some illustrations as to what will occur for combinations of the above flags:
|Table of Recurrence / Overwrite Usage:|
|False||False||DEFAULT, a run-time Assignment shall be performed only as the field is 1st focused and the 'A' field is null. Once the assignment is preformed, the assignment statement is cleared..|
|True||True||Every time the JFormField get focus, the assignment is processed.|
|True||False||Every time the JFormField get focus and the 'A' field is a 'null' the assignment is processed.|
|False||True||Assignment is performed only once regardless of the current value in the 'A' JFormField.|
3. Run-time pre / post IF Statement Processing
On occasion there will be a need to perform run-time assignments
The following Methods are designed to perform "basic" Java Assignments either as a preProcessor OR a postProcessor operation.
public void setPreIf(Condition String, If Assignment String,
Else Assignment String)
public void setPreIf(Condition String, If Assignment String)
public void setPostIf(Condition String, If Assignment String, Else Assignment String)
public void setPostIf(Condition String, If Assignment String)
where the Condition String is of the following format:
Example 1: "Form1.test2 == Form1.test1", "If
", "Else Assignment
- If the Form1 test2 JFormField Text Value is equal to the Form1 test1 JFormField Text Value,
Then perform the Assignment described in the "If Assignment" String
else perform the Assignment detailed by the "Else Assignment" String.
Example 2: "Form1.test2 == Form1.test1", "If
- Same as Example 1 except no Else operation is given or required.
Conditional If Recurrence / Overwrite Functions:
Similar Methods exist for the run-time Post Processor operations by substituting pre with post in the above method signatures.
Note: the 'then' and 'else' operations are "Mutually Exclusive, i. e. you can
control the 'Recurrence / Overwrite' capabilities of each operation individually.
Using the com.jFormTK Common DATA BASE in Assignments.
Additional run-time Assignment capability can be achieved by using the elements of the com.jFormTK Common data base [appCommonDB]. The following example uses the 'appDB.commonDB' as a place holder in a formula to compute a "Running Sum" of the product of two numbers entered by an Application End User.
The formula is as follows:
Result2 = Sum (NumberQ * NumberR)"
To accomplish this formula there must be two "Run-Time" Processors activated.
1) Use a 'post' Processor on 'NumberR' to compute the product of 'NumberQ' and 'NumberR'. This product will then be saved in the 'appDB.commonDB' in an element named "Sum".
// Establish and initialize the Sum 'appDB.commonDB' Element...
// Set the 'post' Processor to compute the "Product"...
NumberR.setPostAssignment("<c>Sum *= NumberQ * NumberR");
2) Use a 'pre' Processor on 'Result2' to display the current "Running Sum".
// Set a 'pre' Processor to display the current Running Sum in the 'Result2' Field...
Result2.setPreAssignment("this = <c>Sum");
Additionally, the running sum of the two products can be accomplished using the target field, i.e. not using an element of the 'appDB.commonDB'.
// Compute the running sum and display the current value within the Result2 JFormField
Result2.setPreAssignment("this += NumberQ * NumberR");
Unexpected Forward Referencing
The com.jFormTK System is designed to assist the end user to process each
Application Form in a specific order. Ideally, the Application Forms will be processed in
the order that they are added to the com.jFormTK appForm Class in the
Application main program class [i.e. the Class that extends the com.jFormTK basejFormTK
This "Form order" processing is encouraged via the com.jFormTK Applications "Forms Selection Tree" of the "Controls" TAB Panel and the "Next Form" button of each Forms "Button Panel".
However, the com.jFormTK Application end user may select any form they want via the Controls TABs Panel "Forms Selection Tree".
This presents a potential problem for the "Assignment" function of the Java
Form Tool Kit in that an Assignment formula may reference a field [JFormField] that has
not yet been assigned a value by the Application end user.
If this situation occurs, the com.jFormTK shall present an "Assignment Incongruity" user interface window [below] that illustrates the field that has not been set yet and the "Assignment" formula that is being processed. In this window, the end user has the ability to input a value for the missing field and to "Mark" the current field so that it can be re-visited at a later time by the com.jFormTK Application end user.
The given value for the unprocessed Application field [JFormField] will be used as the "one Time" default for the field when the Application end user proceeds to that form. The given default is applied just once to enable the end user to modify the field at any subsequent time.
If the "Mark" operation is requested, then the Recurrence and Overwrite flags are automatically set so that the "Assignment" shall always be re-executed when the end user returns to update the associated field.
All the above processing is mandatory for a truly "Dynamic run-time" system. These features are ideal for setting defaults and for displaying running sums of tabular data, etc..
However, a word of "Caution" should be applied when using the "Dynamic run-time" features of the com.jFormTK System. Do not use these capabilities to compute values that will be directly used in your com.jFormTK Analysis or Reports. Parameters that are used in the "Analysis" or "Reports" phase of your Application should be calculated at the time the "Analysis" is performed or the "Report" is generated.
Generally, the "Analysis" and "Reports" are performed after the Application end user has entered all the pertinent data via the Application Forms processing. Note that the com.jFormTK has the "Required Fields" capability that is designed to allow your "Analysis" / "Reports" processing to recognize any fields that do not have the required values entered yet before commencing the "Analysis" / "Reports" processing.
The com.jFormTK Developer may apply the above "Address Book",
"Assignment" and "If" features once per each JFormForm
JFormField. These com.jFormTK features are "mutually
exclusive", therefore the com.jFormTK Developer may use all three
capabilities on each unique JFormField.
Note that the run-time pre / post Processor operations are implemented in the following order:
If the run-time restrictions described above prevent you from accomplishing an Application "Requirement", then you may use the "preProcessor / postProcessor Method override" capability to include Java code to dynamically perform the specified run-time processing.