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:input
- 8.3. xforms:output
- 8.4. Default Formatting
- 9. Iteration of XForms Actions over Sequences
- 10. Generalized context attribute
- 11. Enhanced event() Function Support
- 12. Enhanced <xforms:dispatch> Support
- 13. Enhanced Support for xforms-select and xforms-deselect
- 14. Targetting effective controls within repeat iterations
- 15. Validation Extensions
- 15.1. Extension Events
- 15.2. Extension Types
- 15.3. Controlling the XML Schema Validation Mode
- 16. JavaScript Integration
- 17. Attribute Value Templates
- 17.1. AVTs on XForms Elements
- 17.2. AVTs on XHTML Elements
- 18. Variables
- 19. Dialogs
- 20. Submission Extensions
- 20.1. HTTP Authentication
- 20.2. HTTP Headers Forwarding
- 20.3. Loading Indicator
- 20.4. Target
- 20.5. xxforms:instance Attribute
- 20.6. xxforms:xinclude Attribute
- 20.7. Submitting Binary Content
- 21. Other Extensions
- 21.1. <xxforms:script> Action
- 21.2. Read-Only XForms Instances with xxforms:readonly
- 21.3. Sharing of Read-Only XForms Instances with xxforms:shared
- 21.4. Controlling Item Sets Refreshes with xxforms:refresh-items
- 21.5. xxforms:internal Appearance on <xforms:group>
- 21.6. Trees with the xxforms:tree Appearance
- 21.7. Menus with the xxforms:menu Appearance
- 21.8. Autocomplete box xxforms:tree Appearance
- 21.9. Multiple Event Names, Observers and Targets on Event Handlers
- 21.10. Modal Trigger / Submit Behavior
- 21.11. xxforms:download Appearance on <xforms:output>
- 21.12. 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
Orbeon Forms uses XPath 2.0 expressions instead of XPath 1.0 expressions as mandated by XForms. This allows much greater flexibility in the expressions you can use in Orbeon Forms (and once you have tasted XPath 2.0, you can't go back to XPath 1.0!).
In general, this does not cause incompatibilities: most XPath 1.0 expressions work without issues
with an XPath 2.0 implementation. But one place where there is an incompatibility is the use of the
XPath 1.0 if()
function. This function clashes with XPath 2.0's built-in
if()
construct. The bottom line is that you cannot directly use the XForms
if()
function in Orbeon Forms at the moment. The following, for example, will not work
in Orbeon Forms:
But you have workarounds:
-
Use the XPath 2.0
if (...) then ... else ...
construct instead:if (normalize-space(/first-name) = '') then '' else concat('Hello, ', /first-name, '!') -
Use the Orbeon Forms
xxforms:if()
extension, which behaves like the XFormsif()
function:xxforms:if (normalize-space(/first-name) = '', '', concat('Hello, ', /first-name, '!'))
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: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:
This only controls the appearance of the date as shown to the user. It does not control the format of the date captured in the XML document, or determines the format into which the user can type the date.
8.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.
8.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:
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
Orbeon Forms enhances the XML Events event()
function to take a qualified name as
parameter:
This allows namespacing attribute names, therefore better allowing for extension attributes.
The following standard event attributes are implemented:
[TODO: describe standard Orbeon Forms support for event() function]
On all events, the following extension attributes are supported:
-
event('xxforms:type') as xs:string
Return the event type (also known as event name), for example
"DOMActivate"
. -
event('xxforms:target') as xs:string
Return the static id of the event target.
-
event('xxforms:bubbles') as xs:boolean
Return whether the event is allowed to bubble or not.
-
event('xxforms:cancelable') as xs:boolean
Return whether the event is cancelable or not.
On all UI events (DOMActivate
, DOMFocusIn
, DOMFocusOut
,
xforms-select
, xforms-deselect
, xforms-enabled
,
xforms-disabled
, xforms-help
, xforms-hint
,
xforms-valid
, xforms-invalid
, xforms-required
,
xforms-optional
, xforms-readonly
, xforms-readwrite
,
xforms-value-change
), the following extension attributes are supported:
-
event('xxforms:binding') as node()?
Return the event target's single-node binding if any.
-
event('xxforms:label') as xs:string?
Return the event target's label value if any.
-
event('xxforms:hint') as xs:string?
Return the event target's hint value if any.
-
event('xxforms:help') as xs:string?
Return the event target's help value if any.
-
event('xxforms:alert') as xs:string?
Return the event target's alert value if any.
-
event('xxforms:repeat-indexes') as xs:string*
Return the event target's current repeat indexes, if any, starting from the ancestor repeat.
-
event('xxforms:target-prefixes') as xs:string*
Return the event target's id prefixes, if any, starting from the ancestor components. This will be empty unless the target is within an XBL component.
On xforms-select
, the following extension attributes are supported:
-
event('xxforms:item-value')
When this event is dispatched to in response to a selection control item being selected, returns the value of the selected item.
On xforms-submit-serialize
, the following extension attributes are supported:
-
event('xxforms:binding') as node()?
Return the submission's single-node binding if any.
-
event('xxforms:serialization') as xs:string
Return the submission's requested serialization, e.g.
application/xml
,application/x-www-form-urlencoded
, etc..
12. Enhanced <xforms:dispatch> Support
Orbeon Forms supports passing event context attributes with the <xxforms:context>
child element. The actions supported are actions which directly cause an event to be dispatched:
-
<xforms:dispatch>
-
<xforms:send>
-
<xxforms:show>
-
<xxforms:hide>
Here is how you pass context attributes when executing an action:
<xxforms:context>
supports the following two attributes:
name |
Mandatory | Name of the context attribute. In order to avoid confusion with standard XForms names, we recommend you use qualified names. |
---|---|---|
select |
Mandatory | XPath 2.0 expression determining the value of the context attribute. |
Context attribute passed this way can be retrieved using the event()
function:
At the moment, with, <xforms:dispatch>
, only custom events support passing
context attributes this way. Built-in events, such as xforms-value-changed
, or
DOMActivate
, ignore nested <xxforms:context>
elements.
13. Enhanced Support for xforms-select and xforms-deselect
[TODO: describe support for these events on xforms:upload]
14. Targetting effective controls within repeat iterations
The following actions all support attributes resolving to a particular control:
-
<xforms:dispatch>
(target
attribute) -
<xforms:setfocus>
(control
attribute) -
<xforms:toggle>
(case
attribute) -
<xxforms:show>
(neighbor
attribute)
When that control is within a repeat iteration, the actual control targetted is chosen based on the
current set of repeat indexes. However, in some cases, it is useful to be able to target the control
within a particular iteration. This is achieved with the xxforms:repeat-indexes
extension attribute on these actions. This attribute takes a space-separated list of repeat
indexes, starting with the outermost repeat. Example:
15. Validation Extensions
15.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:
15.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.
15.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.
16. JavaScript Integration
17. Attribute Value Templates
Certain attributes in XForms are literal values defined by the form author at the time the form is
written, as opposed to being evaluated at runtime. Examples include the action
attribute on <xforms:submission>
, or the resource
attribute on
<xforms:load>
.
To improve this, Orbeon Form supports a notation called Attribute Value Templates (AVTs),
borrowed from XSLT, which allows including XPath
expressions within attributes. You include XPath expressions in attributes by enclosing them within
curly brackets ({
and }
).
17.1. AVTs on XForms Elements
Consider this example:
When <xforms:load>
is executed, the resource
attribute is
evaluated. The results is the concatenation of /forms/detail/
and of the result of
the expression within brackets:
If the id
element pointed to contains the string
C728595E0E43A8BF50D8DED9F196A582
, the resource
attribute takes the
value:
Note the following:
-
If you need curly brackets as literal values instead of enclosing an XPath expression, escape them using double brackets (
{{
and}}
). -
You can use as many XPath expressions as you want within a single attributes, each of them enclosed by curly brackets.
AVTs are currently supported on the following attributes:
-
<xforms:submission>
attributes:-
method
-
action
andresource
-
serialization
-
mediatype
-
version
-
encoding
-
separator
-
indent
-
omit-xml-declaration
-
standalone
-
validate
-
relevant
-
mode
-
xxforms:target
-
xxforms:username
-
xxforms:password
-
xxforms:readonly
-
xxforms:shared
-
xxforms:xinclude
-
-
<xforms:dispatch>
attributes:-
name
-
target
-
bubbles
-
cancelable
-
delay
-
xxforms:show-progress
-
xxforms:progress-message
-
-
<xforms:load>
attributes:-
resource
-
replace
-
xxforms:target
-
xxforms:show-progress
-
f:url-type
-
-
<xforms:setfocus>
:control
attribute. -
<xforms:toggle>
:case
attribute. -
<xxforms:show>
attributes:-
dialog
-
neighbor
-
constrain
-
-
<xxforms:hide>
:dialog
attribute. -
All controls:
-
style
: equivalent to the HTMLstyle
attribute
-
-
<xxforms:input>
attributes:-
xxforms:size
: equivalent to the HTMLsize
attribute -
xxforms:maxlength
: equivalent to the HTMLmaxlength
attribute -
xxforms:autocomplete
: equivalent to the HTMLautocomplete
attribute
-
-
<xxforms:textarea>
attributes:-
xxforms:cols
: equivalent to the HTMLcols
attribute -
xxforms:rows
: equivalent to the HTMLrows
attribute -
xxforms:maxlength
: equivalent to the HTML 5rows
attribute (NOTE: this HTML 5 attribute is not supported by most browsers as of March 2009)
-
There are plans to support AVTs in more places in the future. Please send your suggestions!
17.2. AVTs on XHTML Elements
AVTs are also supported on XHTML elements. You must first enable this feature in
properties.xml
:
For example:
In the above example, the value of the class
attribute on
<xhtml:tr>
is determined dynamically through XPath and XForms. Even table rows
get the class zebra-row-even
and odd table rows get the class
zebra-row-odd
.
The values of XHTML attributes built using AVTs update as you interact with the XForms page. In
the example above, inserting or deleting table rows after the page is loaded will still
correctly update the class
attribute.
It is also possible to use AVTs outside <xhtml:body>
, for example:
AVTs are also usable on HTML elements within <xforms:label>
,
<xforms:hint>
, <xforms:help>
, <xforms:alert>
:
It is not possible to use AVTs within the id
attribute of XHTML elements.
18. Variables
Orbeon Forms supports declaring variables which look and behave very much like XSLT variables.
Variables are extremely useful, for example to avoid repeating long XPath expressions, or to give an
XPath expression unambiguous access to data computed in enclosing <xforms:group>
or
<xforms:repeat>
elements.
You define variables with the extension element <xxforms:variable>
. You can also use
<exforms:variable>
in the eXforms namespace. Either element supports the
following attributes:
name |
Mandatory | Name of the variable. |
---|---|---|
model |
Optional |
Id of the model used for the evaluation of the select attribute. This works like
the standard XForms model attribute.
|
context |
Optional |
Overridden evaluation context for the evaluation of the select attribute. If a
model attribute is present, the model is resolved first, and then
context is evaluated. This works like the standard XForms context
attribute.
|
select |
Optional |
XPath 2.0 expression determining the value of the variable. If the attribute is omitted, the
text content of the <xxforms:variable> or <exforms:variable>
element is used as the value.
|
Once a variable is declared, you can use it from XPath expressions for which the variable is visible:
Under the <xhtml:body>
element, the following rules apply:
-
You can declare XPath variables anywhere an XForms control can be declared, as well as within
<xforms:action>
. -
A variable is visible to any XPath expression on a following sibling element or on a following sibling element's descendant element.
In addition, variables are supported within <xforms:model>
, as well as within
<xforms:action>
in a model. Under the <xforms:model>
element, the
following rules apply:
-
Variables have to be declared as direct children of an
<xforms:model>
element. -
Variables defined within a given model are also visible from XPath expression under the
<xhtml:body>
element whenever that model is in scope:
Currently you cannot declare variables in these locations:
-
Within XForms core controls such as
<xforms:input>
, including within nested items or itemsets (except within<xforms:action>
elements, where they are allowed). -
Within nested model elements, including
<xforms:bind>
or<xforms:submission>
(except within<xforms:action>
elements, where they are allowed).
19. Dialogs
19.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.
|
19.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. |
---|
19.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:
19.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.
20. Submission Extensions
20.1. HTTP Authentication
The <xforms:submission>
element supports optional xxforms:username
and
xxforms:password
attributes that allow specifying HTTP authentication credentials.
You can specify either both attributes, or only the xxforms:username
attribute. The
latter case is equivalent to setting the value of xxforms:password
to an empty
string.
20.2. HTTP Headers Forwarding
The <xforms:submission>
automatically forwards current HTTP headers specified by the
oxf.xforms.forward-submission-headers
property. This property contains a
space-separated list of header names to forward:
It can also be set on a per-page basis on your first model element:
Whenever <xforms:submission>
performs an HTTP request, it looks at this list of
header names and it forwards the header value if the following conditions are met:
- There is an incoming header with that name, i.e. either the HTTP request causing the XForms page to load or the XForms Ajax request to run contains that header.
-
There is no author-specifed header with the same name in an
<xforms:header>
element within<xforms:submission>
.
Forwarding the Authorization
or other authentication-related headers can be useful
to propagate authentication credentials to other services.
The Authorization
is treated specially: if a username is specified on the
submission with xxforms:username
, then this header is never forward.
Forwarding authentication-related headers may cause a security risks when communicated with non-trusted servers. Use carefully!
20.3. Loading Indicator
When an <xforms:submission>
with replace="all"
is executed, in general,
the browser will load another page. While this happens, the loading indicator, by default shown
in red at the top right of the window, is displayed. However, when the browser is served not a
web page but say a ZIP file, the browser might ask you in you want to download it, and then stay
in the current page. When this happens, the loading indicator does not go away.
In those cases where you know that the target page does not replace the current page, you can
prevent the loading indicator from being displayed by adding the
xxforms:show-progress="false"
attribute:
Similarly the xxforms:show-progress="false"
attribute can be used with the
xforms:load
action:
20.4. Target
You can use the xxforms:target
attribute on both <xforms:submission>
and
xforms:load
. It behaves just like the HTML target attribute.
When used on <xforms:submission>
, it makes sense to use this attribute only when you
have a replace="all"
, as the replace="instance"
doesn't load another
page.
20.5. xxforms:instance Attribute
On an <xforms:submission>
element with replace="instance"
, the
optional instance
attribute specifies a destination instance for the result. That
attribute is processed like the instance()
function, which means that the instance
specified must be in the current model.
The xxforms:instance
extension attribute can be use instead of the standard
instance
attribute. It works like instance
, except that the instance
is searched globally among all models. xxforms:instance
is to the
instance
attribute what the xxforms:instance()
function is to the standard
instance()
function.
20.6. xxforms:xinclude Attribute
On an <xforms:submission>
element with replace="instance"
, the
optional xxforms:xinclude
attribute specifies whether XInclude processing should be
performed on the XML document returned, before storing it into the destination instance. The
default is false
.
20.7. Submitting Binary Content
XForms 1.1 does not explicitly support submitting binary content, but does not prohibit it
either. Orbeon Forms supports sending the content of a binary resource specified by a URI. Such
resources are easily obtained with <xforms:upload>
, for example. To perform a
binary submission:
-
The
post
orput
method is required. -
You must use a binary
serialization
attribute. This includes all mediatypes which are not XML or text, includingapplication/octet-stream
,image/*
, etc. -
The node referred to by the submission must be of type
xs:anyURI
.
Alternatively, you can set the type information using the xsi:type
attribute:
21. Other Extensions
21.1. <xxforms:script> Action
The <xxforms:script>
action allows you to call client-side JavaScript as a
result of XForms events:
Scripts run with <xxforms:script>
have access to the following JavaScript
variables:
-
this. The element observing the event causing
<xxforms:script>
to run. -
event. Object containing a "target" propeterty.
event.target
returns the element which is the target of the event causing<xxforms:script>
to run.
<xxforms:script>
actions are currently always executed last in a
sequence of XForms actions, even if they appear before other XForms actions.
21.2. Read-Only XForms Instances with xxforms:readonly
Orbeon Forms supports an extension attribute, xxforms:readonly
, on the
<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. But a read-only instance can be replaced entirely by an<xforms:submission replace="instance">
-
When using client-side state handling, less data may be transmitted between server and client.
Read-only instances are particularly appropriate for loading internationalization resources, which can be large but don't change. Example:
The xxforms:readonly
attribute on <xforms:instance>
determines if
the instance is read-only until that instance is being replaced. After an instance is replaced,
it can be read-only or not irrelevant of the of xxforms:readonly
on
<xforms:instance>
. When the instance is replaced, the replaced instance is
read-only if and only if the <xforms:submission>
that does the replacement has a
attribute xxforms:readonly="true"
.
21.3. Sharing of Read-Only XForms Instances with xxforms:shared
Orbeon Forms supports an extension attribute, xxforms:shared
, on the
<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>
:
When used on <xforms:submission>
, the submission has to use
method="get"
method and replace="instance"
:
You set the size of the shared instances cache using a property in properties.xml
:
You can force the XForms engine to remove a shared instance from the cache by dispatching the
xxforms-instance-invalidate
event to it. The next time an XForms document requires
this instance, it will not be found in the cache and therefore reloaded. Example:
The xxforms:invalidate-instance
action allows invalidating a shared instance by
resource URI, for example:
This action also supports the xinclude
attribute, which if present will only invalidate
the instance with the given resource if it was loaded with a matching xxforms:xinclude
attribute:
If the xinclude
attribute is not specified, any shared instance matching the resource
URI is invalidated.
It is also possible to remove all shared instances from the cache by using the
xxforms:invalidate-instances
action, for example:
When using xxforms:readonly="true"
, another attribute, xxforms:ttl
,
can be used to set a time to live for the instance in cache. This duration is expressed
in milliseconds and has to be greater than zero. When a shared instance if found in cache but
has an associated time to live, if it was put in the cache more than time to live milliseconds
in the past, then the instance is discarded from the cache and retrieved again by URI as if it
had not been found in cache at all. The following example expires the shared instance after one
hour:
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.
21.4. Controlling Item Sets Refreshes with xxforms:refresh-items
XForms specifies that items and itemsets are re-evaluated when processing
xforms-refresh
. This may happen quite often, and may lead to time-consuming
re-evaluations especially when there are many or large itemsets.
Orbeon Forms supports an extension attribute, xxforms:refresh-items
, on the
<xforms:select>
and <xforms:select1>
elements. When set to
true
(the default), items and itemsets are re-computed upon
xforms-refresh
event processing. When set to false
, this attribute
signals that once computed, the set of items for the control will not be recomputed upon
xforms-refresh
event processing.
If you know that itemsets do not change over time, setting xxforms:refresh-items
to
false
disables refreshing of the items during xforms-refresh
and may
yield significant performance improvements. For example:
21.5. xxforms:internal Appearance on <xforms:group>
<xforms:group>
supports the xxforms:internal
appearance, which
causes the group to have no representation at all on the client:
In general you won't have a need for this appearance, but it is useful as an optimization, as it leads to less HTML sent to the client. You may use it when a group is used only to change the in-scope evaluation context for nested controls and when you don't need changes to relevance which apply directly to the group to be reflected in the client.
21.6. Trees with the xxforms:tree Appearance
[TODO: describe the Orbeon Forms xxforms:tree
appearance on
xforms:select
and xforms:select1
]
21.7. Menus with the xxforms:menu Appearance
[TODO: describe the Orbeon Forms xxforms:tree
appearance on
xforms:select1
]
21.8. Autocomplete box xxforms:tree Appearance
[TODO: describe the Orbeon Forms xxforms:autocomplete
appearance on
xforms:select
and xforms:select1
]
21.9. Multiple Event Names, Observers and Targets on Event Handlers
The ev:event
, ev:observer
and ev:target
attributes,
defined by the XML Events specification, only
support one event name, observer, or target respectively. Orbeon Forms supports as an extension
a list of space-separated values. The behavior is as follows:
-
For
ev:event
: the handler is called if any of the specified events matches.<xforms:action ev:event="DOMFocusIn DOMFocusOut"><!-- Reacting to either the "DOMFocusIn" and "DOMFocusOut" events -->...</xforms:action> -
For
ev:observer
: the event handler is attached to all the observers specified.<xforms:action ev:event="DOMActivate" ev:observer="my-input my-trigger"><!-- Observing both the "my-input" and "my-trigger" controls -->...</xforms:action> -
For
ev:target
: the handler is called if any of the specified targets matches.<xforms:action ev:event="xforms-submit-done" ev:target="create-submission update-submission"><!-- Checking that either the "create-submission" and "update-submission" controls is a target -->...</xforms:action>
The extensions above have been requested for inclusion in XML Events 2.
In addition, the special #all
event name can be used to catch all events:
21.10. Modal Trigger / Submit Behavior
Usually, activating a trigger or submit button on the client doesn't prevent further actions in the user interface. Sometimes however it is useful to block such actions until further processing is complete, for example calling a submission that saves a document.
You can obtain this behavior by using the xxforms:modal="true"
attribute on
<xforms:trigger>
and <xforms:submit>
:
With this attribute set to true
, user input is blocked until all the events
triggered by DOMActivate
are processed. In the meanwhile, the page is grayed out
and an icon appears indicating that background processing is taking place.
21.11. 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
.
21.12. 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: