a JFormField Primer                                                 

 

The Java "Tool Kit" is designed to provide a user friendly data entry form deigned to enter, edit and Save a "Collection" of information from your application’s end user via. The "heart" of the ‘com.jFormTK’ Development System is the ‘JFormField’ which is designed to represent each field of each Form in an ‘com.jFormTK Application.

Table of Contents...
Framework Overview.
Creating an Application Form.
Using the ‘JFormField’ Field Object.
‘JFormField’ Properties.
The ‘com.jFormTK’ Group Usage.
Application Field Referencing.

Framework Overview

The following figure illustrates a completed JFormForm. It is the "Family Physicians" Form from the Professional Computer Solutions [PCS] Survivors List PLUS Application.


The blue with black print annotation’s point to the five major sections of a JFormForm as follows:

  1. Application Title:
    The title provided when the Application Form [JFormForm] Object is instantiated.
  2. Tabs:
    The ‘com.jFormTK’ provided default Application Tabs as follows:

    - Controls
    - Forms
    - Table Edit
    - Quick Edit
    - Address Book

    Shown are the ‘com.jFormTK’ default Tabs. The ‘Controls’ and ‘Forms’ Tabs are required. The ‘Table Edit’, ‘Quick Edit’ and ‘Address Book’ Tabs are optional. There may be additional, Application specific Tabs added as required.
  3. JFormField :

    Each field of the JFormForm is a JFormField. For example the "Specialty" JFormField is annotated in the figure. The remainder of this document focuses on the ‘JFormField’ Object.
  4. JFormFrame Controls:

    5. The JFormFrame Control Buttons.

    These buttons are the system defaults. Each button may be removed or disabled as required. The button order is also controlled by the Application Developer either for the entire Application or on a per Form basis.

  5. Prompt Line:
    The "Prompt" line provided with each JFormField instance is displayed as each unique JFormField is processed via the keyboard [‘Enter’ / "TAB’] Key or via selection with the mouse.

See the ‘Framework’ documentation for a detailed description of these ‘com.jFormTK’ objects.

Top Return to com.jFormTK Overview

Creating an Application Form.

The ‘com.jFormTK’ produces each field of an Application Form via the following steps:

Using the ‘JFormField’ Field Object.

Each field is instanced using one of the ‘JFormField’ Constructors. For example the "Specialty" Field that is annotated on the above sample Form is created using the following ‘JFormField’ Java statement:

JFormField Specialty = new JFormField(this, "Specialty", "Specialty: ",
"Enter the Doctor's Specialty, e.g General Pratictioner",
_NotRequired, _NoHint, _TField, _FldSize, _FontSize);

Specialty.setText("General Practitioner");
util.addObject (this, DoctorSpecialty, 2, Row, 3,1, GroupName, "");

The following table shows the fields of the ‘com.jFormTK.JFormField’ constructor and a description of each parameters usage by the above ‘Specialty’ Field" code snippet:
Parameter: Description ‘Specialty’ Usage…
JFormForm f The ‘host’ ‘JFormForm’ Generally use the Java ‘this’ field to identify the Current ‘JFormForm’ class.
String name Name used in ID Field "Specialty"
String s Name used to label the Field "Specialty:"
String p User "Prompt’ Line "Enter the Doctor's Specialty, e.g General Pratictioner",
boolean rFlag Required Field Flag _NotRequired *
boolean Hint Hint Button Flag _NoHint *
char Type ‘JFormField’ Type

= 'B' – Action Button
= 'C' - Choice Drop Down
            Box
= 'L' – Label
= 'T' - Text Field OR 'N' for           "Numeric Verification".
= 'X' - Checkbox
= 'R' – RadioButton
= 'A' - Add "Group"
            Button. **
= 'D' – Delete "Group"
            Button. **

 _TField *
int TextFieldSize Text Field Size _FldSize *
int FontSize Text Field Font Size _FontSize *

* - The ‘com.jFormTK’ has a set of mnemonic string used to make the usage of the various ‘com.jFormTK’ Constructors easier to read.
      They start with the ‘_’ character. Some examples that apply to the above table are as follows:

    boolean for Required Field Flag: _NotRequired, _Required.
    boolean for Hine Button existance: _NoHint, _Hint.
    char for the ‘JFormField’ Type: _BField, _CField, LField, _TField, _XField, _Rfield
    int for Text Field Size: _FldSize
    int for Text Field Font Size: _FontSize

These controls have a ‘com.jFormTK’ System Default set that may be modified for each Application via usage of the ‘com.jFormTK Data Base methods.

** - The ‘A’ and ‘D’ Types are used to control the run-time addition or deletion from a ‘com.jFormTK’ Group Table. This "GroupName’ tabular processing is described later in this document.

Top Return to com.jFormTK Overview

‘JFormField’ Properties:

Each ‘JFormField" has the following properties:

  • Object ID
    Each ‘JFormField’ is assigned a unique identifier, i.e. the ID property. This identifier uses the Java "dot" notation as follows:

    GroupName.Name.Set Number

    The Name field is provided  via the ‘JFormField’ Constructor. The ‘GroupName’ and ‘SetNumber’ fields are used to uniquely identify each element of a ‘com.jFormTK.JFormForm’ Group. See the ‘com.jFormTK’ Group description below.
  • Prompt Line
    Provided when the ‘JFormField’ is instanced. Displayed in the ‘Prompt’ section as each Field [JFormField] gains the Form’s focus.
  • Required / not Required Field Flag.
    Controls if the associated field has been flagged as a "Required Data Entry" field. The ‘com.jFormTK’ Developer may flag a field as "Required" if it is necessary for the successful completion of one of more Application Analysis functions.

    For example, if you provide an Application Analysis feature to compute the end user’s "Net Worth", then perhaps a field requesting the estimated value of the person’s home would be a "Required Field".
  • Help Annotation
    If the ‘com.jFormTK Application end user presses the ‘F1’ key a ‘Help’ Window is displayed over the ‘JFormForm’ Control Button panel. The ‘Help’ information displayed shall be automatically constructed at the time the Field [JFormField] is instanced. This is basically a repeat of the ‘Prompt’ information and some annotations as a function of the ‘JFormField’ Type. For example, the following ‘Help’ text is added if the ‘JFormField’ Type is _Cfield, i.e. a Choice JFormField:

    Prompt + LF + "Use the 'up' / 'down' arrows to move to your selection" + LF + "OR" + LF + "Select Button with the Mouse to see the Choices and select the required choice." + LF + LF + "The Choice Items are as follows:

    where LF is the platform specific "Line Feed" code.

    If you have additional ‘Help’ information that you want to add to the constructed Help message, or you want to add your own Application specific ‘Help’ annotation, the following ‘JFormField’ Methods are available:

    - public void preHelp(String s)
        prefix the constructed ‘Help’ String with the given String.

    - public void postHelp(String s)

    •     postfix the constructed ‘Help’ String with the given String.

    - public void replaceHelp(String s)
        replace the constructed ‘Help’ String with the given String…

  • Hint Button
    Each ‘JFormField’ Field may have a ‘Hint’ Button appended to the field. This feature is designed to enable the Application Developer to provide additional information as to the design purpose or required input for the associated field. If this field is true, the Following Java code line is used to enter the information to be displayed when the end user selects the "Hint" Button:

    - addHint("place the HELP Text here! ");

    If the ‘addHint’ Method is not used, a simple default ‘Hint’ message is presented to the end user.

    If a 'Hint' Button is required for a Label Type [_LField] JFormField, then the button annotation s set to "Definition". For all other JFormField Types the Hint Button has the "Hint" annotation. See the "Remove Doctors" button on the above sample Form.
  • Text Field Size
    Indicates the width, in Pixels of the JFormField. The system default [__FldSize] is set to 15]
  • Font Size
    Indicates the Font Size for the associated JFormField. The system default [__FldSize] is set to 12]

    Note that there is a 'JFormField' Constructor that does not require the "Text File Size' and the 'Font Size' parameters. Generally it is advisable to keep the "Look and Feel" of the Application Forms consistent and frequent modification of these parameters are a distraction to the Application end user.
  • The Pre / Post run time processing.

    Each unique ‘com.jFormTK.JFormForm.JFormField’ has a Pre / Post Processing property that allows the ‘com.jFormTK’ developer to control processing before a ‘JFormField’ gains the Form Focus and as a ‘JFormField’ gives up the Form Focus.

    This property enables the ‘com.jFormTK’ Application Developer to control the content of a ‘JFormField’ before and after it is processed by the Application end user. For example, a ‘preProcessor’ operation may be used to enhance the end user data entry by setting default fields based on previously entered data or by Application defaults setup in one of the ‘com.jFormTK’ data bases. A ‘postProcessor’ run-time operation may be used to compute a variable that is then loaded into the ‘com.jFormTK’ Common Data Base for usage by later JFormField’s preProcessor operations.

    The Java Form Tool Kit [com.jFormTK] contains "boiler plate" Java code that enables the Java Application Developer to write the specific code that is required for the individual ‘pre’ / ‘post’ processing operations plus a set of ‘JFormField’ Methods designed to ease the development of run-time Assignment Statements [both static and conditionally] plus the dynamic entry of individuals into the ‘com.jFormTK’ Address Book.

    See the ‘Run Time JFormField Function document for a complete description of these Dynamic run-time capabilities.

