Demo

JCounselor Tutorial – an Advanced look at FWAdmin

Getting Started w/FWAdmin

AsyncFW Framework is, at its core, a tool to make your life easier. If it fails at that, it fails as a framework. The FWAdmin application is a different kind of tool, it is built upon the Framework, but it is NOT part of the framework. It is not pretty, nor is it well designed - in fact it lacks a lot of bells whistles, and is a rather crude tool. But it is an affective tool, and it will save you a lot of time.

Overview

You are not required to use the FWAdmin to create forms, it is just much easier. In fact, you are not required to store Forms, and Fields in the database at all, but it does make re-use much easier and it will give you a data dictionary and central location to administer forms and fields without having to constantly modify XSL.

Using FWAdmin you can quickly determine what forms a field appears on, how many fields of each class are used, or if a particular JavaScript function is attached to a control and much more. I strongly suggest you use the Forms database as the source for your controls, and secondly I recommend using the FWAdmin to quickly prototype your application. But first, we need to understand the underlying data structure.

Data Structure

*Note: The Forms Database is required for the AsyncFW framework, however, you may choose not to use it as your forms repository.

The Data Structure for the forms and fields is very simple. There is a FWFields table and an FWForms table. The relationship between the fields and forms is maintained in the FWFormFieldIndex table. This structure allows the same field to appear on multiple forms. The data base also supports cascading deletes so if you delete a field, it is removed from all forms. If you delete a Form, only the fields that are NOT used on other forms will be removed.

Note: Removing a field does not remove the field from the presentation, it simply takes the field out of the Async sphere of influence – meaning, you can use the field, but you will be responsible for constructing it’s attributes in-code.

The AsyncFW framework will always look in the database for the form being requested (AsyncFW does provide a cache option), however, it does not fail or generate an error if no form is found. The framework simply assumes that you are going to populate the fields manually.

FWAdmin Intro

Forms and fields can be imported from database table structures, and/or manually created. Once the fields have been created, and associated with a form, the FWAdmin can output the XSL, JavaScript, Java Class and Data Object Class files. These files can then been saved to your project.

IMPORTANT: The FWAdmin application was built using the FrameWork so it requires that the Framework setup be complete. You must have a Forms database built and configured as a connection pooled resource within Glassfish. If this is not the case, then please click the following links and do so now;

Download the Forms Database creation script

View the FWAdmin installation guide

To verify that the FWAdmin site is up and running on your system, click the link below (this link assumes you used the default install settings, yours may be different)

http://localhost:8080/FWAdmin/html/Admin.html

Logon Screen

Once the logon screen appears, simply enter an ‘a’ for the user name, and an ‘a’ for the password and press the ‘Logon’ button.

The first screen to appear is the User Maintenance screen. Here you can Add, Update, or Delete users.

Create New User

To Create a new User, enter a User Name, Password and select a Role from the Drop down and click the ‘Add’ button. The new user is now active, and available.

To edit, select a user from the Drop down list, change something about the user and click ‘Update’. To remove a user, select it and click the delete button.

One Important note: Roles don’t inherently do anything; they are simply made available to the developer to implement however he/she sees fit. A user must have its ‘Enable User’ checked, otherwise it is considered ‘disabled’ and the user will fail validation. If you are going to track user session state, or perform user validate, you will need to create a logon screen which is NOT validated, so that you can collect user name/password. More on that later.

The FWAdmin Buttons

Notice that there are two buttons at the top of the form ‘Logon’ and ‘FW Administration’. Clicking the logon button will terminate your current session, and you will be required to log in again. Clicking the FW Admin button will always reset the screen and return you to the User Maintenance screen.

At the bottom of the screen are three buttons which are used to navigate from within FW Administration. There are four possible buttons (the button associated with the current screen is not displayed)

Ø User Maintenance

Ø Edit Fields

Ø Edit forms

Ø Assemble Forms

The row of buttons above these navigation buttons, are the action buttons;

Ø Add

Ø Update

Ø Delete

What are Forms and fields?

