Orbeon Forms User Guide

XForms Reference: Extensions

1. Introduction

This part of the XForms reference documentation focuses on extensions over XForms provided by Orbeon Forms, as well as XForms engine configuration.

Please be sure to visit:

2. 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>
Note

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.

3. XForms 1.1 Support

3.1. Media Type for xforms:output

In XForms 1.0, xforms:output is only used to display text. However, XForms 1.1 supports a mediatype attribute on that element allowing display of other media types.

3.1.1. Image Types

For the <xforms:output> control to display an image, you need to:

  • Have a mediatype attribute on the <xforms:output>. That attribute must refer to an image mediatype, such as image/* or image/jpeg.

  • Use the value attribute on <xforms:output> or bind to the control to a node without type, with an xs:anyURI type or with an xs:base64Binary type.

The resulting value from the instance is interpreted either as a URI pointing to an image, or as a base64-encoded binary representation of the image. The image will display in place of the xforms:output. It is possible to dynamically change the image pointed to. For example:

<xforms:output mediatype="image/*" value="'/images/moon.jpg'"/>
<xforms:model><xforms:instance><image-uri/></xforms:instance><xforms:bind nodeset="image-uri" type="xs:anyURI"/></xforms:model>...<xforms:output mediatype="image/*" ref="image-uri"/>

The image URI may or may no be reachable from the client browser. Orbeon Forms hides this from the developer. For example, to upload and show an image:

<!-- Hide xforms:output when there is no URI available --><xforms:group ref="image[normalize-space() != '']"><!-- Image output --><xforms:output ref="." mediatype="image/*"><xforms:label/></xforms:output></xforms:group><!-- File chooser --><xforms:upload ref="image"><xforms:label/><xforms:filename ref="@filename"/><xforms:mediatype ref="@mediatype"/><xxforms:size ref="@size"/></xforms:upload>

In that example, the upload control stores a temporary URI pointing to a local file: resource. While this URI is not visible from the client web browser, the output control automatically proxies it so that the end user can see the image.

3.1.2. HTML Type

When an xforms:output control has a mediatype attribute with value text/html, the value of the node to which the control is bound is interpreted as HTML content. Consider the following XForms instance:

<xforms:instance id="my-instance"><form><html-content>This is in &lt;b&gt;bold&lt;/b&gt;!</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>.

3.2. origin Attribute on xforms:insert Action

Orbeon Forms supports the XForms 1.1 origin attribute on the xforms:insert action. This attribute allows specifying the source node to use as template. This allows storing templates separately from the node-set specified by the nodeset attribute. For example:

<xforms:insert nodeset="address" at="last()" position="after" origin="instance('template-instance')"/>

The template copied in this case comes from an XForms instance:

<xforms:instance id="template-instance"><address><street><number/><name-1/><name-2/></street><apt/><city/><state/><zip/></address></xforms:instance>

3.3. context Attribute on xforms:insert Action

Orbeon Forms supports the XForms 1.1 context attribute on the xforms:insert action. This attribute allows specifying a context for insertion, which along with the origin attribute allows inserting content into elements:

<xforms:insert context="instance('main-instance')/books" nodeset="book" origin="instance('book-instance')"/>

With original instances as follows:

<xforms:instance id="main-instance"><instance><books/></instance></xforms:instance><xforms:instance id="book-instance"><book><title>Cosmos</title><author>Carl Sagan</author></book></xforms:instance>

The result of a first insertion is:

<xforms:instance id="main-instance"><instance><books><book><title>Cosmos</title><author>Carl Sagan</author></book></books></instance></xforms:instance>

3.4. validate and relevant Attributes on <xforms:submission>

Orbeon Forms supports the XForms 1.1 validate and relevant attributes on <xforms:submission>. These boolean attributes disable processing of validation and relevance respectively for a given submission:

<xforms:submission id="my-submission" method="post" validate="false" relevant="false" resource="http://example.org/rest/draft/" replace="none"/>

For more information, please visit the XForms 1.1 specification.

3.5. serialization Attribute on <xforms:submission>

Orbeon Forms supports the XForms 1.1 serialization on <xforms:submission>. This is particularly useful to specify the value none with a get method:

<xforms:submission id="my-submission" method="get" serialization="none" resource="http://example.org/document.xml" replace="instance" instance="my-instance"/>

For more information, please visit the XForms 1.1 specification.

3.6. Preliminary support for asynchronous handling of <xforms:submission>

Orbeon Forms partially supports the XForms 1.1 mode="asynchronous" attribute on <xforms:submission>. The limitations are:

  • Asynchronous submissions in an Ajax request are delayed until after everything else in the request has run (including other submissions).

  • Asynchronous submissions are "fire and forget": they only work with replace="none" and no xforms-submit-done / xforms-submit-error events are dispatched.

  • All asynchronous submissions started during a given Ajax request run serially.

<xforms:submission id="test-submission" mode="asynchronous" ref="." method="put" resource="http://my.service.com/" replace="none"/>

For more information, please visit the XForms 1.1 specification.

Note

XForms 1.1 specifies that mode="asynchronous" should be the default, but due to the client-server nature of the Orbeon Forms XForms engine, Orbeon Forms still defaults to mode="synchronous".

3.7. Conditional Execution and Iteration of XForms Actions

Orbeon Forms supports the XForms 1.1 if and while attributes on XForms action elements. For more information, please visit the XForms 1.1 specification.

3.8. XForms 1.1 Functions

[TODO: List all XForms 1.1 functions implemented]

4. Extensions

4.1. Read-Only Mode

4.1.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()"/>

4.1.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.

4.2. Formatting

4.2.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?).

4.2.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', (), ())"/>
Note

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.

4.2.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')"/>

4.2.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].

4.3. 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:

<xforms:instance id="main-instance"><instance/></xforms:instance><xforms:instance id="template-instance"><book><title/><author/></book></xforms:instance><xforms:instance id="source-instance"><instance><title>Don Quixote de la Mancha</title><author>Miguel de Cervantes Saavedra</author><title>Jacques le fataliste et son ma??tre</title><author>Denis Diderot</author><title>Childhood's End</title><author>Arthur C. Clarke</author></instance></xforms:instance>

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:

<xforms:action ev:event="xforms-ready" xxforms:iterate="instance('source-instance')/title"><xforms:insert context="instance('main-instance')" nodeset="book" origin="instance('template-instance')"/><xforms:setvalue ref="instance('main-instance')/book[last()]/title" value="context()"/><xforms:setvalue ref="instance('main-instance')/book[last()]/author" value="context()/following-sibling::author"/></xforms:action>

The resulting main-instance is as follows:

<instance><book><title>Don Quixote de la Mancha</title><author>Miguel de Cervantes Saavedra</author></book><book><title>Jacques le fataliste et son ma??tre</title><author>Denis Diderot</author></book><book><title>Childhood's End</title><author>Arthur C. Clarke</author></book></instance>

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.

4.4. 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:

<xforms:group context="personal-information">...</xforms: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.

4.5. Enhanced event() Function Support

Orbeon Forms enhances the XML Events event() function to take a qualified name as parameter:

event($attribute-name as QName) item()*

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 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.

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..

4.6. 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:

<xforms:dispatch name="rename-control" target="my-model"><xxforms:context name="my:control" select="my/control"/><xxforms:context name="my:control-name" select="'beverage-selection'"/></xforms:dispatch>

<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:

<xforms:action ev:event="rename-control"><xforms:setvalue ref="event('control')/@name" value="event('control-name')"/></xforms:action>
Note

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.

4.7. Enhanced Support for xforms-select and xforms-deselect

[TODO: describe support for these events on xforms:upload]

4.8. 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:

<!-- Repeat hierarchy --><xforms:repeat nodeset="todo-list"><xforms:repeat nodeset="todo-item"><xforms:switch><xforms:case id="edit-case">...</xforms:case><xforms:case id="view-case">...</xforms:case></xforms:switch></xforms:repeat></xforms:repeat><xforms:trigger><xforms:label>Toggle Me!</xforms:label><!-- Toggle the case within the 5th todo item of the 3rd todo list --><xforms:toggle ev:event="DOMActivate" case="edit-case" xxforms:repeat-indexes="3 5"/></xforms:trigger>

4.9. Validation Extensions

4.9.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:

<xforms:instance id="my-instance">...</xforms:instance><xforms:action ev:event="xxforms-invalid" ev:observer="my-instance"><xforms:toggle case="invalid-form-case"/></xforms:action><xforms:action ev:event="xxforms-valid" ev:observer="my-instance"><xforms:toggle case="valid-form-case"/></xforms:action>

4.9.2. Extension Types

Orbeon Forms supports the built-in xxforms:xml extension type. This types checks that the value is well-formed XML:

<xforms:bind nodeset="my-xml" type="xxforms: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:

<xforms:bind nodeset="my-xpath" type="xxforms:xpath2"/>
Note

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.

4.9.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).

<xforms:model schema="my-schema.xsd"><xforms:instance id="my-form" xxforms:validation="strict"><my-form>...</my-form></xforms:instance><xforms:instance id="items" xxforms:validation="skip"><items>...</items></xforms:instance></xforms:model>

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.

4.10. JavaScript Integration

4.10.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.

4.10.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 baris 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>

4.10.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.
ignoreErrors Optional When set to true, errors happening while the event is dispatched to the server are ignored. This is in particular useful when you are using a JavaScript timer (e.g. window.setInterval()) that runs a JavaScript function on a regular interval to dispatch an event to the server, maybe to have part of the UI updated. In some cases, you might not want to alert the user when a there is a maybe temporary communication error while the event is being dispatched to the server. In those cases, you call call dispatchEvent with ignoreErrors set to true.

In most cases, you only need to call dispatchEvent() with a target id and event name, as in:

ORBEON.xforms.Document.dispatchEvent("main-model", "do-something");

An event handler for the custom event can be in an XForms model or control, and can execute any valid XForms action. Here an action is explicatly declared to handle the do-something even on the XForms model:

<xforms:model id="main-model" xxforms:external-events="do-something"><xforms:action ev:event="do-something"><xforms:setvalue ref="first-name" value="instance('default-values')/first-name"/><xforms:toggle case="first-name-case"/></xforms:action></xforms:model>

4.11. 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 }).

4.11.1. AVTs on XForms Elements

Consider this example:

<xforms:load resource="/forms/detail/{instance('documents-instance')/documents/document[index('documents-repeat')]/id}"/>

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:

instance('documents-instance')/documents/document[index('documents-repeat')]/id

If the id element pointed to contains the string C728595E0E43A8BF50D8DED9F196A582, the resource attribute takes the value:

/forms/detail/C728595E0E43A8BF50D8DED9F196A582

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 only within certain attributes:

  • <xforms:submission> attributes:

    • method
    • action and resource
    • 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
  • <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.

There are plans to support AVTs in more places in the future. Please send your suggestions!

4.11.2. AVTs on XHTML Elements

AVTs are also supported on XHTML elements. You must first enable this feature in properties.xml:

<property as="xs:boolean" name="oxf.xforms.host-language-avts" value="true"/>

For example:

<xhtml:table class="zebra-table"><xhtml:tbody><xforms:repeat nodeset="*"><xhtml:tr class="zebra-row-{if (position() mod 2 = 0) then 'even' else 'odd'}"><xhtml:td><xforms:output value="."/></xhtml:td></xhtml:tr></xforms:repeat></xhtml:tbody></xhtml:table>

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:

<xhtml:html lang="{instance('language-instance')}" xml:lang="{instance('language-instance')}">...</xhtml:html>

AVTs are also usable on HTML elements within <xforms:label>, <xforms:hint>, <xforms:help>, <xforms:alert>:

<xforms:input ref="foobar"><xforms:label><xhtml:span class="{if (. = 'green') then 'green' else 'red'}-label">Inverted label</xhtml:span></xforms:label></xforms:input>
Note

It is not possible to use AVTs within the id attribute of XHTML elements.

4.12. 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.
select Mandatory XPath 2.0 expression determining the value of the variable.

Once a variable is declared, you can use it from XPath expressions for which the variable is visible:

<xhtml:body><!-- Variable pointing to the default instance's root element --><xxforms:variable name="instance" select="."/><!-- variable pointing to all the item children (using the "exforms" prefix this time) --><!-- It uses the variable declared above --><exforms:variable name="items" select="$instance/item"/><!-- The code below uses the variables in scope --><xforms:repeat nodeset="$items" id="items-repeat"><exforms:variable name="current-item" select="."/><xxforms:variable name="current-position" select="position()"/><xforms:output id="my-count" ref="$current-item/value"><xforms:label value="concat($current-item/label, ':')"/><xforms:setvalue ev:event="my-event" ref="$current-item/value" value="count($items) + $current-position"/></xforms:output></xforms:repeat></xhtml:body>

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:

<xhtml:head><xforms:model id="my-model"><xforms:instance id="my-instance">...</xforms:instance><xxforms:variable name="my" select="."/></xforms:model><xforms:model id="her-model"><xforms:instance id="her-instance">...</xforms:instance><xxforms:variable name="her" select="instance('her-instance')"/></xforms:model></xhtml:head><xhtml:body><!-- $my is visible from here, but not $her --><xforms:output value="$my"><xforms:label>My stuff:</xforms:label></xforms:output><xforms:group model="her-model"><!-- $her is visible from here, but not $my --><xforms:output value="$her"><xforms:label>Her stuff:</xforms:label></xforms:output></xforms:group></xhtml:body>

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).

4.13. Dialogs

4.13.1. The xxforms:dialog Control

You declare dialogs directly under the <xhtml:body> element with:

<xxforms:dialog id="my-dialog-id" appearance="full | minimal" level="modeless" close="true" draggable="true" visible="false"><xforms:label>Dialog title</xforms:label>Content of the dialog (XHTML + XForms)</xxforms:dialog>
  • 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:
  • full (default)
  • minimal
You can set the appearance to either full or minimal:
  • The first screenshot below shows a dialog with appearance="full" while the second one shows a dialog with appearance="minimal".
  • In general, you will use the minimal dialog when you want to show a limited set of information which is related to a certain element in the page. The minimal dialog is sometime also referred to as a "drop-down dialog".
  • Some of the other attributes on <xxforms:dialog> can only be used for the full or the minimal dialog. You will find more details on this below.

level Optional. Can only be used appearance is set to full. Possible values are:
  • modal (default)
  • modeless
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:
  • true (default)
  • false
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:
  • true (default)
  • false
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:
  • true
  • false (default)
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.

4.13.2. The xxforms:show and xxforms:hide Actions

You open a dialog by using the xxforms:show action:

<xforms:trigger><xforms:label>Show Dialog</xforms:label><xxforms:show ev:event="DOMActivate" dialog="hello-dialog"/></xforms:trigger>

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:
  • true (default)
  • false

You close a dialog by using the xxforms:hide action:

<xforms:trigger><xforms:label>Hide Dialog</xforms:label><xxforms:hide ev:event="DOMActivate" dialog="hello-dialog"/></xforms:trigger>

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.

4.13.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:

<xxforms:dialog id="hello-dialog"><xhtml:div>Hello!</xhtml:div><xxforms:setvalue ev:event="xxforms-dialog-open" ref="..." value="..."/></xxforms:dialog>

4.13.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.

4.14. Submission Extensions

4.14.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.

<xforms:submission id="save-submission" ref="instance('my-instance')" method="put" resource="/exist/rest/ops/my-file.xml" replace="none" xxforms:username="admin" xxforms:password=""/>

4.14.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:

<property as="xs:string" name="oxf.xforms.forward-submission-headers" value="Authorization SM_USER"/>

It can also be set on a per-page basis on your first model element:

<xforms:model xxforms:forward-submission-headers="Authorization SM_USER">...</xforms:model>

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.

Note

The Authorization is treated specially: if a username is specified on the submission with xxforms:username, then this header is never forward.

Warning

Forwarding authentication-related headers may cause a security risks when communicated with non-trusted servers. Use carefully!

4.14.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:

<xforms:submission xxforms:show-progress="false"/>

Similarly the xxforms:show-progress="false" attribute can be used with the xforms:load action:

<xforms:load xxforms:show-progress="false"/>

4.14.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.

4.14.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.

<xforms:submission id="my-submission" method="post" resource="http://example.org/" replace="instance" xxforms:instance="my-instance"/>

4.14.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.

<xforms:submission id="my-submission" method="post" resource="http://example.org/" replace="instance" xxforms:xinclude="true"/>

4.14.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 or put method is required.

  • You must use a binary serialization attribute. This includes all mediatypes which are not XML or text, including application/octet-stream, image/*, etc.

  • The node referred to by the submission must be of type xs:anyURI.

<xforms:instance id="attachment"><attachment>file:/Users/jdoe/Applications/apache-tomcat-5.5.20/temp/xforms_upload_30877.tmp</attachment></xforms:instance><xforms:bind nodeset="instance('attachment')" type="xs:anyURI"/>...<xforms:submission id="save-submission" ref="instance('attachment')" method="put" serialization="application/octet-stream" replace="none" resource="http://example.com/foo.bin"/>...

Alternatively, you can set the type information using the xsi:type attribute:

<xforms:instance id="attachment"><attachment xsi:type="xs:anyURI">file:/Users/jdoe/Applications/apache-tomcat-5.5.20/temp/xforms_upload_30877.tmp</attachment></xforms:instance>

4.15. Other Extensions

4.15.1. <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>

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.

Note

<xxforms:script> actions are currently always executed last in a sequence of XForms actions, even if they appear before other XForms actions.

4.15.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:

<xforms:instance id="resources-instance" src="/forms/resources/en" xxforms:readonly="true"/>

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".

4.15.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>:

<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 serialization="none" resource="/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"/>

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:

<xforms:action ev:event="DOMActivate"><xforms:send submission="save-submission"/><xforms:dispatch name="xxforms-instance-invalidate" target="data-to-save-instance"/></xforms:action>

It is also possible to remove all shared instances from the cache by using the xxforms:invalidate-instances action, for example:

<xxforms:invalidate-instances ev:event="DOMActivate"/>

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:

<xforms:instance id="resources-instance" src="/forms/resources/en" xxforms:readonly="true" xxforms:shared="application" xxforms:ttl="3600000"/>
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.

4.15.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:

<xforms:select1 ref="state" xxforms:refresh-items="false"><xforms:label>State</xforms:label><xforms:item><xforms:label>[Select...]</xforms:label><xforms:value/></xforms:item><xforms:itemset nodeset="instance('schema-instance')/xs:simpleType[@name = 'state']//xs:enumeration"><xforms:label ref="@value"/><xforms:value ref="@value"/></xforms:itemset></xforms:select1>

4.15.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:

<xforms:group model="my-model" appearance="xxforms:internal"><!-- More XForms controls --></xforms:group>

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.

4.15.6. Trees with the xxforms:tree Appearance

[TODO: describe the Orbeon Forms xxforms:tree appearance on xforms:select and xforms:select1]

4.15.7. Menus with the xxforms:menu Appearance

[TODO: describe the Orbeon Forms xxforms:tree appearance on xforms:select1]

4.15.8. Autocomplete box xxforms:tree Appearance

[TODO: describe the Orbeon Forms xxforms:autocomplete appearance on xforms:select and xforms:select1]

4.15.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>

This feature has been requested for inclusion in XML Events 2.

4.15.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>:

<xforms:trigger xxforms:modal="true"><xforms:label>Save</xforms:label><xforms:send ev:event="DOMActivate" submission="save-submission"/></xforms:trigger>

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.

5. Configuration

5.1. State Handling

5.1.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:

  • Server-side: in this case, state information is stored on the server. Only very little state information circulates between client and server. The most frequently used state information is stored in memory. Less frequently used state information is stored on disk in a local database.

    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 even when no request is being processed. This creates additional demand for resources on the server and slightly complicates the task of tuning the server.

    • State information can become unavailable when sessions expire or when the server is restarted. When state information becomes unavailable for a page, that page will no longer function unless it is reloaded.

    Note
    Orbeon Forms ensures that it is possible to open multiple client browser windows showing the same page within the same session.
  • 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.

By default, Orbeon forms store XForms state information on the server. Please change this default to client-side only if you have well understood the tradeoffs explained above.

5.1.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 server, state is stored server-side. For example:

<!-- Store state on the server --><property as="xs:string" name="oxf.xforms.state-handling" value="server"/>

The global configuration can be overridden for each page by setting the xxforms:state-handling attribute in the page. This attribute can be set 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 on the server, the maximum size of the data to be stored globally in memory can be selected using the oxf.xforms.store.application.size property. The size is specified in bytes:

<!-- Allow a maximum of 20 MB of state information among all users --><property as="xs:integer" name="oxf.xforms.store.application.size" value="20000000"/>

When the allowed memory space for state information is full, Orbeon passivates state information to a local eXist database. Configuration parameters for the connection to the eXist database can be changed. The defaults are as follows:

<!-- Disk-based store connection information --><property as="xs:string" name="oxf.xforms.store.application.username" value="guest"/><property as="xs:string" name="oxf.xforms.store.application.password" value="guest"/><property as="xs:anyURI" name="oxf.xforms.store.application.uri" value="xmldb:exist:///"/><property as="xs:string" name="oxf.xforms.store.application.collection" value="/db/orbeon/xforms/cache/"/>

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:

<!-- This 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:

<!-- Store at most 10 documents in the cache --><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.

5.1.3. Session Heartbeat

If you happen to leave a browser window open on your computer, chances are that you will get back to that window and keep using the application. The last thing you want to happen when you come back is lose your session and therefore your data.

This is not always a correct guess of course: you may just happen to leave a window or tab open without planning to use it again. Conversely you may have a page which is not actually visible, for example in your browser history, yet you will come back to it. This approach wouldn???t be good for banking applications either. Still, in many situations, such as filling-out large forms, it sounds like a good idea to keep your session alive for open pages.

To achieve this goal you could make all server sessions longer. However this is harder to configure for the application developer, and this won???t discriminate between pages that are actually open on a client and the ones that are not. And while it may be ideal to have infinitely long sessions, unfortunately many applications are not ready for this kind of approach.

So Orbeon Forms supports a "session heartbeat" feature. Here is how this works:

  • When this feature is enabled (the default), an open XForms page in a client browser regularly pings the server through Ajax to keep the current server session alive.

  • The ping delay is automatically computed based on the server???s session timeout. The client pings the server at 80% of the session expiration time after the last interaction with the server.

  • We are careful not to hit the XForms engine too much, in fact we do a very limited amount of work on the server for each ping, so they should run fast.

  • XForms state information for pages hit with the heartbeat just migrates to the disk store over time if RAM is used by other pages, so keeping even large numbers of pages open should not have any negative impact on server RAM.

  • When a user gets back to using the page, state information migrates back from disk to RAM, and the page will be live again.

  • Sessions do eventually expire as nobody keeps a browser open forever.

Note that whenever an application keeps sessions alive for a long time, it is a good idea to keep as little data as possible in the session. The Orbeon Forms XForms engine itself uses a global state store and does not use session objects for storage, but do remember to keep your sessions small!

The session heartbeat should help prevent many occurrences of "session expired" error messages. As an Orbeon Forms application developer you don???t have to worry about anything: the session heartbeat is enabled by default. You can configure it globally in properties.xml:

<property as="xs:boolean" name="oxf.xforms.session-heartbeat" value="true"/>

You can also override the global default by specifying a property on the first XForms model of a page:

<xforms:model id="my-model" xxforms:session-heartbeat="false"/>

5.2. JavaScript and CSS Resources

5.2.1. 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:

<!-- Enable minimal resources --><property as="xs:boolean" name="oxf.xforms.minimal-resources" value="true"/>

5.2.2. Combined Resources

Serving CSS and JavaScript can have a high performance cost on page loads. This is particularly important with the intensive use of JavaScript in Orbeon Forms. In particular, it can be shown that serving many small files is slower than serving a single large file. In theory, HTTP pipelining can improve very much on this, but this is (very unfortunately) useless in practice at the time of writing because Internet Explorer doesn't implement it at all and Firefox / Mozilla do implemente it but do not enable it by default. This is why Orbeon Forms supports the option of combining the multiple JavaScript and CSS files required for a given XForms page into a single JavaScript file and a single CSS file.

You enable this feature in properties.xml as follows

<!-- Enable combined resources --><property as="xs:boolean" name="oxf.xforms.combined-resources" value="true"/>

When this is enabled, Orbeon Forms refers to a single JavaScript file and a single CSS file for XForms-related functionality. The URL identifies special resources needed by the page, for example:

<link rel="stylesheet" href="/ops/xforms-server/xforms-range-autocomplete-min.css" type="text/css"/><script type="text/javascript" src="/ops/xforms-server/xforms-range-autocomplete-min.js"/>

This in short tells the XForms server to produce the minimal CSS and JavaScript for the XForms engine including support for the "range" and "autocomplete" features. Note that you don't have to write these URLs yourself: the Orbeon Forms XForms engine adds them automatically to your page.

When the Orbeon Forms XForms server receives a request for a combined resource, it determine what files need to be combined and outputs them all together. Furthmore, for CSS files, all URLs referred to with url() are rewritten, so that links to images, in particular, remain correct.

In addition, you can enable caching of combined resources with:

<!-- Enable caching of combined resources --><property as="xs:boolean" name="oxf.xforms.cache-combined-resources" value="true"/>

This cache works differently from other Orbeon Forms caches, as the result is stored in the resources, typically under:

WEB-INF/resources/xforms-server/

One benefit of this mechanism is that it allows making such combined files to be served by an Apache front-end.

5.2.3. Versioned Resources

To further improve caching efficiency, Orbeon Forms supports enabling versioned resources. Usually, a resource such as a CSS, JavaScript or image file, is served through URLs like this one:

http://localhost:8080/orbeon/xforms-server/xforms-dialog-min.js

When configuring caching on the server, for example by using an Apache front-end, you may face a dilemma:

  • Caching aggressively (with an expiration date far in the future and no revalidation) so that the client asks for the resource as rarely as possible. Doing so may cause resources on the client to be out of date.

  • Caching for a shorter period of time or by forcing revalidation so that your client always has a fresh version of the resources. Doing so may cause longer page loads and more load on the server.

Orbeon Forms solves this by providing the option of using versioned resources, that is inserting automatically a version number within resource URLs. You enable versioned resources in properties.xml:

<property as="xs:boolean" name="oxf.resources.versioned" value="true"/>

With this, the resource above is served as follows:

http://localhost:8080/orbeon/xforms-server/3.6.0.200803010236/xforms-dialog-min.js

The XForms Server component, which serves the resource in this case, sets an expiration date far in the future. For example, this is the description of the cache entry in the Firefox about:cache page:

          Key: http://localhost:8080/orbeon/xforms-server/3.6.0.200803010236/xforms-dialog-min.css
    Data size: 22524 bytes
  Fetch count: 2
Last modified: 2008-03-01 17:04:25
      Expires: 2011-12-25 17:10:42

This means that the resource can effectively be cached "for ever" by a client. In case the client visits Orbeon Forms pages often, the resources will be availabe from cache, therefore reducing page loading times and server load as well.

When Orbeon Forms is upgraded on the server, the version number changes as well. An XForms page will refer to resources with the new version number, so the cached resource is not used by the browser and a new resource is loaded from the server, before being cached. This "magic" is enabled simply with the inclusion of the Orbeon Forms version number in the URL.

Only CSS and JavaScript resources used by the XForms engine are loaded through the XForms Server component. Other resources like images referred by XForms stylesheets are served by the Page Flow Controller, through URLs like this one:

http://localhost:8080/orbeon/ops/images/xforms/error.gif

With resource versioning enabled, the URL becomes:

http://localhost:8080/orbeon/3.6.0.200803010236/ops/images/xforms/error.gif

When resource versioning is enabled, the Page Flow Controller by default serves all the resources defined in <files> elements by first checking the oxf.resources.versioned property. If versioning is enabled, the PFC removes the version number from the URL before searching for the resource on disk. It is possible to turn this behavior on and off selectively with the versioned attribute. Here is how to turn off versioning for PDF files in page-flow.xml:

<config xmlns:oxf="http://www.orbeon.com/oxf/processors" xmlns="http://www.orbeon.com/oxf/controller"><!-- GIF images are loaded following oxf.resources.versioned --><files path-info="*.gif"/><!-- More file definitions here -->...<!-- PDF files are not versioned --><files path-info="*.pdf" versioned="false"/><!-- More file definitions here -->...<!-- More page definitions here -->...</config>

Conversely, resource URLs produced by an XForms page are automatically rewritten following the Page Flow's <files> definitions.

The versioning mechanism is made available to your own application resources as well. Any resource whose path doesn't start with /ops/ or /config/ is considered part of your application, not of Orbeon Forms. In that case, the Orbeon Forms version number is not used, but you specify instead an application version number in properties.xml:

<property as="xs:string" name="oxf.resources.version-number" value="1.6.3"/>

Note that if this property is commented out or missing, no versioning takes place for your application resources even if oxf.resources.versioned is set to true.

For deployed application, you should upgrade the application version number whenever you modify application resources so that clients retrieve the proper resources.

The following scenario shows the entire lifecycle for application resources:

  • You an image as RESOURCES/apps/foo/bar.png

  • You refer to it as:

    <xhtml:body><xhtml:img src="/apps/foo/bar.png" alt="My Image"/></xhtml:body>
  • With versioning enabled, the image path is rewritten automatically as follows:

    /1.6.3/apps/foo/bar.png

    Note that the application resource number is used because the resource is not part of Orbeon Forms.

  • Your browser sees a URL like:

    http://localhost:8080/orbeon/1.6.3/apps/foo/bar.png
  • When the browser loads the image, the PFC receives back:

    /1.6.3/apps/foo/bar.png
  • The PFC knows that PNG files are versioned, so removes the version number and sends this resource to the browser:

    RESOURCES/apps/foo/bar.png

From client-side JavaScript, you can access the application version number as follow:

var version = ORBEON.util.Utils.getProperty(APPLICATION_RESOURCES_VERSION_PROPERTY);

At the moment, the resources served by the PFC (that is all the resources except the XForms engine's CSS and JavaScript resources) do not automatically get a special expiration date. If you want to fully leverage client-side caching capabilities, you may want to use an Apache front-end or a Servlet filter to modify the Expires header of those resources. With Apache, you can use mod_expires.

In case you use Apache, you can in addition configure a rewriting rule with mod_rewrite to allow Apache to directly load resources containing a version number, as shown below.

Note

We recommend restarting Orbeon Forms after changing the oxf.resources.versioned property, as data in Orbeon Forms caches may not be made aware of the change until the next restart.

5.2.4. Examples of Apache Configurations

Here is how you can configure Apache to serve Orbeon Forms resources. This assumes the following:

  • Orbeon Forms deployed under the /orbeon context

  • Orbeon Forms exploded WAR file under /home/orbeon/war/

  • orbeon-resources-public.jar unziped under /home/orbeon/war/WEB-INF/orbeon-resources-public/

  • oxf.xforms.cache-combined-resources set to true in properties.xml

Without resources versioning:

RewriteEngine on
# Rewrite CSS and JavaScript resources served by the XForms Server
# -> make sure "oxf.xforms.cache-combined-resources" is set to "true" in properties.xml
RewriteRule ^/orbeon/(xforms-server/.*\.(css|js))$ /home/orbeon/war/WEB-INF/resources/$1 [L]
# Serve /config/theme resources
# -> make sure orbeon-resources-public.jar is unzipped under "orbeon-resources-public"
RewriteRule ^/orbeon/(config/theme/.*\.(css|png|gif))$ /home/orbeon/war/WEB-INF/orbeon-resources-public/$1 [L]
# Special handling of PNG images for IE 6
RewriteCond %{HTTP_USER_AGENT} .*MSIE\ 6.*
# Make sure the corresponding GIF image exists
RewriteCond /home/orbeon/war/WEB-INF/orbeon-resources-public/$1.gif -f
# Match on PNG images only and rewrite to GIF
RewriteRule ^/orbeon/(ops/.*)\.png$ /home/orbeon/war/WEB-INF/orbeon-resources-public/$1.gif [L]
# Serve /ops resources
# -> make sure orbeon-resources-public.jar is unzipped under "orbeon-resources-public"
RewriteRule ^/orbeon/(ops/.*\.(gif|css|pdf|json|js|png|jpg|xsd|htc|ico|swf))$ /home/orbeon/war/WEB-INF/orbeon-resources-public/$1 [L]
# Special handling of PNG images for IE 6
RewriteCond %{HTTP_USER_AGENT} .*MSIE\ 6.*
# Make sure the corresponding GIF image exists
RewriteCond /home/orbeon/war/WEB-INF/resources/$1.gif -f
# Match on PNG images only and rewrite to GIF
RewriteRule ^/orbeon/(.*)\.png$ /home/orbeon/war/WEB-INF/resources/$1.gif [L]
# Serve remaining resources
RewriteRule ^/orbeon/(.*\.(gif|css|pdf|json|js|png|jpg|xsd|htc|ico|swf))$ /home/orbeon/war/WEB-INF/resources/$1 [L]

With resources versioning:

RewriteEngine on
# Rewrite CSS and JavaScript resources served by the XForms Server
# -> make sure "oxf.xforms.cache-combined-resources" is set to "true" in properties.xml
RewriteRule ^/orbeon/xforms-server/[^/]+/(.*\.(css|js))$ /home/orbeon/war/WEB-INF/resources/xforms-server/$1 [L]
# Serve /config/theme resources
# -> make sure orbeon-resources-public.jar is unzipped under "orbeon-resources-public"
RewriteRule ^/orbeon/[^/]+/(config/theme/.*\.(css|png|gif))$ /home/orbeon/war/WEB-INF/orbeon-resources-public/$1 [L]
# Special handling of PNG images for IE 6
RewriteCond %{HTTP_USER_AGENT} .*MSIE\ 6.*
# Make sure the corresponding GIF image exists
RewriteCond /home/orbeon/war/WEB-INF/orbeon-resources-public/$1.gif -f
# Match on PNG images only and rewrite to GIF
RewriteRule ^/orbeon/[^/]+/(ops/.*)\.png$ /home/orbeon/war/WEB-INF/orbeon-resources-public/$1.gif [L]
# Serve /ops resources
# -> make sure orbeon-resources-public.jar is unzipped under "orbeon-resources-public"
RewriteRule ^/orbeon/[^/]+/(ops/.*\.(gif|css|pdf|json|js|png|jpg|xsd|htc|ico|swf))$ /home/orbeon/war/WEB-INF/orbeon-resources-public/$1 [L]
# Special handling of PNG images for IE 6
RewriteCond %{HTTP_USER_AGENT} .*MSIE\ 6.*
# Make sure the corresponding GIF image exists
RewriteCond /home/orbeon/war/WEB-INF/resources/$1.gif -f
# Match on PNG images only and rewrite to GIF
RewriteRule ^/orbeon/[^/]+/(.*)\.png$ /home/orbeon/war/WEB-INF/resources/$1.gif [L]
# Serve remaining resources
RewriteRule ^/orbeon/[^/]+/(.*\.(gif|css|pdf|json|js|png|jpg|xsd|htc|ico|swf))$ /home/orbeon/war/WEB-INF/resources/$1 [L]
Note

The rewriting rules above have special handling of PNG images for IE 6: when that browser is detected, any request for PNG image having a corresponding GIF image serves the GIF images instead. If you don't need that behavior, remove the corresponding lines in the rules above.

All in all, the rules above perform the following:

  • Special handling for XForms JavaScript and CSS files (using the cached/combined/minimized resources)
  • Serving of /config/theme resources originally in orbeon-resources-public.jar
  • Special handling of PNG images for IE 6 for /ops resources originally in orbeon-resources-public.jar
  • Serving of other /ops resources originally in orbeon-resources-public.jar
  • Special handling of PNG images for IE 6 for resources under RESOURCES
  • Serving of other resources under RESOURCES

5.3. Browser Navigation (Back and Forward) Handling

When visiting an XForms page by using your browser's Back and Forward buttons, or other browser-history mechanisms, Orbeon Forms by default restores the appearance of that page as it was when you left it. (Browsers don't automatically handle this behavior with Ajax applications!) This behavior best matches the usual user experience obtained when navigating regular web pages.

In certain situations, it can be useful instead to ask the XForms page to reload entirely. You control this by using the xxforms:revisit-handling attribute on the first XForms model of the page you want to reload. This attribute supports two values: restore (the default) and reload. Example:

<xforms:model xxforms:revisit-handling="reload"/>
Note
It is recommended to use the reload value carefully, as reloading pages upon browser navigation often does not match the expectation of the user.

5.4. Encryption

Orbeon Forms encrypt some information sent to the client (for example when using client-side state state handling). This is done through the following property in properties.xml:

<property as="xs:string" name="oxf.xforms.password" value="REPLACE THIS WITH YOUR OWN PASSWORD"/>
Warning

It is strongly advised to change the default password in the property above.

In addition, Orbeon Forms by default encrypts the value of selection controls before sending them to the client. This can be controlled with this property:

<property as="xs:boolean" name="oxf.xforms.encrypt-item-values" value="true"/>

In general, this should be set to true, but you can set it to false if you need to access the value of selection controls through JavaScript on the client, or through offline binds.

5.5. Debugging XForms Pages

5.5.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.

Sometimes, this provides enough information to the developer to figure out what went wrong. But often 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.

These settings enable 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 shows a sample XForms logging session:

event - dispatching {name: "DOMFocusIn", id: "xforms-element-222", location: "line 28 of XFormsDOMFocusInEvent.java"}
  action - executing {action name: "setvalue"}
setvalue - setting instance value {value: "4", instance: "fr-form-instance"}
event - dispatching {name: "xforms-recalculate", id: "fr-form-model", location: "line 1895 of XFormsModel.java"}
  model - performing recalculate {model id: "fr-form-model"}
  model - done recalculating {time: "4"}
event - dispatching {name: "xforms-revalidate", id: "fr-form-model", location: "line 1900 of XFormsModel.java"}
  model - performing revalidate {model id: "fr-form-model"}
  model - done rebuilding {model id: "fr-form-model", time: "1"}
event - dispatching {name: "xforms-refresh", id: "fr-form-model", location: "line 1905 of XFormsModel.java"}
  model - performing refresh {model id: "fr-form-model"}
  controls - start building
    model - evaluated variables {count: "1"}
  controls - end building {time (ms): "22"}
  event - dispatching {name: "xforms-value-changed", id: "xforms-element-222", location: "line 27 of XFormsValueChangeEvent.java"}
    action - executing {action name: "setvalue"}
      setvalue - setting instance value {value: "dirty", instance: "fr-persistence-instance"}
  event - dispatching {name: "xforms-valid", id: "xforms-element-222", location: "line 27 of XFormsValidEvent.java"}
event - dispatching {name: "xforms-recalculate", id: "fr-persistence-model", location: "line 1895 of XFormsModel.java"}
  model - performing recalculate {model id: "fr-persistence-model"}
  model - done recalculating {time: "5"}
event - dispatching {name: "xforms-revalidate", id: "fr-persistence-model", location: "line 1900 of XFormsModel.java"}
  model - performing revalidate {model id: "fr-persistence-model"}
  model - done rebuilding {model id: "fr-persistence-model", time: "5"}
event - dispatching {name: "xforms-refresh", id: "fr-persistence-model", location: "line 1905 of XFormsModel.java"}
  model - performing refresh {model id: "fr-persistence-model"}
  controls - start building
    model - evaluated variables {count: "1"}
  controls - end building {time (ms): "9"}
  event - dispatching {name: "xforms-value-changed", id: "fr-data-status-input", location: "line 27 of XFormsValueChangeEvent.java"}
  event - dispatching {name: "xforms-valid", id: "fr-data-status-input", location: "line 27 of XFormsValidEvent.java"}
controls - evaluating controls
controls - done evaluating controls {time (ms): "4"}

5.5.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's xhtml:body element, typically just before closing that element:

<xhtml:body>...<widget:xforms-instance-inspector xmlns:widget="http://orbeon.org/oxf/xml/widget"/></xhtml:body>

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.