To help in our exploration of XForms we consider a specific example: an XForms Credit Card Verifier. This example displays a simple form asking for a credit card number and related information to be entered, as shown on the screenshot to the right. The information entered by the end-user is validated by a set of rules and errors are flagged in red.

First, the information contained in the form is stored in an XML document called an XForms instance, which is the skeleton or shell that will contain the data captured by the form. You define an XForms instance within an xforms:instance. In the Credit Card Verifier the unique XForms instance is declared with:

The XForms instance does not have to be empty of data: it can contain initial values for the form. Here we set the valid element to the value "false" by default:

XForms instances are always contained in an XForms model, which:

1. Declares one or more XForms instance.

2. Optionally, declares a set of rules attached to the XForms instances.

3. Optionally, declares submissions.

At a minimum, the XForms instance above must be encapsulated as follows:

Note that instances and models can have an optional id attribute. If you have only one model and one instance, the id is optional, but it becomes very convenient when more than one model or instance are used.

In addition to one or more XForms instances, an XForms model can declare a set of "rules", called "model item properties". Let's write a set of rules for the above Credit Card Validation form. Specifically we want to:

1. Check that the credit card number is a number and valid according to particular credit card rules

2. Check that the expiration month is valid (integer between 1 and 12)

3. Check that the expiration year is valid (4 digit number)

4. Display the "verification code" line only if the card type is Visa or MasterCard

5. Check that the verification code is valid only for Visa or MasterCard

You describe each one of those rules with an <xforms:bind> element in the XForms model. Rules apply to elements and attributes in the XForms instance. You specify the elements and attributes each rule applies to with an XPath expression in the mandatory nodeset attribute. In addition to the nodeset attribute you want to have at least one attribute specifying the essence of the rule. We go over the all the possible attributes later in this section, but first let's see how we can express the above rules for the Credit Card Verifier form:

1. You specify that the credit card number must be a number with:

   <xforms:bind nodeset="number" type="xs:integer"/>

   The value of the type attribute is a W3C XML Schema simple type. You can see the list of simple types in the XML Schema primer. If the end-user enters an invalid credit card number (i.e. not a number), an error will be displayed as shows in the screenshot on the right.

2. You can also constrain the value of an element or attribute with an XPath expression in the constraint attribute. For instance you specify that the expiration month must be an integer between 1 and 12 with:

   <xforms:bind nodeset="expiration-month" constraint=". castable as xs:integer and . >= 1 and 12 >= ."/>

   Note that we have decided here not to bother checking the expiration month if no credit card number was entered.

3. Similarly, you check that the expiration year is a 4 digit number with:

   <xforms:bind nodeset="expiration-year" constraint=". castable as xs:integer and string-length(.) = 4"/>

4. You hide the "verification code" text field for American Express cards with:

   <xforms:bind nodeset="verification-code" relevant="../type = 'visa' or ../type = 'mastercard'"/>

   The attribute we use here is relevant. By default, everything is relevant in the XForms instance. If a "relevant" rule is specified, the XPath expression is evaluated for each node in the nodeset, and if the expression returns false, then the node is not considered relevant. When a node is not relevant, the corresponding widget is not displayed (more on this later).

5. Finally, you check that the verification code is entered for Visa and Mastercard:

   <xforms:bind nodeset="verification-code" constraint="/credit-card/type = ('visa', 'mastercard') and . castable as xs:positiveInteger"/>

   Because the verification-code element has both a relevant and a constraint attribute, we combine them on the same xforms:bind:

   <xforms:bind nodeset="verification-code" relevant="../type = 'visa' or ../type = 'mastercard'" constraint="/credit-card/type = ('visa', 'mastercard') and . castable as xs:positiveInteger"/>

XPath expressions in xforms:bind are by default relative to the root element of the first XForms instance. This allows you to write the first constraint above:

• Relatively to the root element of the first XForms instance:

  <xforms:bind nodeset="number" type="xs:integer"/>

• With an absolute path in the first XForms instance:

  <xforms:bind nodeset="/credit-card/number" type="xs:integer"/>

