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

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.

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

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:

When using xforms:output, you can control the formatting of the date using the xxforms:format extension attribute on the xforms:output control.

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

In XForms 1.0, xforms:output is used to display text. However, based on a proposal in a draft version of XForms 1.1, Orbeon Forms supports a mediatype attribute on that element.

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:

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

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:

With original instances as follows:

The result of a first insertion is:

Orbeon Forms supports the XForms 1.1 validate and relevant attributes on xforms:submission. For more information, please visit the XForms 1.1 specification.

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.

When using XPath 2.0, the following functions from XSLT 2.0 are also available:

• format-date() (external documentation)

• format-dateTime() (external documentation)

• format-time() (external documentation)

• format-number() (external documentation)

The following functions are implemented:

• xxforms:if().

  This function implements the semantic of the XForms 1.0 if() function. See Note About XPath 2.0 Expressions for more details.

• xxforms:call-xpl($xplURL as xs:string, $inputNames as xs:string*, $inputElements as element()*, $outputNames as xs:string+) as document-node()*.

  This function lets you call an XPL pipeline.

  1. The first argument, $XPLurl, is the URL of the pipeline. It must be an absolute URL.
  2. The second argument, $inputNames, is a sequence of strings, each one representing the name of an input of the pipeline that you want to connect.
  3. The third argument, $inputElements, is a sequence of elements to be used as input for the pipeline. The $inputNames and $inputElements sequences must have the same length. For each element in $inputElements, a document is created and connected to an input of the pipeline. Elements are matched to input name by position, for instance the element at position 3 of $inputElements is connected to the input with the name specified at position 3 in $inputNames.
  4. The fourth argument, $outputNames, is a sequence of output names to read.
  5. The function returns a sequence of document nodes corresponding the output of the pipeline. The returned sequence will have the same length as $outputNames and will correspond to the pipeline output with the name specified on $outputNames based on position.

  The example below shows a call to the xxforms:call-xpl function:

  xxforms:call-xpl ('oxf:/examples/sandbox/xpath/run-xpath.xpl', ('input', 'xpath'), (instance('instance')/input, instance('instance')/xpath), 'formatted-output')/*, 'html')

• xxforms:evaluate($xpath as xs:string) as item()*.

  The xxforms:evaluate() function allows you to evaluate XPath expressions dynamically. For example:

  <xforms:input ref="xxforms:evaluate(concat('instance(''my-instance'')/document', my-xpath))"><xforms:label>...</xforms:label></xforms:input>

• xxforms:serialize($item as node(), $format as xs:string?) as xs:string.

  The xxforms:serialize() function allows you to serialize an XML node to XML, HTML, XHTML or text. For example:

  <xforms:bind nodeset="my-html" calculate="xxforms:serialize(instance('my-instance'), 'html')"/>

• xxforms:repeat-current($repeat-id as xs:string?) as node().

  The xxforms:repeat-current() function allows you to obtain a reference to an enclosing xforms:repeat's current iteration node. It takes one optional string parameter. If present, the id of the enclosing xforms:repeat is searched. If absent, the function looks for the closest enclosing xforms:repeat.

  <xforms:repeat nodeset="employee" id="employee-repeat"><tr><td><!-- The context is being set to another instance that controls the visibility of the group. --><xforms:group ref="instance('control-instance')/input"><!-- Using xxforms:repeat-current() allows reclaiming the context of the repeat iteration. --><xforms:input ref="xxforms:repeat-current('employee-repeat')/name"><xforms:label>Employee Name</xforms:label></xforms:input></xforms:group></td></tr></xforms:repeat>

  The xxforms:repeat-current() function must be called from within an xforms:repeat element.

• xxforms:context($element-id as xs:string?) as node().

  The xxforms:context() function allows you to obtain the evaluation context for an enclosing xforms:group, xforms:repeat, or xforms:switch. It takes one optional string parameter containing the id of an enclosing XForms element.

  <xforms:group ref="employee" id="employee-group"><!-- The context is being set to another instance that controls the visibility of the group. --><xforms:group ref="instance('control-instance')/input"><!-- Using xxforms:context() allows reclaiming the context of the enclosing group. --><xforms:input ref="xxforms:context('employee-group')/name"><xforms:label>Employee Name</xforms:label></xforms:input></xforms:group></xforms:group>

• xxforms:instance($instance-id as xs:string) as element()?.

  The xxforms:instance() function works like the standard instance() function except that it searches for instances in all the models of the XForms document (the standard instance() function only searches within the current XForms model).

  <xforms:model id="main-model"><xforms:instance id="main-instance">...</xforms:instance></xforms:model><xforms:model id="resources-model"><xforms:instance id="resources-instance">...</xforms:instance></xforms:model>...<xforms:group model="main-model"><xforms:output value="xxforms:instance('resources-instance')/titles/company-information"/></xforms:group>

• xxforms:index($repeat-id as xs:string?) as xs:integer.

  The xxforms:index() function behaves like the standard XForms index() function, except that its argument is optional. When the argument is omitted, the function returns the index of the closest enclosing <xforms:repeat> element. This function must always be used within <xforms:repeat> otherwise an error is raised.

  <xforms:repeat nodeset="employee" id="employee-repeat"><div><xforms:trigger><xforms:label>Add One</xforms:label><xforms:insert ev:event="DOMActivate" nodeset="../employee" at="xxforms:index()"/></xforms:trigger></div></xforms:repeat>

eXForms is a suggested set of extensions to XForms 1.0, grouped into different modules. Orbeon Forms supports the exf:mip module, which includes the following functions:

• exf:relevant()

• exf:readonly()

• exf:required()

Orbeon Forms also supports the following from the sorting module:

• exf:sort()

eXForms functions live in the http://www.exforms.org/exf/1-0 namespace, usually bound to the prefix exf or exforms.

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.

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.

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.

You can dispatch your own events from JavaScript by calling the function ORBEON.xforms.Document.dispatchEvent(). The parameters to this function are:

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:

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:

[To be completed]

[To be completed]

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.

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:

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.

The xxforms:script action allows you to call client-side JavaScript as a result of XForms events:

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

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:

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

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

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

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.

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:

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:

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:

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:

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:

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:

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.

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:

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

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:

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:

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

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

When a fatal error occurs, the XForms engine throws a Java exception which either results in an error page in your web browser (when the error occurrs during page initialization) or in an error message at the top of the displayed XForms page (when the error occurs during an Ajax request after the page is loaded). The main Java exception is also logged on the server. Often, this provides enough information to the developer to figure out what went wrong. When this is not sufficient, the best tool available is the XForms engine logging facility. To enable it, make sure you uncomment the following lines in config/log4j.xml:

This setting enables verbose logging of the XForms engine's operations, in particular:

• Dispatching of events.

• Execution of actions.

• Loading of instances.

• Execution of submissions.

• Resulting XForms instances.

• XForms cache-related operations.

The following figure shows a sample XForms logging session in Orbeon Studio:

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:

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.