ImagoX Forms Extension

The ImagoX Forms Extension is an implementation of a forms processor. ImagoX Forms was designed with these goals:



	Goal:		Implementation:
	To create a single implementation for display, processing, and validation of form data.		To achieve this goal the form validator creates a form or processes the input of the form during a GET or POST respectively. During a GET request each element is formatted and a standardized XML form is created. During a POST request the input is validated. If any errors exist the original input form is recreated with the users input as the default values and the fields in error are clearly marked.

	To allow easy extensibility to create new form element types.		To allow for extensibility each field type has a validator registered with the form validator. New field types may be implemented by registering a class derived from `org.xenei.imagox.forms.FieldValidator`.

	To provide input error checking.		Error checking is performed during a POST processing request and appropriate action taken.

	To resist hacking attempts.		The entire processing of the Form is controlled by the original XML document, invalid user input and extraneous input fields are ignored.

The elements and attributes listed here use the name spaces defined in the imagoX_form.xml and imagoX_extension.xsl files. While the xform name space is not required, a name space must be used. The name space of the root element in the XML document will be used to detect all element and attributes of the form and, except where noted, as the name space on all output elements and attributes.

xform:root element.
The root element of the form. Only one root element may exist in a single name space. The actual name of the element does not need to be root, this is the element that will trigger the org.xenei.imagoX.ImagoForm.root() extension element as defined in the XSLT file. During validation the root node is replaced with a copy. See copy section below for details.

Attributes:

xform:validated: An optional field inserted by the process. If present the form has been validated.

xform:hidden element.
The hidden node and all its child nodes are removed during the GET operation. During the POST operation all children are made siblings of this node and this node is removed. Compare with xform:remove.

xform:remove element.
The remove node and all its child nodes are removed during the POST operation. During the GET operation all children are made siblings of this node and this node is removed. Compare with xform:hidden.

xform:input element.
The input node defines an input field. The input note may have the following attributes:

Attributes:

xform:name: The name of the field. Must be unique.
xform:type: Defines the input type. The mapping of xform:type values to field validators is defined in the configuration file (see Configuration section). If a specific type is not defined the default field validator will be used. See the Field Validators section for more information.
xform:required: Optional. If present the field is required, null data or empty strings will not be accepted and a validation error is generate for that field.
xform:error: An optional field inserted by the process. If present its value is the text of the error message. Any form that has an input element with an error attribute has not been validated.

Field Validation

All field validators listed here are in the org.xenei.imagoX.forms package.

Class: FieldValidator

The default validator and the base class for all Field Validators.

Format: Does nothing.
Validate: Appends the value as a text child node.
Transform: Appends the value as a text child node and performs a copy (See copy section below).

Class: ChoiceValidator

Validates a choice list. An xform:choice is a list of choices contained within an xform:select element. All choice elements must have the same xform:name as the xform:select element that encloses them. The value of the selection may be defined in a xform:value attribute, or as an enclosed text node.

Format: Sets xform:selected attribute if the value has been selected.
Append Value: Sets the xform:selected attribute if the value has been selected.
Validate: Sets the xform:selected attribute if the value has been selected.
Transform: does nothing as the enclosing xform:choice will remove this element type upon form validation.

Class: DateValidator

Creates a multi segment date input field consisting of a month, day and year.

Format: Creates a day drop down list (xform:select), a month drop down list (xform:select) and a year input field (xform:number). Created fields are named <xform:name>Day, <xform:name>Month, and <xform:name>Year respectively. The xform:calendar may be used to specify a calendar implementation to use in validating the date values. If it is not defined java.util.GregorianCalendar is used.
Validate: Sets the <xform:name>Day, <xform:name>Month, and <xform:name>Year attributes.
Transform: Performs a copy (see details below) and then appends the following attributes: xform:month (month string), xform:monthNum (month number, zero based), xform:day (day number), xform:year (year number), xform:calendar (the implementation of java.util.Calendar used to validate the date values), xform:value (the number of milliseconds from Jan 1, 1970 00:00:00, negative numbers being before Jan 1, 1970).

Class: EmailValidator

Creates a text input field that only accepts valid email formats.