• Referring explicitly to the "credit-card-instance" using the instance() function:

  <xforms:bind nodeset="instance('credit-card-instance')/number" type="xs:integer"/>

Now that we have seen a few examples of model item properties, let's go over all the XForms model item properties. Model item properties can essentially be used for 3 purposes:

Validation	The purpose of validation is to determine if the content of an element or attribute in the XForms instance is valid. Invalid values can have an impact on how a form is displayed (you might want to highlight errors and show some information to help the end-user to correct the issue). Also, the XForms engine makes sure that invalid data cannot be submitted. There are 3 ways to validate the content of an element or attribute: required ― You can specify in the required attribute an XPath expression that determines if a value is required. The XPath can be as simple as true(), or more complex and depend on other values entered by the end-user. By default values are not required. type ― In the type attribute you can specify a W3C XML Schema simple type. The type attribute complements the required attribute, but applies separately. In Addition, some XML schema types have special behavior: xs:date ― The input field is complemented by a pop-up calendar. The user can enter a date manually, or use the calendar to select a date in the past or in the future. You can customize the calendar by copying the files in orbeon-resources-public.jar under ops/javascript/jscalendar to your resources directory. Your modified files in the resources will have a precedence over those found in orbeon-resources-public.jar. constraint ― The constraint attribute supports any XPath expression that returns a boolean value. If false() is returned, then the value is considered invalid, otherwise it is considered valid.
Calculation	The purpose of calculations is to dynamically compute values. You do this with the calculate attribute: calculate ― The content of the element or attribute will be set to the result of the evaluation of the XPath expression in the calculate attribute. This way you can automatically compute some values in the XForms instance based on other values, typically entered by the end-user. By default, nodes that contain calculated values are read-only.
Visibility	In general XForms instance nodes are not read-only and are relevant, which means that if an XForms control is bound to that node (e.g. a text field), the control is displayed and is editable by the end-user. You can change this by providing XPath expressions in the readonly and relevant attributes: readonly ― If the XPath expression in readonly evaluates to true, the control will be displayed in non-editable mode. Typically, in an XHTML user interface only the current value is displayed, instead of displaying a form element, like a text field. relevant ― If the XPath expression in relevant evaluates to false, the control will not be displayed at all.

XForms controls are similar to HTML form elements: they include text fields, drop down lists, checkboxes, etc. These are some differences between HTML forms elements and XForms controls:

• The value displayed by an XForms control comes from a node of the XForms instance. When you declare a control, you bind it to a node of your XForms instance with an XPath expression in the ref attribute. For instance this text field a text field is bound to the <number> element, which a child of <credit-card>:

  <xforms:input ref="/credit-card/number"/>

• The way a control is rendered depends on model item properties that apply to the node the control is bound to: if it is bound to an invalid node then an error can be displayed; if the control is bound to a read-only node the value is displayed in read-only mode; if the node is not relevant the control isn't be displayed at all; if the control is bound to a non-existing node, the control is considered non-relevant and is not displayed;

The table below lists all the available XForms controls and shows for each one the XML you need to use in your view, as well as an example showing that control in action.

