Orbeon Forms User Guide

Changes in Version 3.6

1. Introduction

Welcome to Orbeon Forms 3.6!

Orbeon Forms 3.6 features over 170 improvements since Orbeon Forms 3.5.1, including major improvements in the areas of state handling, XML Schema validation, error handling, deployment within Java applications, and performance.

This document describes changes made between Orbeon Forms 3.5.1 and Orbeon Forms 3.6.

2. Changes in Version 3.6

Orbeon Forms 3.6 is an update to Orbeon Forms 3.5.1.

2.1. Noteworthy Changes

  • The XForms engine features a disk-based state store. Before this version, when using session state handling, XForm state information was stored in the user's session. Because the size of the session information was limited, state information could expire and cause certain XForms pages to no longer function when too much memory was used.

    Orbeon Forms now implements a disk-based state store, which allows state information to be stored on disk when the memory state store becomes too large. You enable this state store with the new server configuration value for the oxf.xforms.state-handling property. This is now the default state handling configuration, and when migrating to this version or Orbeon Forms we recommend that you update your properties with the following:

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

    The memory state store is now global and shared among all users and pages. Its size is configured with the following property:

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

    For more information about configuration, see State Handling.

  • Bindings support types imported from XML Schemas. In previous versions, only built-in types such as xs:integer, xs:date, etc. were supported on the type attribute of <xforms:bind> element. In this version, simple types declared in an imported XML Schema can be used. For example, assume the following schema declaring a type called my:state:

    <xs:schema targetNamespace="http://orbeon.org/oxf/examples/my" elementFormDefault="qualified" attributeFormDefault="unqualified" xmlns:my="http://orbeon.org/oxf/examples/my"><xs:simpleType name="state"><xs:restriction base="xs:string"><xs:enumeration value="AL"/><xs:enumeration value="AK"/><xs:enumeration value="AZ"/>...<xs:enumeration value="GU"/><xs:enumeration value="MP"/><xs:enumeration value="PR"/></xs:restriction></xs:simpleType></xs:schema>

    You use <xforms:bind> to assign this type as follows:

    <xforms:bind nodeset="address/state" type="my:state"/>

    Note that with XForms 1.1, the type attribute only supports simple types, or complex types with simple content. Orbeon Forms only support simple types at the moment.

    See issue #306753.

  • Improved XML Schema validation. In previous versions, XML Schema validation always followed a strict mode where all instances had to be strictly valid as per imported schema definitions. In particular, this meant that if you imported a schema, the top-level element of an instance had to have a valid schema definition or the instance would be entirely invalid.

    In this version, 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.

    In addition, the author can specify the validation mode directly on each instance with the extension xxforms:validation attribute, which takes values lax (the default), strict (the root element has to have a definition in the schema and must be valid), or skip (no validation at all for that instance).

    Nodes validated through a schema now 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. Previously, you had to bind the type with a binding even if you used a schema:

    <xforms:bind nodeset="..." type="xs:date"/>

    This is now no longer necessary if you use a schema. Of course if you don't use a schema, or if you want to perform validation in addition to what is picked-up by a schema, then using <xforms:bind> is still the correct way of binding types.

    See issues #307140, #307141 and #305063.

  • Support for XForms 1.1 types allowing empty content. Several built-in XML Schema data types, such as xs:date, do not consider an empty string as a valid value. This makes it difficult, for example, to specify the type "optional date" in XForms. With XForms 1.1, every built-in data type has a counterpart in the xforms namespace, which adds the empty string as a valid value. These types are now supported in Orbeon Forms. For example, you denote an optional date in an instance with:

    <xforms:bind nodeset="..." type="xforms:date"/>

    See issue #307162.

  • Memory usage improvements. The way XForms Model Item Properties (MIPs) are implemented has changed since Orbeon Forms 3.5.1. A memory profiler has revealed that a very large number of objects related to MIPs were created. The implementation has been modified to drastically reduce the number of such objects, with an expected benefit of reduced memory usage and less garbage collection time.

    Thanks to Adrian Baker and to CSC for their work and support regarding this issue.

    See issue #307388.

  • Help displayed as separate help panel. Orbeon Forms now displays help messages (defined with xforms:help) in a separate help panel:

    XForms Help Panel

    The help panel appears when the user selects a help icon. It stays open until closed by the user, and can be moved around the page. See the XForms Reference for more information.

  • Hints displayed as tooltips. Orbeon Forms now displays control hints (defined with xforms:hint) as tooltips:

    XForms Hints

    Hints appear when you mouse over a field, and disappear after a while. See the XForms Reference for more information.

  • Better display of JavaScript and Ajax errors. Orbeon Forms now displays JavaScript and Ajax errors in a user-friendly error dialog:

    Ajax error dialog

    An initially collapsed section containing details of the error useful to the developer:

    Ajax error dialog

    See issue #307198. Also visit the updated error page and error dialog documentation.

  • Improved XForms error location information. What's more frustrating during form development than seeing cryptic errors and not being able to find out what exact line of code caused the problem? Orbeon Forms now supports much enhanced file name and line number reporting in XForms. In many cases, error messages now indicate an exact file name and line number, along with a better call stack:

    Error with location information

    Note that this currently requires setting the following property in properties.xml:

    <property as="xs:boolean" processor-name="oxf:saxon8" name="generate-source-location" value="true"/>
    Note

    This property should usually be turned off in deployment, as line number handling with XSLT currently has a noticeable impact on performance.

    See issue #306558.

  • Support for deployment as separate WAR. Orbeon Forms can now be deployed as a Java web application archive (WAR) separate from your Java application. This is most useful when you want to produce XForms using Java technology (whether using JSP, Java Servlets, or other frameworks).

    Using XForms with your Java applications was already possible in the past, but you had to either copy over all the Orbeon Forms JAR files and configuration files into your application, or the other way around. The new deployment method allows you to deploy Orbeon Forms separately. You just need to include a very small Orbeon Forms JAR file in your application (ops-xforms-filter.jar), and to add a short configuration for a filter to your web.xml.

    Separate deployment has several benefits including:

    • Easier upgrades of both your application and Orbeon Forms.

    • Preventing situations where different versions of JAR files could conflict.

    • Cleaner application architecture.

    See Using the Orbeon Forms XForms Engine with Java Applications for more information.

    Thanks to Adrian Baker and Leigh Klotz for their input.

  • Improved support for built-in JSP deployment. Deploying JavaServer Pages (JSP) directly into Orbeon Forms is now better documented and uses the same mechanism used when deploying Orbeon Forms as a separate WAR. In addition, using setContentType() at the beginning of JSP files is no longer necessary.

    See Using the Orbeon Forms XForms Engine with Java Applications for more information.

  • Support for boolean type in input fields. Previously, <xforms:input> controls bound to nodes of type xs:boolean would display a regular input field. The control now shows a checkbox allowing to better select a boolean value. See issue #306628.

  • Support for <xforms:group> around <xhtml:tr>. This didn't work reliably in previous versions. This in particular allows controlling the visibility of table rows using <xforms:group>, for example:

    <xhtml:table><xhtml:tr><xhtml:th>Name</xhtml:th></xhtml:tr><xforms:group ref="person[address/state = 'CA']"><xhtml:tr><xhtml:td><xforms:output ref="name"/></xhtml:td></xhtml:tr></xforms:group></xhtml:table>

    Note that whether XForms implementations should support XForms elements around table rows and cells is a matter of debate, but Orbeon Forms already supports <xforms:repeat> around table rows for the convenience of form authors, and supporting groups is a matter of consistency.

    See issue #306259.

  • Support for optimization hint on selection controls. The new xxforms:refresh-items attribute on selection controls allows for performance improvements in certain cases. See Controlling Item Sets Refreshes with xxforms:refresh-items.

    See issue #307152.

  • Firebug Lite ships with Orbeon Forms. If you wish to debug JavaScript with Firebug Lite, you don't need anymore to include your own copy of Firebug Lite. Instead you can use the one that comes by default with Orbeon Forms.