Forms are containers for fields (ok duh), and fields are your users inputs to the application. Fields can be any html object;

Ø Buttons

Ø Check Boxes

Ø Combo Boxes

Ø Input Boxes

Ø Labels

Ø List Boxes

Ø Radio Buttons

Ø Text Areas

When designing a form, you will first consider what information needs to be collected, its format, and when it is to be passed to the application for processing.

The FWAdmin’s ‘Edit Fields’ screen is your starting place for adding new, or editing existing fields. A single field (Zip code, state etc.) can be used on multiple forms; this feature can greatly reduce the amount of redundant work and should reduce the number of errors.

Old School first

The FWAdmin provides time saving import functions, but first let’s look at what it required to enter data manually. Normally the first step is to simply create a new form. Click the Edit forms button, and then enter a form name, access level (‘1’ is fine for now), and then click the ‘Add’ button.

Once you have added the new form, click the ‘Edit Fields’ button.

Enter the field information above, and click the ‘Add’ button. Repeat this process for all desired fields. The data being entered will be added to your XSL as attributes of the field. All field level attributes come from the database, and most map directly to HTML attributes; such as, value, ID, Name, etc. as well as the mouse events shown. Notice that the tool tips are placed in the ‘onmouseover’ event. This event is reserved for this purpose, and is not available to the developer.

A web application is of little use, if the user cannot submit the form for processing. In most cases this is done via a button.

The field Attributes and Relationships

Let’s look at another field (this one may not yet be in your Forms Database) “_CustomerID”.

By looking at the field’s name, we can determine that it is a Database column field by the underscore prefix (_xxx). The underscore denotes that the field is to be linked to some table, in some database. The details of that relationship are not established at the field level.

The rest of the attributes are used to populate the XSL that will be transformed to HTML. For example;

And finally to the end users browser…

Adding a submit button

Enter the button information above, and click add. A couple of the field values don’t fit nicely in the inputs, so the actual values are provided below;

Onmouseover: Press this button to submit this form

OnClick: MyNewform_submitButton(this)

IMPORTANT: If you are going to use a script function reference (like shown for onclick) you should precede the script name with the formname. This will insure that the function is unique.

Once the button is added, click the ‘Assemble Forms’ button.

Assemble Forms

Select your newly created form from the ‘Select Form’ dropdown. Your screen should look like the one above. The list labled ‘Form Fields’ shows the fields configured for this form. By default, all the system level variables have been added. These are all hidden fields, and will not be displayed on your form. The second list contains all the fields previously added to this instance of the Form Database. To add our new field(s) and our new button to this form, we need to locate and select them (one at a time) in the ‘Available’ list. Once you have selected a field to add, simply click the ‘Add Field’ button.

NOTE: If you add a field by mistake, simply select it in the Form Fields list, and click the ‘Delete Field’ button. The field is not deleted from the system, it is simply removed from the form.

Generating XSL/Code

When the FWAdmin generates xsl, javascript or java classes it does by creating a tempory file which can be saved to your project (or anywhere else). Before you generate any code, you must fill out the left side of the window.

Number of Cols: This field is used to define the number of columns to be used when constructing the presentation layout. Each ‘column’ consists of a label and an input field. So a 1 column display, is actually 2 html columns – one for the label, and one for the field. A 3 column display would actually produce a 6 column html layout. The fields will be laid out across the form in a left to right, top to bottom order. Remember, this is a prototype, you will be able to directly manipulate the resulting xsl from within Eclipse to get the look and feel you need for your application.

Example of a two column output:

Label [input] label [input]

Enter a 2 in Number of Cols.

Project Name: The Project Name field must contain your actual project name in Eclipse, case is important, for this example enter ‘Customer’

Package Name: If you have not yet created any packages under the ‘src’ folder of your project, you might want to do so now. Once you have a package structure enter it here (com.customer) for example. The class file created at this stage is where you will place your business logic, it will use the associated Data Object (see below)

Data Object Package Name: As a matter of practice, it is a good idea to create a sub-package, under the package you created above, to be used as a repository for your data object classes. The data object will represent the request/response object.

