Even though AVTs and <xforms:output>
elements may be placed before any XForms
model, they are still considered part of the XForms "view" of the XForms document and refer to data placed in
models.
XForms Reference: XForms Extensions
- 1. Introduction
- 2. XPath 2.0 Expressions
- 3. Placement of Controls and Models
- 4. Custom Model Item Properties
- 5. Extension Model Item Property to Specify default instance values
- 6. Standalone Label, Hint, Help and Alert Elements
- 7. Read-Only Mode
- 8. Formatting
- 8.1. Rationale
- 8.2. xforms:output
- 8.3. Default Formatting
- 9. Iteration of XForms Actions over Sequences
- 10. Generalized context attribute
- 11. Enhanced event() Function Support
- 12. Enhanced <xforms:dispatch> Support
- 13. Targeting effective controls within repeat iterations
- 14. Validation Extensions
- 14.1. Extension Events
- 14.2. Extension Types
- 14.3. Controlling the XML Schema Validation Mode
- 15. JavaScript Integration
- 16. Attribute Value Templates
- 17. Variables
- 18. Dialogs
- 19. Submission Extensions
- 20. Other Extensions
- 20.1. Trees with the xxforms:tree Appearance
- 20.2. Menus with the xxforms:menu Appearance
- 20.3. Autocomplete box xxforms:tree Appearance
- 20.4. Multiple Event Names, Observers and Targets on Event Handlers
- 20.5. xxforms:download Appearance on <xforms:output>
- 20.6. xxforms:group Attribute on <xforms:select1> with appearance="full"
1. Introduction
This part of the XForms reference documentation focuses on XForms extensions provided by Orbeon Forms.
2. XPath 2.0 Expressions
This section has migrated to the wiki.
3. Placement of Controls and Models
XForms does not specify normatively where XForms controls and models must be placed within an HTML
document. The convention is to place
<xforms:model>
elements within <xhtml:head>
, and controls within
<xhtml:body>
. Orbeon Forms is more flexible on this:
-
<xforms:model>
can be placed within<xhtml:head>
as is usual, but also under<xhtml:body>
and even nested within other XForms elements. For example:<xxforms:dialog id="my-dialog" model="my-dialog-model"><xforms:label>My Dialog</xforms:label><xforms:group>...</xforms:group><xforms:model id="my-dialog-model"><!-- Model used by the dialog -->...</xforms:model></xxforms:dialog>In this particular case, this allows you to write your dialog as a module in a completely separate file and to XInclude that file within your main form.
At the moment, nested models behave exactly as if they were placed under
<xhtml:head>
. It is just a syntactic convenience to be able to place them within elements such as<xxforms:dialog>
. -
Attribute Value Templates (AVTs) can be placed on HTML elements outside
<xhtml:body>
.<xhtml:body lang="{instance('language')}">...</xhtml:body> -
A single
<xforms:output>
control may be placed within<xhtml:title>
. This allows dynamically changing the HTML document title using XForms.<xhtml:title><xforms:output value="instance('resources')/title"/></xhtml:title>
4. Custom Model Item Properties
You can place user-defined Model Item Properties (MIP) on the <xforms:bind>
element. Any
attribute not in a standard Orbeon namespace is interpreted as a custom MIP:
The value of the attribute must be a valid XPath expression. The expression result is converted to a string to set the MIP value.
Custom MIPs have the side effect of placing CSS classes on controls bound to affected nodes. Class names are computed as the concatenation of:
- MIP attribute prefix
- "-"
- MIP attribute local name
- "-"
- MIP value
With the example above, the following class names can be set: foo-bar-is-g
or
foo-bar-is-not-g
.
5. Extension Model Item Property to Specify default instance values
In XForms, default or initial values can be set by pre-populating an instance document's elements and attributes with initial data, for example:
For dynamic values, for example coming from request parameters or session values, there is no
declarative notation and you must use xforms-submit-done
or
xforms-submit-ready
, which is sometimes cumbersome:
For convenience, Orbeon Forms support an extension model item property:
xxforms:default
. It works like the standard calculate
, except that it is
evaluated only once, just before the first evaluation of the calculate
expressions if
any.
6. Standalone Label, Hint, Help and Alert Elements
In XForms, <label>
, <hint>
, <help>
and
<alert>
("LHHA") elements must always be nested within a control. In HTML on the
other hand, the <label>
element supports a for
attribute which relates
the element to a control. Orbeon Forms follows HTML and support the for
attribute on
all the LHHA elements. This allows placing LHHA elements in other locations on the page:
Standalone LHHA elements must not cross <xforms:repeat>
boundaries.
7. Read-Only Mode
7.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):
7.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:
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.
8. Formatting
8.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:
-
format-date()
(external documentation) -
format-dateTime()
(external documentation) -
format-time()
(external documentation) -
format-number()
(external documentation)
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?)
.
8.2. 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.
8.3. 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:
They produce results as follows:
-
2004-01-07
asxs:date
is displayed asWednesday January 7, 2004
-
2004-01-07T04:38:35.123
asxs:dateTime
is displayed asWednesday January 7, 2004 04:38:35 UTC
-
04:38:35.123
asxs:time
is displayed as04:38:35 UTC
-
123456.789
asxs:decimal
is displayed as123,456.79
-
123456.789
asxs:integer
is displayed as123,456
-
123456.789
asxs:float
orxs:double
is displayed as123,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].
9. Iteration of XForms Actions over Sequences
Orbeon Forms supports the exforms:iterate
attribute, also available as
xxforms:iterate
attribute, on XForms action elements. Consider the following
instances:
The following action iterates over the <title>
elements of
source-instance
. For each of those, a new <book>
element, copied from
the template stored in template-instance
, is inserted into main-instance
.
Then values from the <title>
and <author>
elements are copied over
to the new structure. The XForms 1.1 context()
function provides access to each of the
iterated nodes:
The resulting main-instance
is as follows:
Note that because Orbeon Forms uses XPath 2.0, xxforms:iterate
is not limited to
returning node-sets, but can return sequences of items such as strings.
For more information about eXforms extensions, please visit the eXforms site.
10. Generalized context attribute
XForms 1.1 introduces the context
attribute on <xforms:insert>
and
<xforms:delete>
. Orbeon Forms supports this convenient attribute on all XForms
elements changing the XPath evaluation context, including controls, actions, binds, and
submissions.
The context
attribute overrides the in-scope XPath evaluation context for an action. It
applies before the ref
and context
attributes, but after the
model
attribute.
One convenient use is to just change the context within a group:
Note that it is also possible to use ref
in this case, but doing so has the side effect
of binding the group to an instance data node, which may affect group relevance, for example.
11. Enhanced event() Function Support
This section has migrated to the wiki.
12. Enhanced <xforms:dispatch> Support
This section has migrated to the wiki.
13. Targeting effective controls within repeat iterations
This section has migrated to the wiki.
14. Validation Extensions
14.1. Extension Events
Orbeon Forms supports extensions events dispatched to an instance when it becomes valid or
invalid: xxforms-valid
and xxforms-invalid
. These events are
dispatched just before xforms-revalidate
completes, to all instances of the model
being revalidated. For a given instance, either xxforms-valid
or
xxforms-invalid
is dispatched for a given revalidation.
These events can be used, for example, to toggle the appearance of icons indicating that a form is valid or invalid:
14.2. Extension Types
Orbeon Forms supports the built-in xxforms:xml
extension type. This types checks
that the value is well-formed XML:
Note that this checks the string value of the node, which means that the node must contain escaped XML.
Orbeon Forms supports the built-in xxforms:xpath2
extension type. This types
checks that the value is well-formed XPath 2.0. Any variable used by the expression is assumed
to be in scope:
In both these cases, Orbeon Forms checks for the required
MIP: if it evaluates
to false()
and the value is the empty string, then the instance data node is
considered valid. This is contrary to XForms 1.1 as of August 2008.
14.3. Controlling the XML Schema Validation Mode
When an XML Schema is provided, Orbeon Forms supports controlling whether a particular instance is validated in "lax" mode, "strict" mode, or not validated at all.
Orbeon Forms implements a "lax" validation mode by default, where only elements that have definitions in the imported schemas are validated. Other elements are not considered for validation. This is in line with XML Schema and XSLT 2.0 lax validation modes, and with the default validation mode as specified in XForms 1.1
In addition, the author can specify the validation mode directly on each instance with the
extension xxforms:validation
attribute, which takes values lax
(the default), strict
(the root element has to have a definition in the schema
and must be valid), or skip
(no validation at all for that instance).
Nodes validated through a schema receive datatype annotations, which means that if an element
or attribute is validated against xs:date
in a schema, an XForms control bound to
that node will display a date picker.
15. JavaScript Integration
This section has migrated to the wiki.
16. Attribute Value Templates
This section has migrated to the wiki.
17. Variables
This section has migrated to the wiki.
18. Dialogs
18.1. The xxforms:dialog Control
You declare dialogs directly under the <xhtml:body>
element with:
-
When you have
appearance="full"
on the dialog, you define the title of the dialog with the embedded<xforms:label>
element. -
Inside an
<xxforms:dialog>
you can use all the XHTML and XForms elements you can normally use elsewhere on the page. You can have other XForms controls, or show anything you would like to with HTML. -
The attributes on the
<xxforms:dialog>
are as follows:
id |
Mandatory |
The ID of the dialog. You reference this ID when opening the dialog with
<xxforms:show dialog="my-dialog-id"> .
|
---|---|---|
appearance |
Optional. Possible values are:
|
You can set the appearance to either full or minimal :
|
level |
Optional. Can only be used appearance is set to full . Possible values are:
|
When set to modal the rest the page is grayed out and you can't interact
with any ontrol on the page outside of the dialog. When set to modeless you
can still use other controls on the page.
|
close |
Optional. Can only be used appearance is set to full . Possible values are:
|
A "x" is shown in the dialog title bar when close is set to
true . If you specify close="false" , then you should provide a
way to close the dialog, for instance by having you own "Close" button inside the
dialog. This is typically useful when you want to force users to enter some data before
proceeding and you don't want them to cancel the current operation by closing the
dialog.
|
draggable |
Optional. Can only be used appearance is set to full . Possible values are:
|
When set to false , you won't be able to move dialog on the page by using
drag and drop in the dialog title bar.
|
visible |
Optional. Whether the dialog is initially visible when the page loads. Possible values
are:
|
When set to true , the dialog appears immediately when the page loads.
|
neighbor |
Optional |
Optional. Use only with minimal appearance. The id of the control next to
which the dialog should display when opening.
|
18.2. The xxforms:show and xxforms:hide Actions
You open a dialog by using the xxforms:show
action:
If the dialog is already open, no action takes place.
xxforms:show
supports the following attributes:
dialog |
Mandatory | The id of an existing dialog to open. |
---|---|---|
neighbor |
Optional |
Optional. Use only with minimal appearance. The id of the control next to
which the dialog should display when opening.
|
constrain |
Optional |
Whether to constrain the dialog to the viewport. Possible values
are:
|
You close a dialog by using the xxforms:hide
action:
If the dialog is already closed, no action takes place.
xxforms:hide
supports the following attributes:
dialog |
Mandatory | The id of an existing dialog to close. |
---|
18.3. The xxforms-dialog-open Event
Dispatched in response to: xxforms:show
action executed with an existing dialog id.
Target: dialog
Bubbles: Yes
Cancelable: Yes
Context Info: none
Default Action: Open the dialog.
You can respond to this event before the dialog opens, for example to perform initialization of data:
18.4. The xxforms-dialog-close Event
Dispatched in response to: xxforms:hide
action executed with an existing dialog id.
Target: dialog
Bubbles: Yes
Cancelable: Yes
Context Info: none
Default Action: Close the dialog.
19. Submission Extensions
This section has migrated to the wiki.
20. Other Extensions
This section has migrated to the wiki.
20.1. Trees with the xxforms:tree Appearance
[TODO: describe the Orbeon Forms xxforms:tree
appearance on
xforms:select
and xforms:select1
]
20.2. Menus with the xxforms:menu Appearance
[TODO: describe the Orbeon Forms xxforms:tree
appearance on
xforms:select1
]
20.3. Autocomplete box xxforms:tree Appearance
[TODO: describe the Orbeon Forms xxforms:autocomplete
appearance on
xforms:select
and xforms:select1
]
20.4. Multiple Event Names, Observers and Targets on Event Handlers
This section has migrated to the wiki.
20.5. xxforms:download Appearance on <xforms:output>
<xforms:output>
supports the xxforms:download
appearance, which
causes the the resource identified by the single-node binding to be downloadable through a
link.
Like <xforms:upload>
, when using this appearance,
<xforms:mediatype>
and <xforms:filename>
children elements are
allowed (but not the <xxforms:size>
element). When serving the file, if these
elements are present, they are passed to the resulting HTTP response to provide mediatype and
file name hints to the browser. Example:
The data type for the resource must be xs:anyURI
or xs:base64Binary
.
20.6. xxforms:group Attribute on <xforms:select1> with appearance="full"
<xforms:select1>
supports an extension attribute called xxforms:group
which allows grouping a series of radio buttons together in a way similar to the name
attribute in HTML.
In general, this attribute is not necessary. It is useful in the following case:
-
Multiple
<xforms:select1 appearance="full">
point to the same node. -
You enable deferred event handling on the client.
The xxforms:group
attribute must contain an identifier unique between groups of radio
controls. Example: