Use XForms in Your XML Documents

You may be accustomed to creating forms in HTML. XForms, an XML vocabulary, allows you to take a step up from HTML or XHTML forms.

A key advantage of most XML vocabularies is that they’re more structured than, say, a Microsoft Word document. Most XML is pretty predictable, at least as far as structure goes. Likewise, forms are more structured than free-flowing documents. Taken in combination, XML and forms seem to have been made for each other. Instead of creating documents from scratch, a more fill-in-the-blanks approach becomes possible. As a bonus, this works both for creating a new XML document and for editing existing XML.

XForms (http://www.w3.org/MarkUp/Forms/), which became a W3C recommendation in October 2003, makes it possible to define XML form templates that can be used to create or edit other XML snippets. While a few proprietary solutions are around for creating forms data, XForms is generally a better choice because it is free to implement or use and it is open standards-based. Open standards have a proven track record of being more flexible, more compatible, and less expensive than proprietary alternatives.

XForms is also generally considered a better choice than classic HTML or XHTML forms, which tend to rely heavily on JavaScript and don’t work with XML in any case. Another benefit of XForms is that it provides declarative actions for most, if not all, of the cases where JavaScript is required.

Anatomy of an XForms Document

XForms has been carefully specified as a markup module that can be reused in various host languages, such as SVG (http://www.w3.org/Graphics/SVG/) or more commonly XHTML (http://www.w3.org/MarkUp/). In fact, as of this writing, XHTML Version 2.0 (http://www.w3.org/TR/xhtml2/) is slated to include XForms as a core part of the document language.

Essentially, XForms documents consist of a host language sprinkled with small islands of XForms markup. One such island, called the XForms Model, contains a description of what the form is all about, without getting into details of how the form should look. This is an important design consideration, because on the whole, not every form will automatically have a specific visual component. Consider telephone and speech interfaces, Braille displays, phones, PDAs, and even universal remote controls, and you’ll get an idea of the wide range of possibilities. For now, though, we’ll concentrate on visual-centric forms for the desktop.

Example 4-15 is an example of an XForms Model (a fragment, really) that edits a simple purchase order vocabulary, loosely based on Universal Business Language or UBL (http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=ubl).

Example 4-15. XForms Model with inline instance data

<model id="m1">

 <instance>
  <my:Invoice>
   <my:InvoiceLine>
    <my:Quantity unitCode="PKG">5</my:Quantity>
     <my:Item>
      <my:Desc>Box of Protractors; 500 count<my:Desc>
     </my:Item>
    </my:InvoiceLine>
   </my:Invoice>
 </instance>
 <bind nodeset="my:InvoiceLine/my:Item/my:Desc" required="1"/>
 <submission id="s" method="put" action="po.xml"/>
</model>

This model is wrapped in a model element (http://www.w3.org/TR/xforms/index-all.html#structure-model), followed by an instance element (http://www.w3.org/TR/xforms/index-all.html#structure-model-instance). Notice that a few XML namespaces are in use here (declared elsewhere): the default namespace is that of XForms (http://www.w3.org/2002/xforms), and the instance data itself some other namespace, mapped to the prefix my:. In this example, the instance data is directly included inline (lines 3 through 10), though in many cases it’s more convenient to load and save it from an external URL.

Besides the instance data, the example also shows a bind element (http://www.w3.org/TR/xforms/index-all.html#structure-bind-element) on line 12, which applies to all the my:Desc elements, marking them as required. The syntax of the nodeset attribute is XPath (http://www.w3.org/TR/xpath), another W3C language designed for selecting parts (called node-sets) of XML out of a bigger whole. Notice that the document or root element of the instance data, my:Invoice, is implied—since XML can only ever have a single root element, it’s not necessary to repeat that bit of information. The required attribute simply indicates that all of the XML selected by the nodeset attribute should be flagged as required. XForms includes a number of properties, described later, that can be applied in this way across node-sets.

XForms defines several properties that can be applied to instance data using the bind element (browse the URLs to see examples):

type

A W3C XML Schema datatype, used to fine-tune the presentation of the form control (http://www.w3.org/TR/xforms/index-all.html#model-prop-type).

readonly

An XPath expression to control whether the form control is considered read-only (http://www.w3.org/TR/xforms/index-all.html#model-prop-readOnly).

required

An XPath expression to control whether the form control is required to be filled before submission (http://www.w3.org/TR/xforms/index-all.html#model-xformsconstraints).

relevant

An XPath expression to control whether the form control is considered relevant—non-relevant controls typically are not rendered, and the data they contain is pruned from what gets submitted (http://www.w3.org/TR/xforms/index-all.html#model-xformsconstraints).

calculate

An XPath expression that is automatically computed to provide a data value dependent on other values in the form data (http://www.w3.org/TR/xforms/index-all.html#model-xformsconstraints).

constraint

An XPath expression that must evaluate to a truth value in order for the form control to be considered valid. Whether a control is valid or not affects its rendering, which can be fine-tuned through CSS (http://www.w3.org/TR/xforms/index-all.html#model-xformsconstraints).

p3ptype

A special identifier, based on the W3C recommendation Platform for Privacy Preferences 1.0 (http://www.w3.org/TR/P3P/), indicating the specific nature of the data collected (http://www.w3.org/TR/xforms/index-all.html#model-xformsconstraints).

Back to Example 4-15, the submission element (http://www.w3.org/TR/xforms/index-all.html#structure-model-submission) on line 13 defines the behavior of this form when it comes to submitting the data. The action attribute gives the URL to which the data is to be submitted (in this example, the relative URL po.xml). The method attribute, taken in combination with this URL, says that the form data is to be written back to disk (if the form is loaded from disk to begin with), or else written back to the Web through an HTTP PUT method (if the form is loaded from the Web).

A separate component of the form—the visible (or perhaps audible) part—is called the XForms User Interface, shown partially in Example 4-16.

Example 4-16. XForms User Interface repeating items

<repeat id="lineitems" nodeset="my:ItemLine">

 <group>

  <range ref="my:Quantity" incremental="true"
              start="1" end="9" step="1">
   <label>Quantity <output ref="."/></label>
  </range>

  <select1 ref="my:Quantity/@unitCode">
   <item>
    <label>Package</item>
    <value>PKG</item>
   </item>
   <item>
    <label>Unit</label>
     <value>UNIT</value>
   </item>
  </select1>
   <label>Description</label>
  </input>

 </group>
</repeat>

This example is wrapped by a repeat element (line 1), which indicates that the contents of that element are set to repeat as many times as needed. While not shown here, simple controls can be added to dynamically add and remove repeated rows, which at the same time will add or remove elements from the instance data. The repeating contents are wrapped in a group element (line 2), useful in the context of CSS, which can be used to lay out the repeating items as needed. In fact, nearly all aspects of a form control’s appearance can be conveniently styled through CSS.

The first form control is range (lines 4-7), something not present in classic XHTML forms. It represents a slider control, in this case offering a choice from 1 (start attribute) to 9 (end attribute). Every data collection control has a required label element (lines 6, 11, 15, and 21), which forces authors to think about the purpose of each control and include the needed text or markup to describe the intent behind each form control. In the case of the range control, the label contains an output element (line 6), which renders much the same as plain text but dynamically updates along with the form data. The attribute ref (line 6) contains an XPath expression pointing into the instance data, giving the location where data entered from this form control is stored—in this case, the current node (.) my:Quantity for a item line. The incremental attribute (line 4) causes data updates to happen more immediately than they otherwise might.

The second form control is select1 (line 9), which, yes, includes the digit 1 in the element name. This form control is the appropriate choice when selecting a single item from a list of possibilities. It contains several item elements (lines 10 and 14), each of which contains a label element (lines 11 and 15), indicating the human-readable label for each choice, as well as a value element (lines 12 and 16), indicating the value that gets stored in the XML. As before, the ref attribute (line 9) contains an XPath indicating where in the instance data the stored data goes. Notice the use of the @ abbreviation, which accesses the unitCode attribute of the Quantity element.

The third form control is input (line 20), indicating the intent of basic free-text entry. A real-world purchase order would have additional form controls (like the ever-important price of each line item), but this example omits them in the name of brevity.

The form controls defined in XForms (http://www.w3.org/TR/xforms/index-all.html#controls), chosen in such a way that the element name indicates the intent of the control, are:

input

Entry of freeform value (http://www.w3.org/TR/xforms/index-all.html#ui-input).

textarea

Entry of large amounts of freeform text (http://www.w3.org/TR/xforms/index-all.html#ui-textarea).

secret

Entry of sensitive information (http://www.w3.org/TR/xforms/index-all.html#ui-secret).

select1

Choice of one and only one item from a list (http://www.w3.org/TR/xforms/index-all.html#ui-selectOne).

select

Choice of zero or more items from a list (http://www.w3.org/TR/xforms/index-all.html#ui-selectMany).

range

Selecting a value from a smooth range (http://www.w3.org/TR/xforms/index-all.html#ui-range).

upload

Selecting a data source such as file upload, scanner, microphone, and so forth (http://www.w3.org/TR/xforms/index-all.html#ui-upload).

trigger

Activating a defined process or script (http://www.w3.org/TR/xforms/index-all.html#ui-button).

submit

Activating submission of the form (http://www.w3.org/TR/xforms/index-all.html#ui-submit).

output

Display-only of form data (http://www.w3.org/TR/xforms/index-all.html#ui-output).

The quickest way to jump into some interactive examples of XForms is to point your browser at some live XForms examples, as in the next two sections.

Simple Approaches to Trying Out XForms

The web site XForms Institute (http://xformsinstitute.com) hosts several live examples of XForms, accomplished through a slick little Macromedia Flash applet called DENG (the Desktop Engine) that implements a large swath of XForms plus XHTML and CSS (see http://claus.packts.net/deng). Since XForms is still relatively new, browser support hasn’t come through yet, so a Flash engine is quite a useful tool.

In addition to live examples, the site contains a view source feature and an online validator (http://xformsinstitute.com/validator/) for XForms documents in various host languages, and the text of O’Reilly’s XForms Essentials (2003) under an open content license.

If you are running IE6 on Windows, another useful approach is a browser plug-in called formsPlayer, made available for free download at http://www.formsplayer.com. This plug-in requires a tiny bit of extra markup in documents, notably an object tag to load the necessary ActiveX bits, but otherwise turns an ordinary IE browser into a full-blown XForms solution. The formsPlayer web site also includes numerous examples, and a lively discussion group hosted at http://groups.yahoo.com/group/formsplayer/.

A Working Example

A fully working example, based on the UBL, can be found online at http://xformsinstitute.com/ubl/. This online example shows many additional useful features of XForms, all put together in a real-world example.

See Also

Micah Dubinko

Get XML Hacks now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.