Fill out the left side as shown above, then click the ‘Generate Form *.xsl’ button. This will display a link to the generated file. Normally you would right mouse click this link and select ‘Save Target as….’, and save the file (with an *.xsl extension) to your /Webcontent/html/xsl/ folder. But in this case, we are just going to view it, we really don’t want to save it, so just double click the link and view the MyNewForm.xsl in the browser window. Repeat this process for each button, and view the resulting file.

Detailed look at FWAdmin

The Introduction provided an overview of the FWAdmin functionality; in this section we will take a more detailed look at each screen.

Edit Fields Screen

Click on the ‘Edit Fields’ button.

The ‘Edit Fields’ form contains the attributes which can be assigned to an HTML form control. The only required fields are name, Id (handled for you, it is always set equal to name), type and class. All other attribute settings are optional. Some fields such as label, onmouseover (tool tip remember?), maxLength and size are highly recommended, but not required. Notice the labels are all lowercase, and multiple word labels do not contain spaces, if you are familiar with HTML you will recognize these attributes. If you are not familiar with HTML you may want to do a bit a studying.

Select Field: This drop down displays all the fields currently in the system. To edit a field, simply select it from the list, change or add attribute values, and click the ‘Update’ button.

Field Attributes:

Name:

This is the Unique name for the field (except in the case of Radio buttons) . This name will be used to access the values of the variable on the server side code.

ID:

The ID should be the same as the Name, and is used to access the value of the field from the JavaScript

Type:

Class:

The CSS type that will be used to render the field. The F4J framework uses a very specific naming convention for class. Please refer to WebContent/html/css/application.css file to see the implemented css classes. You will no doubt add your own, feel free – this is just a starting point, you are by no means limited to those supplied. Below is a table containing the currently configured css classes;

local_checkBox_generic	local_comboBox_generic_error	local_comboBox_generic
local_inputBox_currency_error	local_inputBox_currency	local_inputBox_date_error
local_inputBox_date	local_inputBox_email_error	local_inputBox_email
local_inputBox_generic_error	local_inputBox_generic	local_inputBox_integer_error
local_inputBox_integer	local_inputBox_integerNonNeg_error	local_inputBox_integerNonNeg
local_inputBox_integerPreserveZero_error	local_inputBox_integerPreserveZero	local_inputBox_interest_error
local_inputBox_interest	local_inputBox_numeric_error	local_inputBox_numeric
local_inputBox_numericNonZero_error	local_inputBox_numericNonZero	local_inputBox_percent_error
local_inputBox_percent	local_inputBox_percent100_error	local_inputBox_percent100
local_inputBox_phone_error	local_inputBox_phone	local_inputBox_ssn_error
local_inputBox_ssn	local_inputBox_zipcode_error	local_inputBox_zipcode
local_label_error	local_label_generic	opt_button_generic
opt_buttonSmall_generic	opt_checkBox_generic	opt_comboBox_generic_error
opt_comboBox_generic	opt_inputBox_currency_error	opt_inputBox_currency
opt_inputBox_date_error	opt_inputBox_date	opt_inputBox_email_error
opt_inputBox_email	opt_inputBox_generic_error	opt_inputBox_generic
opt_inputBox_integer_error	opt_inputBox_integer	opt_inputBox_integerNonNeg_error
opt_inputBox_integerNonNeg	opt_inputBox_integerPreserveZero_error	opt_inputBox_integerPreserveZero
opt_inputBox_interest_error	opt_inputBox_interest	opt_inputBox_numeric_error
opt_inputBox_numeric	opt_inputBox_numericNonZero_error	opt_inputBox_numericNonZero
opt_inputBox_percent_error	opt_inputBox_percent	opt_inputBox_percent100_error
opt_inputBox_percent100	opt_inputBox_phone_error	opt_inputBox_phone
opt_inputBox_ssn_error	opt_inputBox_ssn	opt_inputBox_zipcode_error
opt_inputBox_zipcode	req_checkBox_generic	req_comboBox_generic_error
req_comboBox_generic	req_hiddenSysValue	req_inputBox_currency_error
req_inputBox_currency	req_inputBox_date_error	req_inputBox_date
req_inputBox_email_error	req_inputBox_email	req_inputBox_generic_error
req_inputBox_generic	req_inputBox_integer_error	req_inputBox_integer
req_inputBox_integerNonNeg_error	req_inputBox_integerNonNeg	req_inputBox_integerPreserveZero_error
req_inputBox_integerPreserveZero	req_inputBox_interest_error	req_inputBox_interest
req_inputBox_numeric_error	req_inputBox_numeric	req_inputBox_numericNonZero_error
req_inputBox_numericNonZero	req_inputBox_percent_error	req_inputBox_percent
req_inputBox_percent100_error	req_inputBox_percent100	req_inputBox_phone_error
req_inputBox_phone	req_inputBox_ssn_error	req_inputBox_ssn
req_inputBox_zipcode_error	req_inputBox_zipcode

