Orbeon Forms User Guide
- Getting Started
- Core Technologies Reference
- XForms
- Page Flow
- XML Pipelines (XPL)
- Other Technologies Reference
- Processors Reference
- API Reference
- Integration
|
XForms Reference: XForms Guide
1. Introduction
Web applications use forms to collect data from users. Orbeon Forms's form handling capabilities are
based on XForms, namely the XForms 1.1 W3C Candidate Recommendation. This section
provides an introduction to XForms concepts and explains how to use XForms in your Orbeon Forms
application.
Note
This document is considered a work in progress. While it does cover some generic features of XForms,
it focuses before all on features specific to the Orbeon Forms XForms engine. For more information
about XForms, please refer to the following resources:
We also recommend that you follow the Orbeon Forms Tutorial first!
This part of the XForms reference documentation focuses on standard XForms features provided by Orbeon
Forms.
2. About XForms
2.1. Origin, Today, and Tomorrow
XForms 1.0 has been designed by the W3C based on experience with HTML forms. It was promoted to the
rank of W3C Recommendation in October 2003, and a second edition of the specification was
released in March 2006. The XForms Working Group at
W3C is as of March 2009 working on XForms 1.1 implementations, and also looking at XForms 1.2
or XForms 2.0. For more information about XForms, please refer to the FAQ.
Mainstream browsers (Internet Explorer, Mozilla / Firefox, Opera, Safari) do not support XForms
natively, although XForms support in Mozilla is under way and plugins are available for Internet
Explorer. However you can leverage the benefits of XForms today by using an Ajax-based XForms
engine like the one provided in Orbeon Forms. The Orbeon Forms XForms engine transparently generates
HTML forms and performs the work that would be done by an XForms-compliant browser, and you can
leverage XForms today within the mainstream browsers that are already deployed in the marketplace.
For more information about the whys and therefores of server-side and Ajax-based XForms engines,
please refer to the FAQ.
2.2. Benefits
Compared to HTML forms, XForms offers a higher level approach to forms. The benefits are that less
programming is needed (less JavaScript, and less
server-side programming), so forms are easier to create and modify. As an
illustration, let's consider some facets of XForms:
-
XML Representation of Forms. XForms clearly defines how data
entered by the end-user is collected: it is stored in an XML document
called an XForms instance, an initially empty, "skeletal" XML
instance document that defines the structure of the data you wish to
collect from the user, which is afterwards filled out with information
collected from the user. For example, credit card information collected
on a web site can be structured as follows:
<credit-card><type/><number/><expiration-month/><expiration-year/></credit-card>
The outcome of the user filling out a form collecting this information
could be this complete XML document:
<credit-card><type>visa</type><number>1234567812345678</number><expiration-month>8</expiration-month><expiration-year>2008</expiration-year></credit-card>
An application using this data to do some processing (e.g. checking the
validity of the credit card) receives the above XML document. There is
no need to write code to go read HTTP request parameters, or to use a
framework performing this task: XForms does it all.
-
Declarative Constraints and Validation. More often than not,
there are constraints on the data that can be entered by the end-user.
For instance, in the example we just considered, the card number must
have 16 digits and the expiration month must be a number between 1 and
12. Traditionally code must be written to check for those constraints.
And more code must be written to handle error conditions (getting back
to the page displaying the form and showing the appropriate error
messages). All this is done is very simple and declarative way with
XForms. For instance, checking that the expiration month is valid number
between 1 and 12 can be done with:
<xforms:bind nodeset="/credit-card/expiration-month" type="xs:integer" constraint=". >= 1 and 12 >= ."/>
An error message can be attached to the "month" text field and if the
end-user enters an invalid month the XForms engine will notice that the
above constraint is not met and will display the error message. You do
not have to write any code for this to happen. We will see later how you
go about doing this with XForms in more details.
-
Declarative Event Handling. User interfaces need to react to
user event such as mouse clicks and character entry. With most UI
frameworks, developers must register event handlers and implement them
in JavaScript, Java, or other traditional imperative languages. With
XForms, a set of predefined event handlers and actions are available,
which cover a set of useful cases without requiring understanding the
complex syntax and semantic of JavaScript or Java. For example, to set a
value into an XForms instance, you write:
<xforms:setvalue ref="/credit-card/expiration-month">11</xforms:setvalue>
Once you have learned the simple built-in XForms actions, you can
combine them in sequences to obtain more complex behavior.
3. Getting Started With the Orbeon Forms XForms Engine
3.1. The XForms Sandbox
The easiest way to get started with simple examples is to use the Orbeon Forms XForms Sandbox. This
tool allows you to upload example XForms files from your web browser and to see the results
directly. You can access the XForms sandbox:
-
Online: visit this link
to access the online public XForms Sandbox.
-
Locally: if this documentation is produced by your local installation of Orbeon
Forms, visit this link.
After submitting an XHTML + XForms file, the result, or errors, should display.
If you have changed your local XForms file, reloads that page in your browser
and this will upload again your local XForms file and the XForms Sandbox will
run the new version. To select another file to upload use your browser quotes
"back" button to return to the main XForms sandbox page.
3.2. Browser Support
[TODO: detail browser support]
4. Programming With XForms
4.1. XForms Model