Control	XForms in the view	Example
Text field	<xforms:input ref="text"/> xforms:input supports the following extension attributes: xxforms:size: equivalent to the HTML size attribute xxforms:maxlength: equivalent to the HTML maxlength attribute xxforms:autocomplete: equivalent to the HTML autocomplete attribute	XForms Controls
Password field	<xforms:secret ref="secret"/>	XForms Controls
Text area	<xforms:textarea ref="textarea"/> xforms:textarea supports the following extension attributes: xxforms:rows: equivalent to the HTML rows attribute xxforms:cols: equivalent to the HTML cols attribute	XForms Controls
Radio buttons	<xforms:select1 ref="carrier" appearance="full"><xforms:item><xforms:label>Fedex</xforms:label><xforms:value>fedex</xforms:value></xforms:item><xforms:item><xforms:label>UPS</xforms:label><xforms:value>ups</xforms:value></xforms:item></xforms:select1>	XForms Controls
Single-selection lists	<xforms:select1 ref="carrier" appearance="compact"><xforms:item><xforms:label>Fedex</xforms:label><xforms:value>fedex</xforms:value></xforms:item><xforms:item><xforms:label>UPS</xforms:label><xforms:value>ups</xforms:value></xforms:item></xforms:select1>	XForms Controls
Combo box	<xforms:select1 ref="payment" appearance="minimal"><xforms:item><xforms:label>Cash</xforms:label><xforms:value>cash</xforms:value></xforms:item><xforms:item><xforms:label>Credit</xforms:label><xforms:value>credit</xforms:value></xforms:item></xforms:select1>	XForms Controls
Autocomplete box	<xforms:select1 ref="name" selection="open" incremental="true" appearance="xxforms:autocomplete"><xforms:label class="label">Name:</xforms:label><xforms:itemset nodeset="instance('countries-name')/country"><xforms:label ref="name"/><xforms:value ref="name"/></xforms:itemset></xforms:select1>	Auto-Complete
Checkboxes	<xforms:select ref="wrapping" appearance="full"><xforms:choices><xforms:item><xforms:label>Hard-box</xforms:label><xforms:value>box</xforms:value></xforms:item><xforms:item><xforms:label>Gift</xforms:label><xforms:value>gift</xforms:value></xforms:item></xforms:choices></xforms:select>	XForms Controls
List	<xforms:select ref="taste" appearance="compact"><xforms:item><xforms:label>Vanilla</xforms:label><xforms:value>vanilla</xforms:value></xforms:item><xforms:item><xforms:label>Strawberry</xforms:label><xforms:value>strawberry</xforms:value></xforms:item></xforms:select>	XForms Controls
Trigger button	<xforms:trigger><xforms:label>Add carrier</xforms:label></xforms:trigger>	XForms Controls
Submit button	<xforms:submit submission="main-submission"><xforms:label>Submit</xforms:label></xforms:submit>	-
Submit link	<xforms:submit submission="main-submission" appearance="minimal"><xforms:label>Submit</xforms:label></xforms:submit>	-
Submit image	<xforms:submit submission="main-submission" appearance="minimal"><xforms:label><xhtml:img src="images/submit.gif" alt="Submit"/></xforms:label></xforms:submit>	-
Upload	<xforms:upload ref="files/file[1]"><xforms:filename ref="@filename"/><xforms:mediatype ref="@mediatype"/><xxforms:size ref="@size"/></xforms:upload>	Upload Control
Range	<xforms:range ref="range/value"><xforms:send submission="countries-submission" ev:event="xforms-value-changed"/></xforms:range>	XForms Controls

In the examples above, the labels and values for the select and select1 controls are declared in the control element with multiple <xforms:item> elements. Alternatively the label/value pairs can be pulled out from the instance. You do this with an <xforms:itemset> element (instead of <xforms:item> elements):

Nested inside each XForms control element, you can specify additional elements that can alter the way the control is displayed. The table below lists those elements:

Label		The label element is mandatory for all controls.
Alert		In each control you can specify an error message that can be displayed if the value entered by the user triggers a validation error. <xforms:secret ref="secret"><xforms:alert>Invalid password</xforms:alert></xforms:secret>
Hint		You can specify a hint on each control, which shows up as a hint when users mouse over the control. <xforms:textarea ref="textarea"><xforms:hint>Enter at least 11 characters</xforms:hint></xforms:textarea>
Help		If you specify a help message for a control, an icon with a question mark is displayed next to the control. When users click on the help icon, a dialog is displayed with the help message. The <xforms:help> can contain XHTML, or if you bind it to a node, the node can contain escaped XHTML. <xforms:input ref="date" class="xforms-date"><xforms:label class="fixed-width">Birth date:</xforms:label><xforms:help><div><p>This field must contain:</p><ul><li>a valid date</li><li>which is at most one day in the future</li></ul></div></xforms:help></xforms:input> The help dialog has a default with of 300px defined in xforms.js. To use a different width, override this default with: .xforms-help-panel { width: 600px; } By default, the help dialog will stretch vertically as needed so all the text in your help is visible. Then users can use the browser vertical scrollbar to navigate through the text. If instead you want the dialog to have a fixed height and scrollbars inside the dialog when the text doesn't fit that height, use CSS as in: .xforms-help-panel .bd { height: 300px; overflow: auto; }

