This quick guide is intended to be a condensed version of the documentation.

What is XFL?

eXtensible Form Language (XFL) is an XML transformation language with similarities to eXtensible Stylesheet Language. It is designed to aid the construction of simple to complex HTML forms by automating and simplifying common aspects of form development.

XFL is comprised of three components: an XFL document that defines how a form should be displayed and its values manipulated, a parser which reads XFL documents and outputs HTML forms and a number of extendible classes that provide a simplistic method to validate fields and manipulate data.

How Does XFL Work?

A working XFL form requires two components: a controller class and an XFL document.

The controller class is extended from the XFL parser class and allows you to:

• Add, edit and remove form elements
• Supply data to populate the form
• Handle post data in a standardised manner

The XFL parser converts data and post data to XML, which is used to populate form fields automatically. For example, a form field that has the name company[name] will query the XML document for with the XPath query: company/name.

The XFL document defines the presentation of a HTML form and provides instructions of how field's values should be handled.

Example Controller Class

Example XFL Documentation

There are two differences between HTML and XFL forms:

• XFL forms begin with an XML deceleration and follow a schema
• XFL forms use elements in the XFL namespace to manipulate the form

The purpose of XFL elements should be straight forward. In the above example there is a validate element with a type attribute. In this case, the element means that the parent field must have a value.

Modifying How and When Forms are Processed

To begin processing an XFL document, the process method must be called. In the example controller class above, the is done on the $demo->process(); line.

There are three states of processing in the XFL parser:

1. The form is returned blank (no processing is undertaken)
2. The form is loaded with the array supplied in the onGet method of the controller class
3. Data is posted to the form, which is processed

Setting the Form to Process POST Data

By default the form will be set to process the data submited to the form when the $_POST array exists if the form's method is 'post' or the $_GET array when the forms method is 'get'. This may not be desired in some cases, e.g. if you have more than one form on a page. Forms can be assigned a variable that must be set for them to on into submit processing

$demo->process( 'submit' );

The parser will now only consider the form has been submitted when the $_POST[submit] or $_GET[submit] variable is set, depending on the method of the form.

Once the form has been processed the $_POSTcode> variable will be updated to take into account any data manipulation. This can be accessed in the onSubmit method.

Setting the Form to Load Data

In some cases you may want to load a form with data, e.g. in a content management system. The XFL parser will automatically populate form fields with an array that is returned by the onGet method in the controller class. To populate a form simply name the array keys to correspond to form values. The XFL parser will also populate multi-dimensional field names with multi-dimensional arrays.

To set the form to load data you need to supply a value that is not false (bool) or null to the second value of the process method like so:

$demo->process( 'submit', $_GET['id'] );

The value passed is then created as the class variable, $value, in the controller class. You can use this to load relevant data in the onGet method of the controller class. For example, loading records from a database. Simply return an array in the onGet method to populate the form.

XFL Elements

XFL elements all begin with 'xfl:'. This is know as an XML namespace, which allows you to use elements from two or more families of XML in one document. There are four types of XFL elements: data manipulation elements (format, sanitise), definition elements (value), presentation manipulation elements (foreach), validation elements (collection, file, validate).

Data Manipulation Elements

Data manipulation elements are used to change a value that a field is being populated with. The format element modifies values that are populated from the array supplied in onGet and the sanitise element modifies values that have been submitted to the form.

Format and sanitise functionality can be extended by adding new methods to their classes. See the extending functionality section for more information.

Presentation Manipulation Elements

Presentation manipulation elements are used to change the appearance of the form. There is only one presentation manipulation element, foreach, which repeats sections of a form based on the result of an XPath expression.

Validation Elements

Validation elements are used to validate values submitted to a form. The collection element validates groups of elements, the file element validates file input elements and the validate element validates single fields.

Handling Errors

When a validation element fails validation it will add an error to an array which can be accessed though the $errors class variable. The error to be used can be defined by adding an error attribute to the validation element. If no error attribute has been defined, a generic error will be created. When no errors occur, the onSubmit method will be executed (if it exists), else the form will be output congaing the submitted variables.

To read more about errors, see the error handling section.

Further Resources

The best way to get an understanding of how XFL works is to look at the demos, the source code of which are contained in the latest release.