The ‘com.jFormTK’ Group Usage.

Most data entry forms require a ‘Variable’ number of "Data Sets" to be entered by the end user. For Example, the Survivors List PLUS ‘Physicians’ Form requires that the end user enter information for all the Family Doctors. For each Doctor, the following four fields [JFormField’s] are required: DoctorName, Patient, Specialty and Phone Number. These fields represent a "Data Set" for each Doctor.

To enter a variable number of Sets to a JFormForm, the Java Form Tool Kit [com.jFormTK] uses the "Group" Concept.  A "GroupName" is specified and the number of "Data Set" fields and number of "Data Set Display Rows" are identified for each Form "Group". Special ‘JFormField’ Buttons are used to add or remove Data Sets to / from each Group of an Application Form.

For example, with the ‘Physicians’ Form of the Professional Computer Solutions Survivors List PLUS Application the "Group Name" is "Doctors", the number of fields per data set is 4 [Name, Patient, Specialty, Phone] and the number of rows per set is 2. This ‘com.jFormTK’ form then uses a ‘More Doctors’ Button to add a variable number of Physicians to the Application "Doctors’ Group and the ‘Remove Doctors’ to remove a Physician from the ‘Doctors’ Group. See the "Family Physicians Survivors List PLUS figure above.

Application Field Referencing

Earlier in this document, the ‘JFormField’ identifier was described. If a Form Field is one of the elements of a "Group Data Set", then the Group Name [GroupName] and Set number [SetNumber] parts of the ‘JFormField’ ID must be used to uniquely identify each element of a ‘com.jFormTK’ Group.

For example, the ‘JFormField.getID’ method for the "Specialty" Field of the second Doctor in the above Survivors List PLUS Family Physicians Form would yield the following identification String: "Doctors.Specialty.1".

To uniquely reference the above ‘JFormField’ from another Application Form, the above ‘JFormField’ ID shall be prefixed with the Survivors List PLUS Family Physicians ID. For example, if the Category = "Directory", Sub Category = null [not sed], and the ‘JFormForm’ File Name is = "Physicians", then the ‘JFormForm’ ID would be "Directory.Physicians" and the complete ‘JFormField’ Reference to the above 2nd Specialty Field would be as follows:

"Directory.Physicians.Doctors.Specialty.1"