In the examples above, the text displayed is directly in the <xforms:label>, <xforms:alert>, <xforms:help>, or <xforms:hint> element. Alternatively that text can come from an XForms instance by using a ref attribute on any one of those elements. The ref references a node in the instant that contains the text to use. This is useful to externalize resources:

Alternatively, you can nest xforms:output elements:

With xforms:help and xforms:hint, you can also produce HTML, in two different ways:

• By using literal XHTML under xforms:help or xforms:hint:

  <xforms:input ref="number"><xforms:label>Number</xforms:label><xforms:help><div><p>This field must contain one of the following values:</p><ul><li>One</li><li>Two</li><li>Three</li></ul></div></xforms:help></xforms:input>
  Note

  Elements in the XHTML namespace and in no namespace are supported.

• By using a nested xforms:output with a text/html mediatype:

  <xforms:input ref="number"><xforms:label>Number</xforms:label><xforms:help><xforms:output mediatype="text/html" ref="instance('resources')/help/number"/></xforms:help></xforms:input>

  In this case, the node pointed to by the ref attribute must contain escaped HTML:

  <xforms:instance id="resources"><resources><help><number>&lt;div>&lt;p>This field must contain one of the following values:&lt;/p> &lt;ul>&lt;li>One&lt;/li> &lt;li>Two&lt;/li> &lt;li>Three&lt;/li>&lt;/ul>&lt;/div></number></help></resources></xforms:instance>

  If you want to have literal XHTML instead of escaped HTML in your resources, you can use the value attribute on xforms:output and the xxforms:serialize extension function:

  <xforms:input ref="number"><xforms:label>Number</xforms:label><xforms:help><xforms:output mediatype="text/html" value="xxforms:serialize(instance('resources')/help/number/*, 'html')"/></xforms:help></xforms:input>

  In this case, the resources instance contains:

  <xforms:instance id="resources"><resources><help><number><div><p>This field must contain one of the following values:</p><ul><li>One</li><li>Two</li><li>Three</li></ul></div></number></help></resources></xforms:instance>

You can mix and match literal XHTML and xforms:output

XForms allows you to upload files with the XForms Upload control:

The related section of the XForms model can look like this:

The file element is the element storing the result of the file upload. The result can be stored in two ways:

• As a URL, by specifying the type xs:anyURI.
• As Base64-encoded text, by specifying the type xs:base64Binary. Base64 is a mechanism to encode any binary data using a 65-character subset of US-ASCII. Using this mechanism allows embedding binary data into XML documents, at the typical cost of taking 50% more space than the original binary data. For more information, please refer to the RFC.

The optional xforms:filename, xforms:mediatype, and xxforms:size (the latter being an extension) allow storing metadata about an uploaded file:

• xforms:filename: stores the file name sent by the user agent
• xforms:mediatype: store the media type sent by the user agent
• xxforms:size: stores the actual size in bytes of the uploaded data

Note that the file name and the media type are provided by the user agent (typically a web browser) and are not guaranteed to be correct.

The result of a file upload can look as follows when using xs:anyURI:

The contents of the file can be retrieved using the URL Generator. The result will be an XML document containing a single root element containing the uploaded file in Base64-encoded text.

The result of a file upload can look as follows when using xs:base64Binary:

In this case, the uploaded file is encoded an directly embedded into the XML instance. This is a good method to handle small files only, because the entire file is converted and stored in memory.

A very common requirement of user interfaces consists in repeating visual elements, such as rows in a table or entries in a list. Those repeated sections usually have an homogeneous aspect: they all have the same or a very similar structure. For example, multiple table rows will differ only in the particular content they display in their cells. An example of this is an invoice made of lines with each a description, unit price, and quantity.

XForms provides a very powerful mechanism to implement such repeated structures: the xforms:repeat element. You use xforms:repeat around XHTML elements or XForms controls. For example, to repeat a table row, you write: