Description of the com.jFormTK "Dynamic Referencing" Function…

Each ‘JFormField’ instance of a 'com.jFormTK' Application has a unique String identifier [ID]. This "ID" String variable is used to "Reference" any JFormField of a 'com.jFormTK' Application. These JFormField references can be made in the Software Development Phase and used during the 'com.jFormTK' Application Run-Time processing. Thus the term "Dynamic Referencing".

A "Dynamic Reference" may be to any JFormField of the 'com.jFormTK' Application or a reference to any 'com.jFormTK' Data Base element that is processed by the 'com.jFormTK.Jvalue' Class.

Each JFormField instance contains a 'reference' control parameter. This JFormField reference is defaulted to the null String [""] when the JFormField is instanced. The jFormTK software developer may define a "Dynamic Reference" via the ‘JFormField.setReference()’ Method

Example:   aField.setReference("Directory.DirFamily.spouse");
                     where 'aField' is a JFormField instance,
                                  "Directory.DirFamily" is a JFormForm SubClass IF,
                                  "spouse" is a JFormField name in the "Directory.DirFamily" Form.

The remainder of this document defines the format of a "Dynamic Reference' to a specific JFormField instance, i.e. the "JFoormField Reference"  See the 'com.jFormTK.JValue' documentation for the format required to dynamically reference one of the 'com.jFormTK' Data Base elements.

The "JFormField Reference" shall contain a String that "uniquely" identifies a specific JFormField using "dot" Notation. The rules for the "dot" Notation identification of a "JFormField Reference" are as follows:

A FULL "JFormField Reference" contains the "Form ID" concatenated with the "Field ID".

Form ID = Category . SubCategory . FileName
- Category:           "Required" String assigned to the JFormForm Sub-Class Constructor.

- Sub-Category: "Optional String assigned to the JFormForm Sub-Class Constructor.

- FileName:           "Required" Name of the Java File that contains the JFormForm Sub-Class.

 Field ID = GroupName . FieldName . SetNumber
- GroupName: "Optional" String assigned to the JFormField when added to the
                            JFormForm Sub-Class instance.

- FieldName:    "Required" Field Name String assigned to the JFormField when added to the                               JFormForm Sub-Class instance.

- SetNumber:  "Optional" Set Number String assigned to the JFormField when added to the                              JFormForm Sub-Class instance.

A "JFormField Reference" may contain just the Field ID if the Field to be referenced is in the "host" JFormForm Sub-Class. The 'com.jFormTK' Kernel will use the "Form ID" of the current JFormForm if the Form ID is not specified in the "JFormField Reference" String.

Examples and notes:

The following is a list of "JFormField Reference" items with example from the Professional Computer Solutions Survivors List PLUS [Survivors List PLUS] 'com.jFormTK' Application.
[Note: No Sub-Category's are used in Survivors List PLUS, therefore none will be shown below. Sub-Category may be removed in the future because it is considered as "overkill"]

'com.jFormTK' Kernel Processing Notes:


- Repeat Mode:

If the JFormField has an associated 'Repeat Mode',
i.e. 'JFormField.repeatMode' is Not Null,
Then a Warning Message shall be presented and no "referenced" Value is set.

The Warning message is as follows:

"Repeat Mode of value found with an Active Reference Property.

The Reference will NOT be made since the "Repeat Mode" Processing has Precedence.

SUGGESTION:

Remove the Name .setReference(Reference") usage!

OR Clear the RepeatMode for the Name JFormField."

Reference Removal…

By default, if the Application End User changes that value of a JFormField for a JFormField, which was set by a "JFormField Reference", the 'com.jFormTK' Kernel shall clear the 'reference' parameter for that JFormField. This is done, by design, so that when the JFormField receives the focus again, the 'reference' shall not change the value that was entered by the End User.

A 'com.jFormTK' developer may control this process by setting the JFormField instance as uneditable via the following method:

aField.setEditable(false);
where 'aField' is a JFormField instance.

In this case the 'reference' is set to the "Dynamic Reference" each time the JFormField gains focus and can not be changed by the Application End User.

Group Processing…

New 'com.jFormTK' Groups are added when the Application End User selected an _AField button. The new set is derived from the previous sets OR the 'savedGroup' String [see "Additional References Usage" below] iff all previous sets have been deleted.

If an entry in a Group has the associated value changed by the 'com.jFormTK' Application end user, the 'reference' is cleared by the 'com.jFormTK' Kernel. This operation should NOT carry over to addition Group Sets however, i.e. any added Group Sets shall contain the original 'reference' NOT the value entered during Run-Time by the Application End User. Therefore, the original 'reference' is NOT cleared iff the JFormField has a non-null Group Name. Instead of being cleared, the original 'reference' is prefixed with the JFormTKDB.NullReferencePrefix' so that it can be reset in the newly constructed Group.

Additional JFormField.reference Usage's:

The JFormField 'reference' field is used by the 'com.jFormTK' Kernel as follows:

  1. _QField JFormField Type
    Used to hold the "JPerson" control required to make the _QField processing service Group Sets using a predefined set of Person Names as the Set Number.
  2. _Afield JFormField Type
    Contains 'savedGroup' String used to Control resetting of a Group after ALL of the Group Sets have been deleted.