4.1.1. Introduction
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:
<xforms:instance id="credit-card-instance"><credit-card><type/><number/><expiration-month/><expiration-year/><verification-code/><valid/></credit-card></xforms:instance>
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:instance id="credit-card-instance"><credit-card><type/><number/><expiration-month/><expiration-year/><verification-code/><valid>false</valid></credit-card></xforms:instance>
XForms instances are always contained in an XForms model, which:
-
Declares one or more XForms instance.
-
Optionally, declares a set of rules attached to the XForms instances.
-
Optionally, declares submissions.
At a minimum, the XForms instance above must be encapsulated as follows:
<xforms:model id="main-model"><xforms:instance id="credit-card-instance"><credit-card><type/><number/><expiration-month/><expiration-year/><verification-code/><valid>false</valid></credit-card></xforms:instance></xforms:model>
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.
4.1.2. Model Item Properties
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:
-
Check that the credit card number is a number and valid according to particular credit card rules
-
Check that the expiration month is valid (integer between 1 and 12)
-
Check that the expiration year is valid (4 digit number)
-
Display the "verification code" line only if the card type is Visa or MasterCard
-
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:
-
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.
-
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.
-
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"/>
-
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).
-
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.
-
xs:time ??? [TODO].
-
xs:dateTime ??? [TODO].
-
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.
|
4.2. XForms Controls
4.2.1. Available Controls
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 Controls
|
Password field

|
<xforms:secret ref="secret"/>
|
XForms Controls
|
Text area