Format: Does nothing.
Validate: Ensures that the email address has an '@', that the '@' is not in the first position or the last position. That there is at least one '.' after the '@' and that it does not contain one of the following characters: `#$%^&*()+=|]}[{";:,><
Transform: Appends the value as a text child node and performs a copy (See copy section below).

Class: ImageValidator

Creates an image button.

Format: Does nothing.
Validate: If the image has been selected set the xform:x value and xform:y value indicating where in the image the selection was made, appends the value to the element.
Transform: Appends the value as a text child node and performs a copy (See copy section below).

Class: NumberValidator

An input that only accepts numbers.

Format: Does nothing.
Validate: Verifies the input value can be interpreted as a number by the java.lang.Double.valueOf() method. Also appends the value as a text child node.
Transform: Appends the value as a text child node and performs a copy (See copy section below).

Class: SelectValidator

The validator for a selection list. The selection list contains elements of type xform:choice (see ChoiceValidator above).

Format: Does nothing.
Validate: Sets the value to the selected choice.
Transform: Performs a copy (See below) and removes all enclosed xform:choice elements.

Copy Section

Many of the input types, the root node and any node in the xform name space not listed above is copied from the input document to the output document after validation according to the following process.

If the element has an xform:remove attribute the element and all enclosed children are removed. Nothing is added to the result and the copy is complete.

Otherwise if the xform:name attribute is specified the new element name will be set to that value. This may be a fully qualified name or a simple name. If a simple name is specified the element will not have a name space defined. If not specified and the element is in the xform namespace the result element will be called xform:unknown; otherwise the element will be cloned. Next any attributes that are not in the xform name space are copied to the result and the result returned.

If the prefix (xform in our examples) of the new element is not known in the current transform its URI may be specified with the xform:NS attribute. If the name space is known this attribute is ignored.

Configuration

ImagoX Forms is a good candidate for the Launcher mechanism, otherwise it must create a new instance of the field validators on each request. The configurations passed to the ImagoForm class must list the input types and classes that will validate those types. The types listed in the configuration file become valid xform:type attribute values for the xform:input elements.

ImagoX extension configuration information is available here. The following configuration lines go into the imago.properties file.

The method of configuring Forms depends upon the choice of configuration style. The two styles are shown below.

Launcher-style configuration

init.Launcher.class.Forms=org.xenei.imagoX.forms.ImagoForm

            init.Launcher.init.Forms.number=org.xenei.imagoX.forms.NumberValidator

            init.Launcher.init.Forms.date=org.xenei.imagoX.forms.DateValidator

            init.Launcher.init.Forms.image=org.xenei.imagoX.forms.ImageValidator

            init.Launcher.init.Forms.email=org.xenei.imagoX.forms.EmailValidator

            init.Launcher.init.Forms.choice=org.xenei.imagoX.forms.ChoiceValidator

            init.Launcher.init.Forms.select=org.xenei.imagoX.forms.SelectValidator

imago.properties-style configuration

org.xenei.imagoX.forms.ImagoForm.number=org.xenei.imagoX.forms.NumberValidator

            org.xenei.imagoX.forms.ImagoForm.date=org.xenei.imagoX.forms..DateValidator

            org.xenei.imagoX.forms.ImagoForm.image=org.xenei.imagoX.forms.ImageValidator

            org.xenei.imagoX.forms.ImagoForm.email=org.xenei.imagoX.forms.EmailValidator

            org.xenei.imagoX.forms.ImagoForm.choice=org.xenei.imagoX.forms.ChoiceValidator

            org.xenei.imagoX.forms.ImagoForm.select=org.xenei.imagoX.forms.SelectValidator

Sample Form XML

Below is a simple XML example of an ImagoX Form.

<?xml version="1.0"?> <!DOCTYPE document SYSTEM "imago.dtd"> <document xmlns:xform="http://xenei.org/imago/XForm/2003"> <meta> <title>ImagoX Form Example</title> <author> <name>webmaster</name> <email>webmaster@xenei.org</email> </author> </meta> <content> <xform:root name="formRoot"><xform:form> <test name="Name"><xform:input xform:name="name" xform:type="text"/></test> <test name="Password"><xform:input xform:name="pw" xform:type="password"/></test> <test name="Number"><xform:input xform:name="number" xform:type="number"/></test> <test name="Email"><xform:input xform:name="email" xform:type="email"/></test> <test name="Date"><xform:input xform:name="date" xform:type="date"/></test> </xform:form></xform:root> </content> </document>

Once the above XML has been validated the result would be the following document:

<!DOCTYPE document SYSTEM "imago.dtd"> <document xmlns:xform="http://xenei.org/imago/XForm/2003"> <meta> <title>ImagoX Form Example</title> <author> <name>webmaster</name> <email>webmaster@xenei.org</email> </author> </meta> <content> <formRoot> <test name="Name"><name>My Name</name></test> <test name="Password"><pw>MyPassword</pw></test> <test name="Number"><number>123</number></test> <test name="Email"><email>someone@xenei.org</email></test> <test name="Date"><date xform:monthNum="6" xform:day="10" xform:year="1959" xform:calendar="java.util.GregorianCalendar" xform:month="May" xform:value="11292897198"/></test> </formRoot> </content> </document>