This document describes changes made between Orbeon Forms 3.5.1 and Orbeon Forms 3.6.
Orbeon Forms 3.6 is an update to Orbeon Forms 3.5.1.
-
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 xmlns:my="http://orbeon.org/oxf/examples/my" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://orbeon.org/oxf/examples/my" elementFormDefault="qualified" attributeFormDefault="unqualified">
<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:
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:
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:
An initially collapsed section containing details of the error useful to the developer:
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:
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 (orbeon-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.
Orbeon Forms 3.6 addresses over 170 bugs and features:
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>