|
<xforms:textarea ref="textarea"/>
|
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):
<xforms:select1 ref="country" appearance="compact"><xforms:itemset nodeset="instance('countries')/country"><xforms:label ref="name"/><xforms:value ref="us-code"/></xforms:itemset></xforms:select1>
4.2.2. Label, Alert, Help, and Hint
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:
<xforms:secret ref="secret"><xforms:alert ref="@alert"/></xforms:secret>
Alternatively, you can nest xforms:output elements:
<xforms:secret ref="secret"><xforms:hint><xforms:output value="instance('resources')/help/secret"/></xforms:hint></xforms:secret>
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><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>
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
4.2.3. Upload
XForms allows you to upload files with the XForms Upload control:
<xforms:upload ref="files/file[1]"><xforms:filename ref="@filename"/><xforms:mediatype ref="@mediatype"/><xxforms:size ref="@size"/></xforms:upload>
The related section of the XForms model can look like this:
<xforms:instance id="my-instance"><files><file filename="" mediatype="" size=""/></files></xforms:instance><xforms:bind nodeset="file" type="xs:anyURI"/>
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 :
<file filename="photo.jpg" mediatype="image/jpeg" size="2345">file:/C:/Tomcat/temp/upload_00000005.tmp</file>
Note
The URL stored as the value of the upload is temporary and only valid until either:
-
the session expires,
-
the Java VM quits,
-
or a new file upload replaces the existing URI in the XForms instance.
The URL is only accessible from the server side, and will not be accessible from a client
such as a web browser. It is not guaranteed to be a file: URL, only that it can
be read with Orbeon Forms's URL generator.
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.
Note
Using the xs:anyURI type allows Orbeon Forms to make sure the uploaded file
does not have to reside entirely in memory. This is the preferred method for uploading large
files.
The result of a file upload can look as follows when using
xs:base64Binary :
<file filename="photo.jpg" mediatype="image/jpeg" size="2345">/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAAQDAwQDAwQEBAQFBQQFBwsHBwYGBw4KCggLEA4RERAO EA8SFBoWEhMYEw8QFh8XGBsbHR0dERYgIh8cIhocHRz/2wBDAQUFBQcGBw0HBw0cEhASHBwcHBwc
...</file>
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.
4.3. Repeating with <xforms:repeat>
4.3.1. Basics
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 (but not always) 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:
<xforms:repeat><xhtml:tr>...</xhtml:tr></xforms:repeat>
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:
<xforms:instance id="employees-instance"><employees><employee><first-name>Alice</first-name></employee><employee><first-name>Bob</first-name></employee><employee><first-name>Marie</first-name></employee></employees></xforms:instance>
Assuming you want to produce one table row per employee, add the following nodeset
attribute:
<xforms:repeat nodeset="instance('employees-instance')/employee"><xhtml:tr>...</xhtml:tr></xforms:repeat>
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:
<xforms:repeat nodeset="instance('employees-instance')/employee"><xhtml:tr><xhtml:td><xforms:output ref="first-name"/></xhtml:td></xhtml:tr></xforms:repeat>
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.
4.3.2. Repeat Index
Each <xforms:repeat> element has an associated index, representing the notion
of a currently selected repeat iteration. This information can be used in CSS for example to
highlight the currently selected iteration. The current index for a given repeat can be obtained
with the XPath index() function.
XForms 1.1 has made it clearer that, with nested repeats, each nested repeat keeps its own
index. [TODO: explain more]
Note
XForms 1.1 does not explicitly limit in what type of XPath expressions index()
can be used. However, in Orbeon Forms, it is strongly advised at the moment to only use
index() within actions, and to avoid using it in control bindings and binds, as
doing so may yield unpredictable results.
4.3.3. Deleting Iterations with the <xforms:delete> Action
<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
iterations. Two XForms actions are used for this purpose: <xforms:delete> and
<xforms:insert> .
<xforms:delete> is provided with a nodeset attribute pointing to
the collection of nodes to delete. It also has an optional at attribute, which
contains an XPath expression returning the index of the element to delete. See how
<xforms:delete> is used in these scenarios:
<xforms:delete nodeset="employees" at="last()"/><xforms:delete nodeset="employees" at="1"/><xforms:delete nodeset="employees" at="index('employee-repeat')"/><xforms:delete nodeset="employees"/>
Note
Prior to XForms 1.1, the at attribute was mandatory. Since XForms 1.1, it is
optional, and if omitted the nodeset attribute specifies all the nodes to
remove.
4.3.4. Inserting Iterations with the <xforms:insert> Action
<xforms:insert> has a nodeset attribute pointing to the 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 collection at a position you
specify. The last element of a collection therefore often acts as a template for
insertions:
<xforms:insert nodeset="employees" at="last()" position="before"/><xforms:insert nodeset="employees" at="last()" position="after"/><xforms:insert nodeset="employees" at="1" position="before"/><xforms:insert nodeset="employees" at="1" position="after"/><xforms:insert nodeset="employees" at="last()" position="after"/><xforms:insert nodeset="employees" at="index('employee-repeat')" position="before"/><xforms:insert nodeset="employees" at="index('employee-repeat')" position="after"/>
[TODO: document how using the origin attribute and a template is a better option with XForms 1.1]
Note
Orbeon Forms supports the new XForms 1.1 features as well, including the origin and context attributes. The
XForms 1.1 specification features a more complete list of example.
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.
4.3.5. Using xforms:trigger to Execute Actions
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:
<xforms:trigger><xforms:label>Add</xforms:label><xforms:action ev:event="DOMActivate"><xforms:insert nodeset="employees" at="index('employee-repeat')" position="after"/></xforms:action></xforms:trigger>
or:
<xforms:trigger><xforms:label>Delete</xforms:label><xforms:action ev:event="DOMActivate"><xforms:delete nodeset="employees" at="index('employee-repeat')"/></xforms:action></xforms:trigger>
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:
<xforms:trigger><xforms:label>Add</xforms:label><xforms:insert ev:event="DOMActivate" nodeset="employees" at="index('employee-repeat')" position="after"/></xforms:trigger>
or:
<xforms:trigger><xforms:label>Delete</xforms:label><xforms:delete ev:event="DOMActivate" nodeset="employees" at="index('employee-repeat')"/></xforms:trigger>
Notice in that case how ev:event="DOMActivate" has been moved
from the enclosing xforms:action to the
<xforms:insert> and <xforms:delete> elements.
4.3.6. Nested Repeats
It is often desirable to nest repeat sections. Consider the following
XForms instance representing a company containing departments, each
containing a number of employees:
<xforms:instance id="departments"><departments><department><name>Research and Development</name><employees><employee><first-name>John</first-name></employee><employee><first-name>Mary</first-name></employee></employees></department><department><name>Support</name><employees><employee><first-name>Anne</first-name></employee><employee><first-name>Mark</first-name></employee><employee><first-name>Sophie</first-name></employee></employees></department></departments></xforms:instance>
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:
<xhtml:table><xforms:repeat nodeset="instance('departments')/department"><xhtml:tr><xhtml:td><xforms:output ref="name"/></xhtml:td><xhtml:td><xhtml:table><xforms:repeat nodeset="employees/employee"><xhtml:tr><xhtml:td><xforms:output ref="first-name"/></xhtml:td></xhtml:tr></xforms:repeat></xhtml:table></xhtml:td></xhtml:tr></xforms:repeat></xhtml:table>
In the code above, the second <xforms:repeat> 's nodeset
expression is interpreted relatively to the department element of
the parent <xforms:repeat> for each iteration of the parent's
repetition. During the first iteration of the parent, the "Research and
Development" department is in scope, and employees/employee refers
to the two employees of that department, John and Mary. During the second
iteration of the parent, the "Support" department is in scope, and
employees/employee refers to the three employees of that
department, Anne, Mark and Sophie.
4.4. Events
4.4.1. Introduction
[TODO: Introduction to events in XForms.]
4.4.2. Using the ev:observer and ev:target Attributes
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.
<xforms:model id="main-model"><xforms:instance id="child-instance" src="my-instance.xml"/><xforms:dispatch ev:observer="child-instance" ev:event="xforms-insert" targetid="main-model" name="update-after-insert"/></xforms:model>
Note that you still need to use the ev:event attribute to specify to what event the
handler responds. The following example shows how you can define event handlers for XForms
elements anywhere in an XForms document:
<xhtml:html><xhtml:head><xforms:model id="my-model"><xforms:instance id="my-instance"><instance>initial</instance></xforms:instance><xforms:action ev:observer="my-group" ev:target="my-input" ev:event="DOMFocusIn"><xforms:setvalue ref=".">new</xforms:setvalue></xforms:action></xforms:model></xhtml:head><xhtml:body><xforms:group id="my-group"><xforms:input id="my-input" ref="."><xforms:label>My Data</xforms:label></xforms:input><xforms:action ev:observer="my-model" ev:event="xforms-ready"><xforms:dispatch name="DOMFocusIn" targetid="my-input"/></xforms:action></xforms:group></xhtml:body></xhtml:html>
The above example also shows how you can constrain an event handler to respond to an event
dispatched to a particular target element using the ev:target attribute. here, the
event handler responds to DOMFocusIn events, but only those dispatched to the
my-input control.
4.5. Actions
4.5.1. Setting Instance Values with the xforms:setvalue Action
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.
<xforms:trigger><xforms:label>Submit</xforms:label><xforms:action ev:event="DOMActivate"><xforms:setvalue ref="clicked">my-button</xforms:setvalue><xforms:setvalue ref="flavor" value="concat('van', 'illa')"/></xforms:action></xforms:trigger>
4.5.2. Displaying Messages with the xforms:message Action