Title:

Of very little use within the Framework, but is included to provide a place holder for custom xsl or javascript handling.

Label:

The Label is as its name implies – the label that will be displayed next to the input field – if your xsl supports it. The xsl produced by the FWAdmin uses this attribute, for this very purpose.

Value:

The value attribute is used to send and receive user data. 99% of your interaction (from the java/javascript) will be with the fields value.

MaxLength:

Total number of character which will be allowed for input fields. For lists, it is the width of the field

Size:

Represents the display size of the field in characters. This value may be smaller than Maxlength – resulting in scrolling text.

Checked:

Checkboxes and Radio buttons. Setting the checked=’checked’ will cause the object to be ‘selected’

ContentEditable:

Specifies whether or not the content of the element is editable, Its support is a bit sketchy among the different browser types. Works great for Safari and IE, but the framework ignores it for combo-box and lists as it seems to cause some grief.

TabIndex:

Used to control the tab order of the field on the form. Usually you will leave this at zero, and set it this value in code. (re-using a field with a tab order, may result in odd tabbing).

FWError:

Free form field field designed to be used to hold server side field error messages. Steps would need to be taken to implement this attribute in the xsl or java script.

FWInfo:

FWInfo is similar in nature to FWError, with one exception. For Radio buttons, enter the word ‘Vertical’ will cause the radio buttons to display vertically, instead of horizontally.

Field Events:

Field events execute a java script function when the action occurs. Usually you will want to pass a reference to the current field into the function being executed. This can be accomplished by using the ‘this’ keyword. For example ‘dummy(this)’, would call the function named dummy, and pass a reference to the object for which the event was fired.

Onclick:

Executes when the user clicks on the field.

Ondblclick:

Executes when the user double clicks on the field.

Onkeydown:

Executes when the user presses a keyboard key, when the current control has the focus.

Onkeypress:

Executes when the user presses a keyboard key, when the current control has the focus.

Onkeyup:

Executes when the user releases a keyboard key, when the current control has the focus.

Onmousedown:

Executes when the user presses the mouse key down, when the current control has the focus.

Onmouseover:

Enter a tool tip message to appear when the mouse pointer is over the field

Onmouseup:

Executes when the user releases the mouse button, when the current control has the focus.

Dynamic Field Changes

The AsyncFW framework relies on the Forms database as it’s source for form control attributes, since these attributes are not ‘hard-coded’ into the application, or the xsl they can be changed on the fly and reflected in the application without the need to recompile or deploy. This dynamic nature allows for rapid adjustments to your visual display, and can greatly improve developer productivity. I would suggest that you always have the FWAdmin installed and running during development. The ability to dynamically change a field without having to rebuild and deploy is a powerful option.

To find out more about each of the field attributes, you can simply research their HTML equivalents, with only a few exceptions, they operate very much like their HTML equivalents. The FWInfo field is simply a miscellaneous field added for whatever purpose you deem necessary – with one exception, Radio Buttons.

Just to reiterate:

There are a few very important fields on the Edit Field screen, they are ‘name’, ‘class’, ‘type’, ‘size’. Be sure to always supply those.

‘Real world’ Example:

