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:

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.

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:

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:

This is not enough to be functional code: you need to indicate to the xforms:repeat element how many repetitions must be performed. This is done not by supplying a simple count value, but by binding the the element to a node-set with the nodeset attribute. Consider the following XForms instance:

Assuming you want to produce one table row per employee, add the following nodeset attribute:

This produces automatically three xhtml:tr rows. Note that we explicitly use the XForms instance() function, but you may not have to do so if that instance is already in scope. Then you display in each row the content of the first-name element for each employee:

This works because for each iteration, the context node for the ref attribute changes: during the first iteration, the context node is the first employee element of the XForms instance; during the second iteration, the second employee element, and so on.

xforms:repeat may be used purely for display purposes, but it can also be used for interactively editing repeated data. This includes allowing the user to delete and insert rows. Two XForms actions are used for this purpose: xforms:delete and xforms:insert.

xforms:delete is provided with a nodeset attribute pointing to the homogenous collection into which the insertion must take place. It also has an at attribute, which contains an XPath expression returning the index of the element to delete. See how xforms:delete is used in these 3 scenarios:

xforms:insert has a nodeset attribute pointing to the homogenous collection into which the insertion must take place. xforms:insert then considers the last element of that collection (and all its content if any) as a template for the new element to insert: it duplicates it and inserts it into the homogenous collection at a position you specify. The last element of an homogeneous collection therefore always acts as a template for insertions:

The at attribute contains an XPath expression returning the index of the element before or after which the insertion must be performed. The position element contains either after or before, and specifies whether the insertion is performed before or after the element specified by the at attribute.

It is important to note that while it is possible to delete the last element of an homogeneous collection, it becomes then impossible to insert a new element into that collection with XForms 1.0, since there is no longer a template element available in this case (save for using an XML submission with replace="instance"). This means that in general you will want to have at least one element in your collections.

In case you want the user interface to visually appear empty empty when there is "no more" elements in the collection, you can use the tip provided below, which can be used in most situations. The idea is to consider that the last element of the collection is never displayed, but always used as a template for xforms:insert:

You do not want to display that template, however. Therefore you use an xforms:repeat element of the form:

The position() < last() condition tells xforms:repeat to consider all the elements of the collection except the last one. This causes the repetition to display zero iteration when there is one element in the collection, one iteration when there are two, etc. The xforms:insert action, on the other hand, operates on the entire collection including the last element, so that that element can be duplicated:

Another solution involves using an xforms:bind element which makes the last element of the collection non-relevant. This achieves the same result, but requires extra code, so the tip above is usually preferred.

Upon submission, some care must be taken with repeat template. For example, if the first-name element above is required, and the template contains an empty value as above, submission will fail. xforsm:bind statements must then also exclude the last element of the collection:

Insertions and deletions are typically performed when the user of the application presses a button, with the effect of adding a new repeated element before or after the currently selected element, or of deleting the currently selected element. You use an xforms:trigger control and the XPath index() function for that purpose:

or:

Note that we use xforms:action as a container for xforms:insert and xforms:delete. Since there is only one action to execute, xforms:action is not necessary, but it may increase the legibility of the code. It is also possible to write:

or:

Notice in that case how ev:event="DOMActivate" has been moved from the enclosing xforms:action to the xforms:insert and xforms:delete elements.

It is often desirable to nest repeat sections. Consider the following XForms instance representing a company containing departments, each containing a number of employees:

This document clearly contains two nested sections subject to repetition:

• Departments: a node-set containing all the department elements can be referred to with the following XPath expression: instance('departments')/department.

• Employees: a node-set containing all the employee elements can be referred to with the following XPath expression: instance('departments')/department/employees/employee. However, if the context node of the XPath expression points to a particular department element, then the following relative XPath expression refers to all the employee elements under that department element: employees/employee.

Following the example above, here is how departments and employees can be represented in nested tables with XForms:

[TODO: Introduction to events in XForms.]

The ev:observer attribute, defined by the XML Events specification, allows you to register event handlers by specifying an element identifier, instead of embedding the event handler within that element. This is particularly useful to register event handlers on <xforms:instance> elements, which do not allow you to directly embed XML event handlers. The current support is limited to adding the ev:observer attribute on XForms actions under <xforms:model> with the ev:observer attribute referring to a child <xforms:instance>.

Note that you still need to use the ev:event attribute to specify to what event the handler responds.

There are two ways of providing the value to set with <xforms:setvalue>. The first one specifies the value as a literal enclosed in the <xforms:setvalue> element. The second possibility uses the value attribute: the content of the attribute is an XPath expression evaluated in the context of the node the xforms:setvalue element is bound (through the ref attribute). The content of the node pointed to by the ref attribute will be set with the result of the XPath expression provided in the value attribute. The example below and uses two <xforms:setvalue>, each one providing the new value in a different way.

The XForms message action displays a message to the user.

Typically, the content of the message element is the message to render. It can also come from the binding attributes (ref or bind), or from the linking attribute (src). The order of preference is the following:

• Binding attributes
• Linking attribute
• Inline text

The Page Flow Controller supports an MVC architecture that allows pages to be built with a page model and a page view. The page model is in charge of preparing data then sent to the page view for display. Assume the following definitions in your page flow, with a page model and either a static page view:

Or a dynamic XSLT page view:

As always with Orbeon Forms, the page model produces a page model document on its data output, and the page view can access this document on its data input, as shown in the following sections. The page view also has access on its instance input to the current XML submission, which may be an unmodified submission performed on the page (in case the page model doesn't have an instance output), or a submission created or modified by the page model and produced on its instance output. These mechanisms are described in details in the PFC documentation.

The <xforms:instance> element supports an src attribute, able to access the current XML submission using the input:instance URI, as well as the page model data using the input:data URI.

In this scenario, the PFC page model generates an XML document which contains an XForms instance on its data output. A static PFC page view then includes this document using xi:include, as follows:

The use of the URI input:data instructs XInclude processing to dynamically include the data output of the page view, which is produced on the data output of the page model. Note that you can also use the instance input, which then refers to the current XML submission:

You can use a dynamic XSLT page view to perform the inclusion of the instance. XSLT is more flexible than XInclude, but less efficient at runtime. The following example uses the data input of the page view to initialize an XForms instance:

Note the use of xsl:version="2.0" on the root element of the document, which instructs the PFC to process the page view as an XSLT stylesheet.

The following example uses instead the instance input of the page view to initialize an XForms instance:

The use of the XPath doc() function with a URI input:instance instructs XSLT processing to dynamically include the instance input of the page view.