The XForms message action (xforms:message ) displays a message to the user.
The message to render can be specified in different ways, in order of precedence:
- Binding attributes (
ref or bind )
- Linking attribute (
src )
- Inline content, including optional
xforms:output elements
xforms:message supports the following values on the level attribute:
-
modal . This standard level specifies taht the message needs to be closed
by the user before any further interaction can take place with the form.
-
xxforms:log-debug , xxforms:log-info ,
xxforms:log-warn and xxforms:log-error . These values cause the
message to be logged on the server using the levels "debug", "info", "warn" and "error"
as per the log4j terminology. Messages output with these levels appear in the
Orbeon Forms logs depending on the configuration of log4j.xml .
The level is optional and defaults to modal .
Note
When using the linking attribute (src ), the value must be an absolute URL,
starting with oxf: , http: or other supported protocols. It is not
recommended to use the src attribute to specify the content of the message.
Simple message:
<xforms:trigger><xforms:label>Test</xforms:label><xforms:message ev:event="DOMActivate" ref="taste"/></xforms:trigger>
Message with nested xforms:output :
<xforms:trigger><xforms:label>Test</xforms:label><xforms:message ev:event="DOMActivate" level="modal">This is your first name:<xforms:output value="first-name"/></xforms:message></xforms:trigger>
Server-side log message:
<xforms:submission>...<xforms:message ev:event="xforms-submit-error" level="xxforms:log-error">A submission error occurred:<xforms:output value="event('error-type')"/></xforms:message></xforms:submission>
5. Validation with XML Schema
[TODO: document schema validation including basics, extensions, inline schemas]
6. XForms Initialization
Upon loading, an XForms document goes through a phase of initialization during which models, instances
and controls are created and prepared.
As a form author, you can hook-up event handlers to perform your own initialization. You usually do this
with either the xforms-model-construct-done or xforms-ready events dispatched
to each model.
In many cases, you can use either event, but there is a significant difference: when
xforms-model-construct-done runs, controls are not yet initialized, and you may obtain
better performance when using that event, as controls don't have to update as a response to actions.
Here are a few things you can do during initialization:
-
Call submissions to load data. For example, you may want to load initial form data from
a database, or load localization resources.
<xforms:model><xforms:send ev:event="xforms-model-construct-done" submission="load-submission"/>...</xforms:model>
-
Prepare data. For example, you may want to perform initial calculations.
<xforms:model><xforms:setvalue ev:event="xforms-model-construct-done" ref="uuid" value="digest(string(random(true)), 'MD5', 'hex')"/>...</xforms:model>
7. XForms Instance Initialization
7.1. Rationale
An XForms page usually needs to contain initial data when first loaded. The data may be inline, come
from a database, from a form submitted on a previous page, etc. This section looks at the different
ways to initialize XForms instances.
7.2. Initializing XForms Instances from the PFC
7.2.1. Page Flow Definitions
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:
<page id="..." path-info="..." model="my-page-model.xpl" view="my-page-view.xhtml"/>
Or a dynamic XSLT page view:
<page id="..." path-info="..." model="my-page-model.xpl" view="my-page-view.xsl"/>
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.
7.2.2. Using the src Attribute
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.
<html><head><title>Summary</title><xforms:model><xforms:instance id="document-infos-instance" src="input:instance"/>...</xforms:model></head><body>...</body></html>
7.2.3. Using XInclude
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:
<html><head><title>Summary</title><xforms:model><xforms:instance id="document-infos-instance"><xi:include href="input:data"/></xforms:instance>...</xforms:model></head><body>...</body></html>
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:
<xforms:instance id="document-infos-instance"><xi:include href="input:instance"/></xforms:instance>
Note
Whenever possible, the use of the <xforms:instance> 's src
attribute is preferable. Doing so may have a positive impact on performance as more caching
can take place.
7.2.4. Using XSLT
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:
<html xsl:version="2.0"><head><title>Summary</title><xforms:model><xforms:instance id="document-infos-instance"><xsl:copy-of select="/*"/></xforms:instance>...</xforms:model></head><body>...</body></html>
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:
<xforms:instance id="document-infos-instance"><xsl:copy-of select="doc('input:instance')"/></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.
Note
You can use XInclude instructions in a dynamic XSLT page view as well. In this case, it is
important to note that XInclude instructions are processed before XSLT instructions, i.e. the result
of XInclude instructions is an XSLT stylesheet, which is then executed.
Note
Whenever possible, the use of the <xforms:instance> 's src
attribute is preferable. Doing so may have a positive impact on performance as more caching
can take place. For performance reasons, we also recommend using static XHTML views instead
of XSLT whenever possible.
7.3. Initializing XForms Instances with an XForms Submission
8. URLs in XForms
8.1. Rationale
XForms documents can refer to external resources using URIs in the following
circumstances:
-
External Instances. The xforms:instance element
can have an src attribute linking to an external instance
definition.
-
Submission. The xforms:submission element must refer
to an action URI.
-
Load Action. The xforms:load action must refer to an
URI that must be loaded upon execution.
-
Image Mediatype. The xforms:output control may refer
to an image URI.
-
Message, Label, Help, Hint, and Alert.
xforms:label , xforms:help ,
xforms:hint , and xforms:alert may use an
src attribute to refer to external content.
Note
The XForms 1.1 draft of November 15, 2004 removes linking attributes
from actions and metadata elements and "the src attribute
is not available to XForms 1.1 message , label ,
help , hint , alert elements."
URIs are resolved relatively to a base URI. The base URI is, by default,
the external URL used to display the XForms page, with special handling of the
servlet context, if necessary. It is also possible to override this behavior by
adding xml:base attributes on xforms:load or any of
its ancestor elements.
8.2. External XForms Instances
Referring to external XForms instances is done with the src
attribute on the xforms:instance element:
<xforms:instance src="instance.xml"/>
This feature allows for improved modularity by separating an XForms instance
definition from an XHTML page. It also allows for producing XForms instances
dynamically.
The following assumes that Orbeon Forms runs in the /ops servlet context:
Base URI (External URL or xml:base attributes)
|
Initial URI (src attribute)
|
Resolved URI |
Comment |
The following URI is loaded in a servlet:
http://a.org/ops/page
|
http://b.com/instance |
http://b.com/instance |
Absolute URLs are left untouched.
|
/new-instance |
http://a.org/ops/new-instance |
Absolute paths resolve against the current servlet context.
|
admin/instance |
http://a.org/ops/admin/instance |
The relative path resolves against the original URL.
|
The following path is loaded in a portlet:
/example/page
|
http://b.com/instance |
http://b.com/instance |
Absolute URLs are left untouched.
|
/new-instance |
/new-instance |
The absolute path is used as is. The XForms instance is loaded from the
portlet. The developer must make sure that the path resolves to a PFC
entry producing XML.
|
admin/instance |
/example/admin/instance |
The relative path is resolved against the original path. The XForms
instance is loaded from the portlet. The developer must make sure that
the path resolves to a PFC entry producing XML.
|
8.3. XForms Submisssion
Specifying a submission URL is done with the resource attribute (or the deprecated, as
of XForms 1.1, action attribute) on the xforms:submission element:
<xforms:submission resource="/submission" ref="..."/>
The following assumes that Orbeon Forms runs in the /ops servlet context:
Base URI (External URL or xml:base attributes)
|
Initial URI (action attribute)
|
XForms Init 1 |
Resolved URI |
Comment |
The following URI is loaded in a servlet:
http://a.org/ops/page
|
http://b.com/submission |
N/A |
http://b.com/submission |
The absolute URL is left untouched. The XForms submission is performed
on the absolute URL.
|
/new-submission |
N/A |
http://a.org/ops/new-submission |
Absolute paths resolve against the current servlet context.
|
admin/submission |
N/A |
http://a.org/ops/admin/submission |
The relative path resolves against the original URL.
|
The following path is loaded in a portlet:
/example/page
|
http://b.com/submission |
N/A |
http://b.com/submission |
The absolute URL is left untouched. The XForms submission is performed
on the absolute URL.
|
/new-submission |
Yes |
/new-submission |
The absolute path is used as is. The XForms submission is performed on
the portlet.
|
No |
http://a.org/ops/new-submission |
The absolute path resolves against the current servlet context. The
submission is performed on the web application.
|
admin/submission |
Yes |
/example/admin/submission |
The relative path is resolved against the original path. The XForms
submission is performed on the portlet.
|
No |
http://a.org/ops/ example/admin/submission |
The relative path resolves against the original path, then against the
the current servlet context. The submission is performed on the web
application.
|
1 If "yes", this means the submission is performed during XForms
initialization, for example upon an xforms-ready event. If "no",
this means that the submission is performed after XForms initialization, for
example upon the user activating a trigger.
8.4. XForms Load Action
The xforms:load action can refer to a resource to load either
through the resource attribute or using a single-node binding
retrieving the URI from an XForms instance. In both cases, the value of the URI
is resolved relatively to the base URI.
The following assumes that Orbeon Forms runs in the /ops servlet context:
Base URI (External URL or xml:base attributes)
|
Initial URI (resource or Single-Node Binding)
|
show
f:url-type |
Resolved URI |
Comment |
The following URI is loaded in a servlet:
http://a.org/c/d
|
http://b.com/e/ |
replace |
http://b.com/e/ |
The absolute URL is left untouched. The new page replaces the existing
page.
|
new |
The absolute URL is left untouched. A new window or tab opens for the new
page.
|
/f |
replace |
http://a.org/c/f |
Absolute paths resolve against the current servlet context. The new page
replaces the existing page.
|
new |
Absolute paths resolve against the current servlet context. A new window
or tab opens for the new page.
|
g |
replace |
http://a.org/c/g |
The new page replaces the existing page.
|
new |
A new window or tab opens for the new page.
|
The following path is loaded in a portlet:
h/d
|
http://b.com/e/ |
replace |
http://b.com/e/ |
This causes the application to load a page outside of the portlet,
replacing the entire portal.
|
new |
This causes the application to load a page in a new window outside of
the portlet.
|
/f |
replace |
/f |
The resulting path is loaded within the portlet.
|
replace
f:url-type= "resource" |
http://a.org/c/f |
The resulting path is loaded in the same window outside the portal.
|
new |
http://a.org/c/f |
The resulting path is loaded in a new window.
|
g |
replace |
h/g |
The resulting path is loaded within the portlet.
|
replace
f:url-type= "resource" |
undefined |
undefined |
new |
undefined |
undefined |
8.5. Image Mediatype for xforms:output
When an xforms:output control refers to an image URI, as documented
below, the resulting value is resolved
relatively to the base URI.
9. XForms and Services
9.1. Introduction
XForms allows an XForms page to perform submissions of XForms instances and to handle a response.
In most cases, both the submitted XForms instance and the response are XML documents.
Note
It is possible to submit an XForms instance with the HTTP GET method. In that case, some
information contained in the XML document is lost, as the structure of the instance, attributes, and
namespace prefixes among others, are not passed to the submission.
The XForms submission feature practically allows forms to call XML services. Those services are
accessible through an XML API, which means that a request is performed by sending an XML document to
the service, and a response consists of an XML document as well.
10. XForms 1.1 Support
10.1. Media Type for <xforms:output>
In XForms 1.0, xforms:output is only used to display text. However, XForms 1.1 supports
a mediatype attribute on that element allowing display of other media types.
10.1.1. Image Types
For the <xforms:output> control to display an image, you
need to:
-
Have a mediatype attribute on the <xforms:output> . That
attribute must refer to an image mediatype, such as image/* or
image/jpeg .
-
Use the value attribute on <xforms:output> or bind to the
control to a node without type, with an xs:anyURI type or with an
xs:base64Binary type.
The resulting value from the instance is interpreted either as a URI pointing to an image, or as
a base64-encoded binary representation of the image. The image will display in place of the
xforms:output . It is possible to dynamically change the image pointed to. For
example:
<xforms:output mediatype="image/*" value="'/images/moon.jpg'"/>
<xforms:model><xforms:instance><image-uri/></xforms:instance><xforms:bind nodeset="image-uri" type="xs:anyURI"/></xforms:model>...<xforms:output mediatype="image/*" ref="image-uri"/>
The image URI may or may no be reachable from the client browser. Orbeon Forms hides this from
the developer. For example, to upload and show an image:
<xforms:group ref="image[normalize-space() != '']"><xforms:output ref="." mediatype="image/*"><xforms:label/></xforms:output></xforms:group><xforms:upload ref="image"><xforms:label/><xforms:filename ref="@filename"/><xforms:mediatype ref="@mediatype"/><xxforms:size ref="@size"/></xforms:upload>
In that example, the upload control stores a temporary URI pointing to a local
file: resource. While this URI is not visible from the client web browser, the
output control automatically proxies it so that the end user can see the image.
10.1.2. HTML Type
When an xforms:output control has a mediatype
attribute with value text/html , the value of the node to which
the control is bound is interpreted as HTML content. Consider the following
XForms instance:
<xforms:instance id="my-instance"><form><html-content>This is in <b>bold</b>!</html-content></form></xforms:instance>
You bind an xforms:output control to the
html-content node as follows:
<xforms:output ref="instance('my-instance')/html-content" mediatype="text/html"/>
This will display the result as HTML, as expected: "This is in bold!". If the
mediatype is not specified, the result would be instead: "This is in
<b>bold</b>!". In the XForms instance, the HTML content must be escaped as text. On
the other hand, the following content will not work as expected:
<xforms:instance><form><html-content>This is in in<b>bold</b>!</html-content></form></xforms:instance>
Note
When using a mediatype="text/html" , an HTML
<div> element will be generated by the XForms engine to hold
the HTML data. As in HTML a <div> cannot
be embedded into a <p> , if you have a
<xforms:output mediatype="text/html"> control, you should
not put that control into a <xhtml:p> .
10.2. origin Attribute on <xforms:insert> Action
Orbeon Forms supports the XForms 1.1 origin attribute on the
<xforms:insert> action. This attribute allows specifying the source node to use as
template. This allows storing templates separately from the node-set specified by the
nodeset attribute. For example:
<xforms:insert nodeset="address" at="last()" position="after" origin="instance('template-instance')"/>
The template copied in this case comes from an XForms instance:
<xforms:instance id="template-instance"><address><street><number/><name-1/><name-2/></street><apt/><city/><state/><zip/></address></xforms:instance>
10.3. context Attribute on <xforms:insert> Action
Orbeon Forms supports the XForms 1.1 context attribute on the
<xforms:insert> action. This attribute allows specifying a context for insertion,
which along with the origin attribute allows inserting content into elements:
<xforms:insert context="instance('main-instance')/books" nodeset="book" origin="instance('book-instance')"/>
With original instances as follows:
<xforms:instance id="main-instance"><instance><books/></instance></xforms:instance><xforms:instance id="book-instance"><book><title>Cosmos</title><author>Carl Sagan</author></book></xforms:instance>
The result of a first insertion is:
<xforms:instance id="main-instance"><instance><books><book><title>Cosmos</title><author>Carl Sagan</author></book></books></instance></xforms:instance>
10.4. validate and relevant Attributes on <xforms:submission>
Orbeon Forms supports the XForms 1.1 validate and relevant attributes
on <xforms:submission> . These boolean attributes disable processing of validation
and relevance respectively for a given submission:
<xforms:submission id="my-submission" method="post" validate="false" relevant="false" resource="http://example.org/rest/draft/" replace="none"/>
For more information, please visit the XForms 1.1 specification.
10.5. serialization Attribute on <xforms:submission>
Orbeon Forms supports the XForms 1.1 serialization on
<xforms:submission> . This is particularly useful to specify the value
none with a get method:
<xforms:submission id="my-submission" method="get" serialization="none" resource="http://example.org/document.xml" replace="instance" instance="my-instance"/>
For more information, please visit the XForms 1.1 specification.
10.6. Preliminary Support for Asynchronous Handling of <xforms:submission>
Orbeon Forms partially supports the XForms 1.1 mode="asynchronous" attribute on
<xforms:submission> . The limitations are:
-
Asynchronous submissions in an Ajax request are delayed until after everything else in the
request has run (including other submissions).
-
Asynchronous submissions are "fire and forget": they only work with
replace="none" and no xforms-submit-done /
xforms-submit-error events are dispatched.
-
All asynchronous submissions started during a given Ajax request run serially.
<xforms:submission id="test-submission" mode="asynchronous" ref="." method="put" resource="http://my.service.com/" replace="none"/>
For more information, please visit the XForms 1.1 specification.
Note
XForms 1.1 specifies that mode="asynchronous" should be the default, but due to the
client-server nature of the Orbeon Forms XForms engine, Orbeon Forms still defaults to
mode="synchronous" .
10.7. Preliminary Support for delay Attribute on <xforms:dispatch> Action
Orbeon Forms partially supports the XForms 1.1 delay attribute on
<xforms:dispatch> . The limitations are:
-
A delay greater than zero always incurs a round-trip with the client. This may mean higher
latency and ressource usage than could be expected. You are advised to use delays in the
order of seconds at least.
-
Events are not combined as specified in XForms 1.1.
-
Custom event context information is not supported and simply ignored.
The boolean xxforms:show-progress attribute allows specifying whether the
client must enable the loading indicator when sending back delay events from the client. The default
is true and the indicator is used.
<xforms:dispatch name="my-event" targetid="my-model" delay="2000" xxforms:show-progress="false"/>
The xxforms:progress-message attribute allows specifying a custom progress message when
xxforms:show-progress is true . By default, the standard progres message is
used.
<xforms:dispatch name="my-event" targetid="my-model" delay="2000" xxforms:show-progress="true" xxforms:progress-message="Autosave..."/>
For more information, please visit the XForms 1.1 specification.
10.8. Conditional Execution and Iteration of XForms Actions
Orbeon Forms supports the XForms 1.1 if and while attributes on XForms
action elements. For more information, please visit the XForms 1.1 specification.
10.9. targetid attribute on xforms:dispatch
As of May 2009, in order to prevent attribute clashes with other specifications, the
targetid attribute supercedes the target on
<xforms:dispatch> . target is still supported for backward compatibility.
10.10. XForms 1.1 Types
Orbeon Forms supports the following XForms types:
-
xforms:dayTimeDuration
-
xforms:yearMonthDuration
-
xforms:email
-
xforms:card-number
These types can be used on binds, e.g.:
<xforms:bind nodeset="my-email" type="xforms:email" required="true()"/>
10.11. XForms 1.1 Functions
[TODO: List all XForms 1.1 functions implemented]
|