When building a web application, a recurring task is to write an HTML form, to receive, filter and validate its input and to then use the submitted data or store it into a database. Writing all the code to handle one form can take some time. Writing the code to handle all of your application's forms takes a lot more time.
Web:Extend was started because of the simple fact that using forms is too often a tedious task. Throughout its history, the framework included some kind of form generator that handled filtering and validation on its own. This form generator evolved through various stages to take its current form. What was at first badly written PHP became with time a very efficient form generator, allowing you to boost your productivity without sacrificing code quality, performance or security.
The form module uses XSLT to transform its form files into valid XHTML. Do not worry however, there is a good probability that you won't have to write any XSL stylesheet. In fact, unless you want to customize extensively the resulting form by altering its markup output, you probably won't need to, ever.
The form files are basically XHTML markup along with a few special nodes. The special nodes cover the form configuration and the fields it contains.
A form file has the following structure:
<?xml version="1.0" encoding="utf-8"?> <form> <!-- Header here --> <widgets> <!-- Contents: widgets and embedded HTML here --> </widgets> </form>
The following nodes are defined in this example:
Table 10.1. Main nodes in a form file
| Node | Parent node | Description |
|---|---|---|
form | -- | Root node, no attributes. Contains header nodes (none required) and a mandatory widgets node. |
widgets | form | Root node for the form contents. Contains all widgets along with the embedded XHTML. |
The first line is the XML header. Although not necessarily required, it is recommended to always define it as it allows the parser to detect the encoding of the file.
There is currently four different nodes available.
Table 10.2. Header nodes in a form file
| Node | Parent node | Description |
|---|---|---|
class | form | The form's CSS class. Defaults to block. |
enctype | form | The form's enctype attribute. Do not forget to set it to multipart/form-data when the form permits file uploads. |
formkey | form | Whether to enable the form key protection. Value can be either 0 or 1. Enabled by default. |
method | form | Submit method. Either post or get. Defaults to post. |
uri | form | Target URI of the form. Defaults to the current page, identified by $_SERVER['REQUEST_URI']. |
The following example demonstrates the setting of a few header options:
<?xml version="1.0" encoding="utf-8"?> <form> <formkey>0</formkey> <!-- disable form key protection --> <method>post</method> <!-- uses POST when submitting the form --> <uri>/path/to/target</uri> <!-- target changed to "/path/to/target" --> <widgets> <!-- Contents: widgets and embedded HTML here --> </widgets> </form>
A widget node, child of the widgets node, contains information about a field.
It defines the its type, name, label, value, validators and various other options.
The widget node can contain the following nodes:
Table 10.3. Widget nodes in a form file
| Node | Parent node | Description |
|---|---|---|
class | widget | The widget's HTML class. |
label | widget | Widget's label that will be displayed next to it. For example Username. |
name | widget | Widget's name, also used as the name of the HTML element produced. For example user_name. |
validator | widget | One or more validators associated with this widget. See forms validation. |
value | widget | The widget's default value. |
Selectable widgets can also define a set of options. A root node and two different child nodes exist.
Table 10.4. Selectable widget-specific nodes in a form file
| Node | Parent node | Description |
|---|---|---|
options | widget | Root node for the list of options. Child of widget |
item | options | group | An item that can be choosed from the list of options. |
group | options | group | A non-selectable item that defines a group of other items. Only available for choice and radiobox widgets. |
Here is an example of a form containing a few widgets:
<?xml version="1.0" encoding="utf-8"?> <form> <formkey>0</formkey> <method>post</method> <widgets> <widget type="fieldset"> <widget type="hidden" action="update"> <name>user_id</name> <label>User ID</label> </widget> <widget type="textbox"> <name>user_name</name> <label>Username</label> </widget> <widget type="textbox"> <name>user_email</name> <label>Email</label> </widget> <widget type="checkbox"> <name>user_email_private</name> <label>Keep email private</label> </widget> <widget type="choice"> <name>profile_id</name> <label>Profile</label> <options> <item label="Administrator" value="ADM"/> <item label="Moderator" value="MOD"/> <item label="User" value="USR"/> </options> </widget> <widget type="fieldset"> <class>buttonsfieldset</class> <widget type="submitbutton"/> </widget> </widget> </widgets> </form>
This XML will result in the following form.
The appearance of the form is defined by the default CSS style available in res/wee/form.block.css.
Before applying the stylesheet, res/yui/reset-fonts.css was also applied in order to reset the default styles of the browser.
The form is styled because we used the default HTML class block.
Example form
Note that all widgets that are direct child nodes of widgets will be contained inside an ol structure.
So you will have the following structure for your generated form:
<form> <ol> <li>first widget here</li> <li>second widget here</li> <!-- etc. --> </ol> </form>
A complete widget reference is available separately. It details all the widget types available in the framework.
You can also embed XHTML directly into the form, inside the widgets node.
The following tags are allowed by default:
a, abbr, acronym, address, area, b, bdo, big, blockquote, br, caption, cite, code, col, colgroup, dd, del, div, dfn, dl, dt, em, h1, h2, h3, h4, h5, h6, hr, i, img, ins, kbd, li, map, noscript, object, ol, p, param, pre, q, samp, small, span, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, ul, var
If you need another tag not present in this list, you can add it by customizing the form output.