ForX is a set of attributes designed to extend existing form functionality with desirable features such as validation, content types, and groups. ForX is based on two principles:
With ForX, you can specify the elements that must be completed before a form can be submitted. To define these requirements, you use
forx:ctype, which can, in addition to existing attributes, be applied to the following elements (list items are linked to appropriate section of the HTML 4.01 reference):
A "group" makes it easier to handle elements that are not associated by default, such as radio buttons. With a conditional requirement you can have a group that's dependent on another element's value or on a literal value.
A form implementing ForX attributes must have a unique
forx:id and the
forx:enabled attribute set to
true to be handled by the engine. To start the engine, you also have to attach the document's
onload handler to the
forxInit() function of the library -- after the library files have been included, of course.
To make sure a user completed the form correctly, you can use an option to enable a warning after the user tried to send a valid form (which doesn't necessarily mean that the data entered is correct). This element is shown only once (if the form remains valid after reviewing). This behavior is managed by
forx:review, which must be set to
true to switch the warning on. The warning element is an empty element (DIV) that's identified by its ID,
forx:review, and class,
Required elements and non-valid elements are marked with a special element, which is defined in the same way as the warning element above. You are generally free to fill the template elements with any content you want; you only need to have the correct ID and class.
The template file contains everything you need to get started. (Use right-click to save, or view source -- the unaltered template file will just view as a blank page!) After that, you should examine the example page for some working demos.
ForX uses its own namespace to avoid conflicts with other elements. The prefix for the namespace is defined as
forx, but it can't be altered due to missing DOM Level 2 support in IE. See implementation details on that. This means that every ForX attribute looks like this:
Every element that is referenced by another ForX element needs to have its own unique
To mark any element as being "required" for the form to process, the
forx:required attribute has to be set to
true. In addition to an unconditional requirement, you can define a simple if-then condition, which will be evaluated before the element is marked as being required. A condition of this type should have the following format:
if element operator value|element
element is some element of the same form. All elements referenced need a
forx:id attribute value.
operator can be
!= (not equal) or
You can use a literal value, or the name of another element on the same form, on the right side of the condition. A literal value is indicated by single or double quotation marks.
Checkboxes and radio buttons can use the keyword
CHECKED instead of using the element's value on the right side. To make an element required only when some other element is checked, you write:
An element is required only when the condition evaluates
true. If a required element has a content type or a regular expression also defined, the element is checked in regard to the content type or regular expression. If the variables don't match, the element is marked as being invalid.
All required elements need to be specifically marked as defined in the template. A template needs to have class
forx and ID
forx:marker to be recognized by the engine. This is how a template should look:
<div id="forx:marker" style="display:inline" class="forx"><b style="color:red">*</b></div>
As long as you meet these requirements, you are free to use whatever you want as your marker. The engine copies this template to all elements and group containers that are required, but not valid.
Elements that allow the user to enter any type of text should be checked to contain a special class of content. For this purpose, ForX defines a set of predefined content types. The content type for an element is defined within the
Predefined content types:
date- Format: mm/dd/yyyy
integer- Integer value
float- Floating point value
number- Any number
phone- Format: +CountryCode (CityCode)
text- Any text
any- Any data
regexp- Indicates a regular expression. This type is only used internally.
If no content type is specified for a required element, it's assumed to have the
any content type.
In those cases where a predefined set of content types is not good enough, a regular expression is the only solution. To use a regular expression, it has to be put into the
Groups are probably one of the most desirable features. Just imagine the following situation: You need a form for an online store that allows customers to pay via invoice or credit card. For the latter, you need additional data such as the number and expiration date for the card.
Previously, "in the old days," you'd write a custom function that forked after it detected the customer's selected payment method. With ForX, you can easily group required elements and make them dependent on other elements.
To create such a group you need two things: a container element and a set of member elements.
The container element is needed to place the marker element into, which reminds the user to fill out required fields. If a group is not valid, the marker template is copied and shown in the group container element. The container element is identified by the
forx:group attribute value -- the name of the group is stored here.
The container element also holds the
forx:required attribute; the behavior is the same as with standard elements.
To highlight all members of a group, you can set the group container's
forx:highlight attribute to
true. A group implementing this feature shows all members with a red background for a few seconds and switches back.
To define the number of elements that must be valid to make the entire group valid, you use the
forx:grouprequires attribute of the group container. You have three options: all elements, any element, or the exact number of elements must be valid. For example:
forx:grouprequires="all" forx:grouprequires="any" forx:grouprequires="3"
To add elements to a group you use the
forx:member attribute. This value must correspond to a group defined by a container element. After adding an element to a group, the requirements are determined using the group container's attributes. You can define content types for all group members, however.
It's not possible to retrieve the value of a group or to nest groups.
See the example pages for working demos.
Copyright © 2009 O'Reilly Media, Inc.