What follows is a very quick, and basic tutorial on using the FWAdmin tool, if you want a deeper, more instructive tutorial, you may want to actually skip over to the JCounselor tutorial at this point.

An AsnycFW Form consists of two core files, and two optional, but highly recommended files.

Core files

The Form’s presentation layer *.xsl file

Contains xsl tags representing the fields added to the form
Contains additional standard tags

The Form’s *.java servlet (ServiceLet in AsyncFW)

extends FWHttpServiceLet
implements FWServiceLetInt
Provides all required core functionality
Implements the FWHttpServiceLet.Execute() method

Optional files

The Form’s JavaScript file

Provides core functionality

1. Ajax host interactions

2. Comet functionality

3. Direct web access to Java classes

Will contain form specific code to support button controls

Data Object representing the Form’s controls

Contains getters and setters for all form controls
Provides access to all system level variables
Provides a support Database interface for AsyncDO (database persistence)

Create the Customer Project in Eclipse

Pre-work:

Create a Dynamic Web Application named Customer.
Put all the Jar files (Click here to download) into the WEB-INF/lib folder
Create a package in the ‘src’ folder called com.customer
Create a sub-package called com.customer.obj
Add a standard, non-AsyncFW, HTTPServlet named ‘Customer’ to the com.customer package.
Create the AsyncFW /html folder structure in the new /WebContent (Click here to Download)

Unzip the folder structure to the /WebContent folder

FWMaster.properties, FWDefault.properties files installed in your /src/ root directory. (Click here to download)

Configure these to match your Form’s database JNDI name.
Review the AsyncFW Configuration and Properties tutorial

Make sure your web.xml resource references are correct for the JNDI JDBC connection pool.

<resource-ref>

<res-ref-name>jdbc/FWConPool</res-ref-name>

<res-type>javax.sql.DataSource</res-type>

<res-auth>Container</res-auth>

<res-sharing-scope>Shareable</res-sharing-scope>

</resource-ref>

Your project should now look like the following;

Designing your application

Start with your data store. Determine how you intend to persist your data, and build a functional design of your domain. In other words, build your database. If you want to just follow along you should already have the customer table in your FWDemo database (jdbc/FWConPool), if not, feel free to download the CustOrder.sql script and run it on an existing, or new database.

Starting with the database will save you a lot of time, even if your form ultimately contains many more fields than you actually store. This is due to the fact that the FWAdmin can discover table information and automatically create a useable form. This will be your “protptype”.

Click Edit Forms

When you are importing a database table, the form need not already exist in the Forms database; therefore it is not necessary to use the upper portion of the form. When importing, simply enter the JNDI connection pool name for both the Source DB (database containing the table structure to be imported.) and the Target Form DB (the forms database where the new fields and form will be stored).You will also need to supply the Table Name. This is the actual table name, as it appears in the database. For our example, Enter ‘customer’ in the Table Name input box, and click the Import Table button.

Once you receive the ‘Returned from Import’ message, click the ‘Assemble Forms’ buttons, then select the newly created ‘customer’ form from the drop down list.

Once you have selected the ‘customer’ form, the ‘Form Fields’ list will show all the newly imported fields associated with this form. It contains the default system fields (prefixed with sys*), the database columns (prefixed with an underscore) and four ‘Button’ fields (Add, Update, Delete and Find). At this point you could add additional fields from the ‘Available’ list, or remove unwanted fields. For the proposes of this tutorial, we will accept the defaults and proceed with generating the *.xsl, *.js, and the two Java classes.

Creating the form

NOTE: At this point you should have a Dynamic Web Application named customer.

By default the FWAdmin will always construct the XSL layout as a table - for all non-system fields. System fields are identified by the field’s Type, and Class. If the type is ‘hidden’ and the class is ‘sys_value’ – it is considered a ‘System Value’ and will not be placed in the table.

Number of Cols: Instructs FWAdmin how many columns should be constructed in the XSL. One key point to note is that specifying a value of ‘2’, will actually result in a 4 column layout as follows;

[LABLE] [INPUT] [LABLE] [INPUT]

