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
1. Scope
Web applications use forms to collect data from users. Orbeon Forms's form handling capabilities are
based on XForms, namely the XForms 1.0 W3C 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!
2. Introduction to 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
W3Cis as of July 2006 working on XForms 1.1, before embarking on XForms 1.2 or XForms 2.0. For
more information about XForms, please refer to the FAQ.
As of July 2006, 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.
4. Programming With XForms 1.0
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:
-
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: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):
<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 is displayed next to the control and
becomes highlighted when the control is selected, or as a tooltip.
<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. A pop-up shows the help message when you position the
mouse cursor over the icon.
<xforms:input ref="date" class="xforms-date"><xforms:label class="fixed-width">Birth date:</xforms:label><xforms:help>This is supposed to be a help message explaining what a birth date is. But since you already know, it mostly serves the purpose
of showing how help messages can be attached to controls, and that they can be pretty long as they can be displayed on multiple
lines.</xforms:help></xforms:input>
|
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>
Warning
The URL stored as the value of the upload is temporary and only valid for the duration of the
current request. It 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 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.
Note
The nodeset attribute of xforms:repeat must point
to a so-called homogeneous collection. Such a collection must consist
of contiguous XML elements with same name and same namespace. XForms does
not predict what happens if the node-set is not homogenous.
4.3.2. Deleting Rows 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 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:delete nodeset="employees" at="last()"/><xforms:delete nodeset="employees" at="1"/><xforms:delete nodeset="employees" at="index('employee-repeat')"/>
4.3.3. Inserting Rows with the xforms:insert Action
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:
<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"/>
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 :
<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><employee><first-name/></employee></employees></xforms:instance>
You do not want to display that template, however. Therefore you use an
xforms:repeat element of the form:
<xforms:repeat nodeset="instance('employees-instance')/employee[position() < last()]">...</xforms:repeat>
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:
<xforms:insert nodeset="employees" at="..." position="..."/>
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:
<xforms:bind nodeset="employee[position() < last()]/first-name" required="true()"/>
Note
If you are dealing with an XML document format which requires
removing the last element of a collection, you have to post-process
your XForms instance to remove such extra elements, and pre-process
it to add such elements when initializing your XForms instance.
4.3.4. 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.5. 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. Actions
4.4.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.4.2. Displaying Messages with the xforms:message Action
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
Note
- The only value currently supported for the
level
attribute is modal . This attribute is optional.
- When using the linking attribute (
src ), the value must
be an absolute URL, starting with oxf: , http:
or other supported protocols.
<xforms:trigger><xforms:label>Test</xforms:label><xforms:message ev:event="DOMActivate" ref="taste"/></xforms:trigger>
4.5. Submission
Two properties control some aspects of XForms submission in Orbeon Forms:
<property as="xs:boolean" name="oxf.xforms.optimize-post-all" value="true"/>
If set to true (the default), Orbeon Forms optimizes submissions with
replace="all" by sending the response of the submission directly to the web browser.
This however means that submission errors cannot be caught by XForms event handlers after Orbeon
Forms has started connecting to the submission URL, as should be the case following XForms 1.0. If
set to false , Orbeon Forms buffers the reply so that errors can be handled as per
XForms 1.0. However, this solution is less efficient.
<property as="xs:boolean" name="oxf.xforms.optimize-local-submission" value="true"/>
-
If set to
true (the default), Orbeon Forms optimizes "local" HTTP and HTTPS
submissions, i.e. submissions performed to a URL controlled by Orbeon Forms itself, by directly
submitting using the Java Servlet API instead of actually using the HTTP protocol for the
submission.
-
If set to
false , Orbeon Forms always always uses the HTTP or HTTPS protocol, which
is less efficient. In this case, it is possible to specify the xxforms:post method
instead of the post method on the xforms:submission element to force
an optimized local submission.
5. XPath Expressions in XForms
5.1. Note About XPath 2.0 Expressions
Orbeon Forms uses an XPath 2.0 implementation instead of an XPath 1.0 implementation as mandated by
XForms 1.0 and XForms 1.1. The main impact of this is that the XForms 1.0 and 1.1 if()
function is not directly available. With Orbeon Forms, you have two options to write conditions
within XPath expressions:
-
Use the xxforms:if() function (note the namespace prefix), which has the same
semantic as the standard XForms 1.0 if() function:
<xforms:setvalue ref="total" value="xxforms:if(../item-price[. = ''], 0, sum(../item-price))"/>
6. Formatting
6.1. Rationale
It is usually recommended to use native XML types within XForms instances, as this guarantees
interoperability and maintainability. For example, a date of January 10, 2005 is stored in ISO
format as: 2005-10-01 . However it is often necessary to format such values on screen
in a user-readable format, like "January 10, 2005", "10 janvier 2005", or "10. Januar 2005".
Orbeon Forms provides an extension attribute, xxforms:format , for that purpose.
xxforms:format must contain an XPath 2.0 expression. In your XPath expression you can
use all the XPath 2.0 functions, including those for date manipulation (external
documentation). However since XPath 2.0 functions don't provide any facility for date and time
formatting, you can in this attribute also use the following XSLT 2.0 functions:
The XPath expression is evaluated by the XForms engine whenever the value bound to the
xforms:input control changes and needs to be updated on screen. It is evaluated in the
context of the instance node bound to the control. This means that the current value of the control
can be accessed with ". ". Often the value must be converted (for example to a date) in
which case the conversion can be done with a XPath 2.0 constructor such as xs:date(.)
or with as cast such as (. cast as xs:date?) .
6.2. xforms:input
When using xforms:input and a bound xs:date type, you can control the
formatting of the date using the xxforms:format extension attribute on the
xforms:input control. For example:
<xforms:input ref="date" xxforms:format="format-date(xs:date(.), '[MNn] [D], [Y]', 'en', (), ())"/>
6.3. xforms:output
When using xforms:output , you can control the formatting of the date using the
xxforms:format extension attribute on the xforms:output control.
<xforms:output ref="date" xxforms:format="format-date(xs:date(.), '[MNn] [D], [Y]', 'en', (), ())"/><xforms:output ref="size" xxforms:format="format-number(., '###,##0')"/>
6.4. Default Formatting
For both xforms:input and xforms:output , if the bound node is of one of
the following types: xs:date , xs:dateTime , xs:time ,
xs:decimal , xs:integer , xs:float , and xs:double ,
and if no xxforms:format attribute is present on the control, formatting is based on
properties. If the properties are missing, a built-in default
formatting is used. The default properties, as well as the built-in defaults, are as follows:
<property as="xs:string" name="oxf.xforms.format.date" value="if (. castable as xs:date) then format-date(xs:date(.), '[FNn] [MNn] [D], [Y]', 'en', (), ()) else ."/><property as="xs:string" name="oxf.xforms.format.dateTime" value="if (. castable as xs:dateTime) then format-dateTime(xs:dateTime(.), '[FNn] [MNn] [D], [Y] [H01]:[m01]:[s01] UTC', 'en', (),
()) else ."/><property as="xs:string" name="oxf.xforms.format.time" value="if (. castable as xs:time) then format-time(xs:time(.), '[H01]:[m01]:[s01] UTC', 'en', (), ()) else ."/><property as="xs:string" name="oxf.xforms.format.decimal" value="if (. castable as xs:decimal) then format-number(xs:decimal(.),'#,##0.00') else ."/><property as="xs:string" name="oxf.xforms.format.integer" value="if (. castable as xs:integer) then format-number(xs:integer(.),'#,##0') else ."/><property as="xs:string" name="oxf.xforms.format.float" value="if (. castable as xs:float) then format-number(xs:float(.),'#,##0.000') else ."/><property as="xs:string" name="oxf.xforms.format.double" value="if (. castable as xs:double) then format-number(xs:double(.),'#,##0.000') else ."/>
They produce results as follows:
-
2004-01-07 as xs:date is displayed as Wednesday January 7, 2004
-
2004-01-07T04:38:35.123 as xs:dateTime is displayed as Wednesday January 7, 2004 04:38:35 UTC
-
04:38:35.123 as xs:time is displayed as 04:38:35 UTC
-
123456.789 as xs:decimal is displayed as 123,456.79
-
123456.789 as xs:integer is displayed as 123,456
-
123456.789 as xs:float or xs:double is displayed as 123,456.789
Note:
-
With the "if" condition in the XPath expressions, a value which cannot be converted to the
appropriate type is simply displayed as is.
-
For values of type xs:time or xs:dateTime, if you wish the time to be
displayed using the current timezone instead of UTC, replace in the value attribute
UTC by [ZN].
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 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>
7.2.3. 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
Using XSLT for page views has an impact for debugging, as the output of XSLT transformations do not
contain valuable location information. For performance and ease of debugging reasons, we recommend
using static XHTML views with XInclude whenever possible.
7.2.4. Using the src Attribute
The xforms:instance element supports an src attribute, able to access the
current XML submission using the input:instance URI.
<html><head><title>Summary</title><xforms:model><xforms:instance id="document-infos-instance" src="input:instance"/>...</xforms:model></head><body>...</body></html>
Note
Note that the URI input:data is not supported in the src attribute.
7.3. Initializing XForms Instances from a URI
TODO (xforms:instance/@src).
7.4. 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 action
attribute on the xforms:submission element:
<xforms:submission action="/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 1.0 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. Read-Only Mode
10.1. Making an Entire Instance Read-Only
You often want to present a form without allowing the user to enter data. An easy solution is to use
the readonly MIP in the model. By making for example the root element of an instance
read-only, all the controls bound to any node of that instance will appear read-only (because the
read-only property is inherited in an instance):
<xforms:instance id="my-form"><form>...</form></xforms:instance><xforms:bind nodeset="instance('my-form')" readonly="true()"/>
10.2. Static Appearance for Read-Only Mode
Sometimes, read-only controls don't appear very nicely in web browsers. For example, a combo box
will appear grayed out. It maybe be hard to read, and there is not much point showing a combo box
since the user can't interact with it. Furthermore, with some browsers, like IE 6 and earlier, it
is not even possible to make disabled controls appear nicer with CSS. In order to make read-only
versions of forms look nicer, Orbeon Forms supports a special extention attribute that allows you
to produce a "static" appearance for read-only controls. You enable this on your first XForms model:
<xforms:model xxforms:readonly-appearance="static">...</xforms:model>
The attribute takes one of two vales: static or dynamic (the default).
When using the value static , read-only controls do not produce disabled HTML form
controls. This has one major limitation: you can't switch a control back to being read-write once
it is displayed as read-only.
You can also set the xxforms:readonly-appearance attribute directly on individual
XForms controls.
See the Government Forms sample application's View Read-Only option for
an example of this feature in action.
11. Extensions
11.1. XForms 1.1 Extensions
11.1.1. Media Type for xforms:output
In XForms 1.0, xforms:output is used to display text. However, based on a proposal
in a draft version of XForms 1.1, Orbeon Forms supports a mediatype attribute on
that element.
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, such as image/* or image/jpeg .
-
Use the value attribute on
<xforms:output> or bind to the control to a node
without type or with an xs:anyURI type.
The resulting value is interpreted a URI pointing to an image. The image
will display in place of the xforms:output . When a single-node
binding is used, 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"/>
Note
It is not yet possible to directly embed image data in an XForms instance
using the xs:base64Binary type.
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> .
11.1.2. origin Attribute on xforms:insert Action
Based on a proposal in a draft version of XForms 1.1, Orbeon Forms supports an
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>
11.1.3. context Attribute on xforms:insert Action
Based on a proposal in a draft version of XForms 1.1, Orbeon Forms supports a
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>
11.1.4. validate and relevant Attributes on xforms:submission
Based on a proposal in a draft version of XForms 1.1, Orbeon Forms supports the
validate and relevant attributes on xforms:submission .
For more information, please visit the XForms 1.1 draft.
11.2. XPath Extension Functions
Orbeon Forms implements some extension functions which can be used from XPath expressions
in XForms documents.
11.2.1. XSLT 2.0 Functions
When using XPath 2.0, the following functions from XSLT 2.0 are also available:
11.2.2. Orbeon Forms Functions
The following functions are implemented:
-
xxforms:if() .
This function implements the semantic of the XForms 1.0 if() function.
See Note About XPath 2.0 Expressions for more details.
-
xxforms:call-xpl($xplURL as xs:string, $inputNames as xs:string*, $inputElements
as element()*, $outputNames as xs:string+) as document-node()* .
This function lets you call an XPL pipeline.
-
The first argument,
$XPLurl , is the URL of the pipeline. It must be an
absolute URL.
-
The second argument,
$inputNames , is a sequence of strings, each one
representing the name of an input of the pipeline that you want to connect.
-
The third argument,
$inputElements , is a sequence of elements to be
used as input for the pipeline. The $inputNames and
$inputElements sequences must have the same length. For each element
in $inputElements , a document is created and connected to an input of
the pipeline. Elements are matched to input name by position, for instance the
element at position 3 of $inputElements is connected to the input with
the name specified at position 3 in $inputNames .
-
The fourth argument,
$outputNames , is a sequence of output names to
read.
-
The function returns a sequence of document nodes corresponding the output of the
pipeline. The returned sequence will have the same length as
$outputNames and will correspond to the pipeline output with the name
specified on $outputNames based on position.
The example below shows a call to the xxforms:call-xpl function:
xxforms:call-xpl ('oxf:/examples/sandbox/xpath/run-xpath.xpl', ('input', 'xpath'), (instance('instance')/input, instance('instance')/xpath),
'formatted-output')/*, 'html')
-
xxforms:evaluate($xpath as xs:string) as item()* .
The xxforms:evaluate() function allows you to evaluate XPath expressions
dynamically. For example:
<xforms:input ref="xxforms:evaluate(concat('instance(''my-instance'')/document', my-xpath))"><xforms:label>...</xforms:label></xforms:input>
-
xxforms:serialize($item as node(), $format as xs:string?) as xs:string .
The xxforms:serialize() function allows you to serialize an XML node to
XML, HTML, XHTML or text. For example:
<xforms:bind nodeset="my-html" calculate="xxforms:serialize(instance('my-instance'), 'html')"/>
-
xxforms:repeat-current($repeat-id as xs:string?) as xs:string .
The xxforms:repeat-current() function allows you to obtain a reference to
an enclosing xforms:repeat 's current iteration node. It takes one optional
string parameter. If present, the id of the enclosing xforms:repeat is
searched. If absent, the function looks for the closest enclosing
xforms:repeat .
<xforms:repeat nodeset="employee" id="employee-repeat"><tr><td><xforms:group ref="instance('control-instance')/input"><xforms:input ref="xxforms:repeat-current('employee-repeat')/name"><xforms:label>Employee Name</xforms:label></xforms:input></xforms:group></td></tr></xforms:repeat>
The xxforms:repeat-current() function must be called from within an
xforms:repeat element.
-
xxforms:context($element-id as xs:string) as xs:string .
The xxforms:context() function allows you to obtain the evaluation context
for an enclosing xforms:group , xforms:repeat , or
xforms:switch . It takes one required string parameter containing the id of
an enclosing XForms element.
<xforms:group ref="employee" id="employee-group"><xforms:group ref="instance('control-instance')/input"><xforms:input ref="xxforms:context('employee-group')/name"><xforms:label>Employee Name</xforms:label></xforms:input></xforms:group></xforms:group>
-
xxforms:instance($instance-id as xs:string) as element()? .
The xxforms:instance() function works like the standard
instance() function except that it searches for instances in all the models
of the XForms document (the standard instance() function only searches
within the current XForms model).
<xforms:model id="main-model"><xforms:instance id="main-instance">...</xforms:instance></xforms:model><xforms:model id="resources-model"><xforms:instance id="resources-instance">...</xforms:instance></xforms:model>...<xforms:group model="main-model"><xforms:output value="xxforms:instance('resources-instance')/titles/company-information"/></xforms:group>
11.2.3. eXForms Functions
eXForms is a suggested set of extensions to XForms 1.0,
grouped into different modules. Orbeon Forms supports the exf:mip module, which includes the
following functions:
-
exf:relevant()
-
exf:readonly()
-
exf:required()
Orbeon Forms also supports the following from the sorting module:
eXForms functions live in the http://www.exforms.org/exf/1-0 namespace, usually
bound to the prefix exf or exforms .
11.3. JavaScript Integration
11.3.1. Rationale
While XForms gets you a long way towards creating a dynamic user-friendly user interface, there
are some dynamic behaviors of the user interface that cannot be implemented easily or at all
with XForms, or you might already have some JavaScript code that you would like to reused. A
JavaScript API is provided to handle those cases, or other use cases involving JavaScript that
you might have.
11.3.2. Getting and Setting Controls Value
In JavaScript, you get the current value of an XForms control var value =
ORBEON.xforms.Document.getValue("myControl") where myControl is the id of
the XForms control, for instance: <xforms:input id="myControl"> .
You set the value of an XForms control with ORBEON.xforms.Document.setValue("myControl",
"42") where myControl is the id of the XForms control, and 42
the new value. Setting the value with JavaScript is equivalent to changing the value of the
control in the browser. This will trigger the recalculation of the instances, and the dispatch
of the xforms-value-changed event. More formally, the Value Change sequence of
events occurs.
As an example, consider you have the model below. It declares an instance with two elements
foo and bar , where bar is a copy of foo ,
implemented with a calculate MIP.
<xforms:model><xforms:instance id="instance"><instance><foo>42</foo><bar/></instance></xforms:instance><xforms:bind nodeset="/instance/bar" calculate="/instance/foo"/></xforms:model>
The input control below is bound to foo , and the output control is bound to
bar . When activated, the trigger executes JavaScript with the
<xxforms:script> action. It increments the value of the input control bound to
foo . When this happens the value displayed by the output control bound to
bar is incremented as well, as bar is a copy of foo .
<xhtml:p><xforms:input ref="foo" id="foo"><xforms:label class="fixed-width">Value of foo:</xforms:label></xforms:input></xhtml:p><xhtml:p><xforms:output ref="bar"><xforms:label class="fixed-width">Value of bar:</xforms:label></xforms:output></xhtml:p><xhtml:p><xforms:trigger><xforms:label>Increment foo with JavaScript</xforms:label><xxforms:script ev:event="DOMActivate">var fooValue = ORBEON.xforms.Document.getValue("foo"); ORBEON.xforms.Document.setValue("foo", Number(fooValue) + 1);</xxforms:script></xforms:trigger></xhtml:p>
11.3.3. Dispatching Events
You can dispatch your own events from JavaScript by calling the function
ORBEON.xforms.Document.dispatchEvent() . The parameters to this function are:
targetId |
Mandatory |
Id of the target element. The element must be an element in the XForms namespace: you
cannot dispatch events to HTML elements. In addition, the id must identify either a
relevant and non-readonly XForms control, or a model object that supports event handlers
such as <xforms:model> , <xforms:instance> , or
<xforms:submission> .
|
eventName |
Mandatory |
Name of the event.
Warning
For security reasons, by default Orbeon Forms prohibits client-side JavaScript
from dispatching any external events except DOMActivate ,
DOMFocusIn and DOMFocusOut . Furthermore, these events
can only be dispatched to relevant and non-readonly XForms controls. In order to
enable dispatching of custom events, you must first add the
xxforms:external-events attribute on the first
<xforms:model> element, for example:
<xforms:model xxforms:external-events="acme-super-event acme-famous-event">...</xforms:model>
This attribute contains a space-separated list of event name. In this example,
you explicitly enable your JavaScript code to fire the two events
acme-super-event and acme-famous-event to any relevant
and non-readonly XForms controls, or to any model object supporting event
handlers. Note that you can only enable custom events, but you cannot enable
standard XForms or DOM events in addition to DOMActivate ,
DOMFocusIn and DOMFocusOut .
Since the event handlers for custom events can be called by JavaScript code that
runs on the client, you need to be aware that these handlers can potentially be
activated by anybody able to load the form in his browser.
|
form |
Optional |
The form object that corresponds to the XForms form you want to dispatch the event to.
This argument is only needed when you have multiple "XForms forms" on the same HTML
page. Typically, this would only happens if you are running your form in a portal and
you have multiple portlets using XForms on the same page. When the parameter is not
present or null , the first form on the HTML page with the class
xforms-form is used.
|
bubbles |
Optional |
Optional boolean indicating if this event bubbles, as defined in DOM2 Events. The default value depends
on the definition of the custom event.
|
cancelable |
Optional |
Optional boolean indicating if this event bubbles, as defined in DOM2 Events. The default value depends
on the definition of the custom event.
|
incremental |
Optional |
When false the event is sent to the XForms server right away. When
true the event is sent after a small delay, giving the opportinuty for other
events that would occur during that timespan to be aggregated with the current event.
|
In most cases, you only need to call dispatchEvent() with a target id and event name,
as in:
ORBEON.xforms.Document.dispatchEvent("my-id", "acme-super-event");
An event handler for the custom event can be in an XForms model or control, and can execute any
valid XForms action, for example:
<xforms:action id="my-id" ev:event="acme-super-event"><xforms:setvalue ref="first-name" value="instance('default-values')/first-name"/><xforms:toggle case="first-name-case"/></xforms:action>
11.4. Other Extensions
11.4.1. XForms Submission
The xforms:submission element supports optional xxforms:username and
xxforms:password attributes that allow specifying HTTP authentication credentials:
<xforms:submission id="save-submission" ref="instance('my-instance')" method="put" action="/exist/rest/ops/my-file.xml" replace="none" xxforms:username="admin" xxforms:password=""/>
11.4.2. xxforms:script Action
The xxforms:script action allows you to call client-side JavaScript as a result of
XForms events:
<xforms:action ev:event="xforms-value-changed"><xforms:setvalue ref=".">test</xforms:setvalue><xxforms:script>var v = 2; myValueChanged(v);</xxforms:script></xforms:action>
Note
xxforms:script actions are currently always executed last in a sequence
of XForms actions, even if they appear before other XForms actions.
11.4.3. Read-Only XForms Instances
Orbeon Forms supports an extension attribute, xxforms:readonly , on
xforms:instance and xforms:submission elements. When set to
true , this attribute signals that once loaded, the instance is read-only, with the
following consequences:
-
The instance is loaded into a smaller, more efficient, read-only data structure in
memory.
-
Instance values cannot be updated, and no Model Item Properties (MIPs) can be
assigned with <xforms:bind> to the instance.
-
When using client-side state handling, less data may be transmitted between server and
client.
Note that a read-only instance can still be replaced in its entirety during an XForms
submission.
Read-only instances are particularly appropriate for loading internationalization resources,
which can be large but don't change. Example:
<xforms:instance id="resources-instance" src="/forms/resources/en" xxforms:readonly="true"/>
11.4.4. Sharing of Read-Only XForms Instances
Orbeon Forms supports an extension attribute, xxforms:shared , on
xforms:instance and xforms:submission elements. This attribute can be
used only when an XForms instance is marked as read-only with
xxforms:readonly="true" . xxforms:shared can take two values:
document (the default if the attribute is not specified) and
application . When application is specified:
-
The instance can be shared at the application level identified just by its source URL.
-
The instance is not stored into the XForms document's state, but in a global cache,
therefore potentially saving memory. If, upon loading an XForms document, the instance
is found in the cache, it is directly retrieved from the cache. This can save time
especially if the URL can take significant time to load.
-
The URL must refer to a constant XML document and authorization credentials such as
username and password should not cause different data to be loaded.
Here is how you use the attribute on <xforms:instance> :
<xforms:instance id="resources-instance" src="/forms/resources/en" xxforms:readonly="true" xxforms:shared="application"/>
When used on xforms:submission , the submission has to use
method="get" method and replace="instance" :
<xforms:submission serialize="false" action="/forms/resources/fr" method="get" replace="instance" instance="resources-instance" xxforms:readonly="true" xxforms:shared="application"/>
You set the size of the shared instances cache using a property in properties.xml :
<property as="xs:integer" name="oxf.xforms.cache.shared-instances.size" value="10"/>
Warning
When using xxforms:shared="application" , be sure that the data contained in the
instance does not contain information that could be inadvertently shared with other XForms
documents. It is recommended to use it to load localized resources or similar types of data.
12. State Handling
12.1. Rationale
The Orbeon Forms XForms engine requires keeping processing state while operating on an XForms page.
Such state includes the current values of XForms instances, selected repeated elements, and more.
With Orbeon Forms, XForms state information can be handled in one of two ways:
-
Client-side: in this case, static initial state information is sent along with the
initial HTML page, and dynamic state is exchanged over the wire between the client browser
and the Orbeon Forms XForms server when necessary.
Benefits of the approach:
-
The Orbeon Forms server is entirely stateless. It only requires memory while
processing a client request. It can be restarted without consequence for the XForms
engine.
-
State information does not expire as long as the user keeps the
application page open in the web browser.
Drawbacks of the approach:
-
Resulting HTML pages are larger. In particular, the size of
state data grows when XForms instances grow, regardless of
whether many XForms controls are bound to instance data.
-
More data circulates between the client browser and the Orbeon Forms XForms server.
Note
Orbeon Forms compresses and encrypts XForms state information sent to the client.
-
Server-side: in this case, state information is stored on the
server, in association with an application session. Only very little
state information circulates between client and server.
Benefits of the approach:
-
Resulting HTML page are smaller. HTML pages increase in size as
more XForms controls are used, but they don't increase in size
proportionally to the size of XForms instances.
-
Small amounts of data circulate between the client browser and the Orbeon Forms
XForms server.
-
This means that very large XForms instances can be processed
without any impact on the amount of data that is transmitted
between the client and the server.
Drawbacks of the approach:
-
The Orbeon Forms XForms server needs to be stateful. It uses server memory to store
state information in a session even when no request is being processed. The server
must be configured to determine how much state information is kept in a session, how
long session take to expire, etc. This creates additional demand for resources on
the server and complicates the task of tuning the server.
-
State information can become unavailable when sessions expire or
when the server is restarted (unless you setup the server to
persist session information). When state information becomes
unavailable for a page, that page will no longer function unless
it is reloaded.
Note
With most servlet containers, it is possible to configure
session handling to passivate sessions out of the application
server memory to a persistent store. It is this way possible to
partially alleviate the drawback above by making sure that a
very large number of active but idle sessions can be kept, with
a minimum impact on application server memory. It is this way
also possible to make sure that sessions survive a servlet
container restart.
Note
Orbeon Forms ensures that it is possible to open multiple client browser windows showing
the same page within the same session.
12.2. Configuring State Handling
State handling can be configured globally for all pages, or locally for each
individual page served. Global configuration is performed in
properties.xml with the oxf.xforms.state-handling
property. When missing or set to client , state is stored
client-side. When set to session , state is stored server-side in a
session. For example:
<property as="xs:string" name="oxf.xforms.state-handling" value="session"/>
The global configuration can be overridden for each page by setting the
xxforms:state-handling attribute in the page. This attribute can be
set for example on the root element of the XHTML page, or on the first
xforms:model element. Only the first such attribute encountered by
the XForms engine is used:
<xforms:model xxforms:state-handling="client">...</xforms:model>
When storing state in a session, the maximum size of the data to be stored for
each user can be selected using the oxf.xforms.cache.session.size
property. The size is specified in bytes:
<property as="xs:integer" name="oxf.xforms.cache.session.size" value="500000"/>
Whether state information is kept client-side or server-side, a property controls whether the XForms
engine should try to optimize state reconstruction by using a cache. This property should usually
be set to true :
<property as="xs:boolean" name="oxf.xforms.cache.document" value="true"/>
If the above property is set to true , the number of XForms documents that can be held
in that document cache at a given time is configured with the following property:
<property as="xs:integer" name="oxf.xforms.cache.documents.size" value="10"/>
Note that this represents XForms documents in a particular state of interaction with a user, which
means that if to users load the same XForms page two entries will be needed in the cache.
13. Minimal Resources
Most JavaScript and CSS files used by the XForms engine are available in two versions:
-
A full version, which may contain comments, spaces, longer identifiers, etc.
-
A minimal version, which is usually much smaller
Both versions work exactly the same. For development and debugging of the XForms engine itself, the full
version is easier to work with. But if you never work directly with these JavaScript and CSS files, as
well as for deployment, the minimal versions are recommended as they will load faster in the user's web
browser. You enable minimal resources in properties.xml as follows:
<property as="xs:boolean" name="oxf.xforms.minimal-resources" value="true"/>
14. Debugging XForms Pages
14.1. Enabling XForms Logging
When a fatal error occurs, the XForms engine throws a Java exception which either results in an error
page in your web browser (when the error occurrs during page initialization) or in an error message at
the top of the displayed XForms page (when the error occurs during an Ajax request after the page is
loaded). The main Java exception is also logged on the server. Often, this provides enough information
to the developer to figure out what went wrong. When this is not sufficient, the best tool available is
the XForms engine logging facility. To enable it, make sure you uncomment the following lines in
config/log4j.xml :
<category name="org.orbeon.oxf.xforms.processor.XFormsServer"><priority value="debug"/></category><category name="org.orbeon.oxf.xforms.processor.XFormsModelSubmission"><priority value="debug"/></category>
Note
You must restart your Servlet container for those changes to be taken into account.
This setting enables verbose logging of the XForms engine's operations, in particular:
-
Dispatching of events.
-
Execution of actions.
-
Loading of instances.
-
Execution of submissions.
-
Resulting XForms instances.
-
XForms cache-related operations.
The following figure shows a sample XForms logging session in Orbeon Studio:

14.2. The Instance Inspector
The Instance Inspector allows you to visualize all the instances of your XForms page. You enable it
by adding the following within your XForms page:
<widget:xforms-instance-inspector xmlns:widget="http://orbeon.org/oxf/xml/widget"/>
This is an example of how the Instance Inspector looks like in your page:

You can select which model and instand to view, and decide whether to see plain XML or formatted
XML.
15. Migrating from XForms Classic to XForms NG
Migrating from XForms Classic to XForms NG consists in telling Orbeon Forms to use XForms NG, in
making the necessary changes to adjust your XForms model and controls (this is necessary as XForms
Classic was lacking in terms of compatibility with the XForms specification, and XForms NG on the
contrary aims at implementing XForms 1.0 and XForms 1.1 fully), and (sometimes optionally) in making
some architectural changes to your application:
-
Configuring Orbeon Forms to use XForms NG.
-
Identify in your page flow the pages that use XForms Classic. Those are defined by
<page> elements with the xforms attribute, for example:
<page id="my-page" path-info="/my/page" xforms="/my-page/xforms-model.xml" view="/my-page/view.xhtml"/>
-
For each page identified in the previous step, locate the XForms model file referred by the
xforms attribute. In most cases, this is a static XML file with a root element
called <xforms:model> , for example:
<xforms:model><xforms:instance>...</xforms:instance>...</xforms:model>
You must now insert the content of that file into your XHTML page view. In most cases, the
page view is a static XHTML file or a dynamic XSLT file that produces XHTML. Locate the
<xhtml:head> element and insert the XForms model as a child of that element:
<xhtml:html><xhtml:head><xhtml:title>My Page</xhtml:title><xforms:model><xforms:instance>...</xforms:instance>...</xforms:model></xhtml:head><xhtml:body>...</xhtml:body></xhtml:html>
Alternatively, you can use XInclude to keep the XForms model external:
<xhtml:html><xhtml:head><xhtml:title>My Page</xhtml:title><xi:include href="oxf:/my-page/xforms-model.xml"/></xhtml:head><xhtml:body>...</xhtml:body></xhtml:html>
-
In the page flow, remove the xforms attribute on the <page>
element:
<page id="my-page" path-info="/my/page" view="/my-page/view.xhtml"/>
What you have achieved at this point is migrating from XForms Classic's external
XForms model specification to the up-to-date way of including XForms directly within XHTML.
Note that this also allows you to use multiple XForms models simply by adding them as
children of the <xhtml:head> element:
<xhtml:html><xhtml:head><xhtml:title>My Page</xhtml:title><xforms:model id="main-model">...</xforms:model><xforms:model id="resources-model">...</xforms:model></xhtml:head><xhtml:body>...</xhtml:body></xhtml:html>
-
Updating XForms model and controls.
You are very likely to have to make further adjustments to your XForms controls and model. The
following are possible things to look at:
-
The <xforms:submit> control requires a submission
attribute referring to an existing <xforms:submission> element
within an XForms model. Start creating an <xforms:submission>
element, assign it an id, and then set the submission attribute on
<xforms:submit> . For example:
<xforms:submission id="default-submission" method="post" action="/services/save" replace="none"/>...<xforms:submit submission="default-submission"><xforms:label>Save</xforms:label></xforms:submit>
-
The <xxforms:if> and <xxforms:choose> extensions no
longer work with XForms NG. Use <xforms:switch> or
<xforms:group> with relevance instead. Note that you can often
convert simply from:
<xxforms:if test="/form/first-name = 'Joe'">...</xxforms:if>
to:
<xforms:group ref=".[/form/first-name = 'Joe']">...</xforms:group>
-
With XForms Classic, activacting a trigger would make the unique XForms instance of the
unique XForms model available to Page Flow Controller processing (i.e. a PFC action,
model and view could be activated). With NG, this is no longer the case and processing
follows the XForms specification. This means in particular that if a submission fails
because the submitted instance is invalid, that instance will never be sent by the
XForms engine and will not, in particular, reach a page or service declared in the page
flow (unless the XForms 1.1 validate="false" attribute on
<xforms:submission> is set).
Similarly, using triggers to perform insertions or deletions into XForms instances does
not cause a submission to happen with XForms NG.
-
With XForms Classic, a submission would annotate an XForms instance with attributes
such as xxforms:valid="true" , etc. This is no longer the case with XForms
NG.
-
Architectural considerations.
-
Much of the work that was performed with page flow actions with XForms Classic can be
implemented with XForms events and XForms actions. This means that you will tend to
migrate functionality away from the PFC and towards XForms. This also means that you
will use less XSLT to produce your pages, or even none at all, which is ideal as that is
one less technology tha developers have to learn.
-
Because of the power of the <xforms:submission> element (which, with
XForms 1.1, allows you to call any REST service), you are likely to move towards a
service-oriented approach where your XForms page uses submissions that communicate with
services. Such services may be external, or they may be implemented in Orbeon Forms and
mapped in your page flow.
|