2.2. Complete List of Issues Addressed in this Release

Orbeon Forms 3.6 addresses over 170 bugs and features:

2.3. Upgrade Notes

When upgrading from Orbeon Forms 3.6, please note the following:

  • The following files have been renamed: ops.war to orbeon.war, ops.jar to orbeon.jar, ops-resources-public.jar to orbeon-resources-public.jar, ops-resources-private.jar to orbeon-resources-private.jar

  • We recommend that you update your properties with the following:

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

    For more information about configuration, see State Handling.

  • Error resources moved to private location. The files error.xpl and error.xsl under RESOURCES/config have been moved to orbeon-resources-private.jar. If you haven't modified these files, make sure that you remove the old files from RESOURCES/config. If you have made modification, you will have to merge the changes introduced in orbeon-resources-private.jar.

  • Theme CSS stylesheets moved to private location. The files under RESOURCES/config/theme have been moved to orbeon-resources-public.jar. This includes xforms.css and xforms-widgets.css. If you haven't modified these files, make sure that you remove the old files from RESOURCES/config/theme. If you have made modification, you will have to merge the changes introduced in orbeon-resources-public.jar, or better, don't modify these CSS files but override CSS definitions in your own CSS files instead.

  • XML parser upgrade requires XInclude namespace change. The Xerces XML parser has been upgraded to version 2.9. The previous version supported an obsolete version of the XInclude namespace: http://www.w3.org/2003/XInclude. The new version supports the correct namespace as specified by XInclude 1.0: http://www.w3.org/2001/XInclude.

    Note that the correct version has the older year, 2001, instead of the newer year, 2003. If you are using http://www.w3.org/2003/XInclude in your namespace declarations for XInclude, you will need to change these declarations to http://www.w3.org/2001/XInclude.

  • Plain theme no longer copies attributes in XHTML namespace. The plain theme, under RESOURCES/config/theme-plain.xsl, used to convert attributes in the XHTML namespace to attributes in no namespace. If you wrote:

    <div xhtml:style="background-color: red"/>

    then the plain theme would convert this to:

    <div style="background-color: red"/>

    There does not seem to be much use for this feature, so for reasons of simplification it was removed. If you do need it then you can add again the following XSLT template:

    <!-- Copy attributes in XHTML namespace to no namespace --><xsl:template match="@xhtml:*"><xsl:attribute name="{local-name()}"><xsl:value-of select="."/></xsl:attribute></xsl:template>