So a column is actually considered as the combination of both a label and an input of some kind.

Project Name: This is the name of the project, as you created it in Eclipse.

Package Name: This is the name of your root package, this is where the AsyncFW servlet will be placed.

Data Object Package: This is the package where your DO Classes will reside.

Ready to generate some code!

Click the button, and a link will appear which will allow you to save the XSL file into your project. Be sure to place it into your /WebContent/html/xsl/ folder, and to change the default extension from *.xml to *.xsl.

Next click on the button, and generate the JavaScript file. Right click the link, and save the file into the /WebContent/html/scripts/pages/ folder.

To Generate the AsyncFW Servlet class, click the button, and save the resulting *.java file in to the /src/com/customer folder.

And lastly, click the button to create the AsyncFW Data Object *.java source file. Save this file into the /src/com/customer/obj folder.

Refresh your project in Eclipse, and the new files should now appear in your project.

Configuring the project to run

To test the above ‘customer’ application, we still need to perform a few housekeeping tasks. First we need to configure the FWMaster.properties files to use the database(s) we have designated as our Form and Application databases. You should have the FWMaster.properties file in your project’s /src folder.

FWMaster.properties

file.property.1 = /FWDefault.properties

Environment = dev

replace.dev.LogName = Framework_dev

replace.dev.LogFileName = Framework_log

replace.dev.FormsDB = jdbc/FWConPool

replace.dev.ApplicationDB = jdbc/FWConPool

The key to these changes is to make sure you know the JNDI data resource name. The above settings assume that the Forms and Application database are one in the same. If your’s are different, you will need to modify them.

Start.html

The /Webcontent/html/Start.html file is the default AsyncFW startup html file. If you are using it (or are not sure) then open that file up in you Eclipse editor and make the following changes;

1) Locate the following section and add the newly created script to the list of page scripts to be imported;

<!--

INCLUDE ALL YOUR PAGE SCRIPTS BELOW. REMEBER EACH 'PAGE' SHOULD

HAVE THEIR OWN JS FILE

-->

<script type="text/javascript" src="./scripts/pages/customer.js"></script>

2) Change the project name variable;

<!--

IMPORTANT: YOU MUST CHANGE THE PROJECT NAME TO MATCH YOUR PROJECT

-->

var sysProjectName = "customer";

</script>

<!--

3) Change the script snippet located toward the bottom of the Start.html file to the following

<!--

IMPORTANT: This script snippet kicks off the entire process

-->

try{

AjaxRequestPage("customer","Init", "Page", FormContextArea)

}catch(err){

alert("[Start.html].script: Failed to load JLogon:"+err);

}

</script>

4) Save the Start.html file.

5) Modify the /WebContent/WEB-INF/web.xml file so that it contains the new servlet, and the database reference

<resource-ref>

<res-ref-name>jdbc/FWConPool</res-ref-name>

<res-type>javax.sql.DataSource</res-type>

<res-auth>Container</res-auth>

<res-sharing-scope>Shareable</res-sharing-scope>

</resource-ref>

<display-name>customer</display-name>

<servlet-name>customer</servlet-name>

<servlet-class>com.customer.customer</servlet-class>

</servlet>

<servlet-mapping>

<servlet-name>customer</servlet-name>

<url-pattern>/customer</url-pattern>

</servlet-mapping>

6) Rebuild you project

7) Redeploy the EAR to the server

8) Test: Http://localhost:8080/Customer/html/Start.html

The default screen is not all that pretty, but that is where you come in. While it lacks much, it is functional. You can add and edit records, but be aware, you will not want to allow CustomerID edits, as this is an auto-increment field.

Enter an ‘S%’ in the First Name field, and then click the ‘Find’ button. This will search the customer table for the first ‘Customer’ who’s name starts with the uppercase letter ‘S’.

The results should be…

Conclusion…

This was a very brief introduction, I would suggest that you now go to the JCounselor Tutorial, and run through that example. Once you have completed that you should be fully versed in the use of FWAdmin and the AsyncFW framework.

S. Chappell