Orbeon Forms 3.7.1

Historical note: Orbeon Forms 3.7.1 was released on June 1, 2009.


Orbeon Forms 3.7.1 (Developer Release) features over 400 improvements since Orbeon Forms 3.6, including the new Form Builder authoring tool, the new Form Runner environment, and enhancements in the areas of performance, core XForms engine features, schema validation, session handling, caching, and application server support.

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

Please also make sure to check all releases on the downloads page.

Changes in version 3.7.1 (developer release)

Noteworthy changes

  • New version numbering scheme. Starting with Orbeon Forms 3.7.1, Orbeon Forms adopts a new numbering scheme:

    • Even-numbered releases (3.6, 3.8, etc.) are considered "stable" releases
    • Odd-numbered releases (3.7, 3.9, etc.) are considered "developer" releases

    This scheme follows the practice of a number of other open source projects.

  • Form Builder editor. Orbeon Form Builder is a visual form designer which allows you to build and deploy forms in minutes right from your web browser.

    For more information see the Form Builder product page.

    Try Form Builder right from this Orbeon Forms installation!

  • Form Runner environment. Orbeon Form Runner is the Orbeon Forms runtime environment. Form Runner manages form definitions and form data, handles search, validation, and takes care of the plumbing necessary to capture, save, import and export form data. Features include:

    • Customizable, extensible persistence layer (eXist and Oracle support out of the box)
    • Summary page with built-in search
    • Standard page layout and look and feel
    • As-you-type validation with error summary
    • Customizable submission process
    • Printable HTML output
    • PDF output
    • Send form data, PDF and attachments by email
    • Fully internationalized UI
    • Built-in accessible "noscript" mode

    Form Runner is built on top of core Orbeon Forms technologies, including the XForms and XPL engines.

    For an example running on top of Form Runner, see the Bookshelf form.

  • Noscript mode. The "noscript mode" in Orbeon Forms allows you to use a single XHTML+XForms description of a page and to target browser that have JavaScript disabled. This is integrated into Form Runner, which means you don’t need JavaScript on the client to fill-out forms created by Form Builder. This is also the basis for the accessibility features we are working on (including WCAG AA compliance).

    More documentation is available in the Noscript (Accessible) Mode Guide.

  • Firefox 3 support. Orbeon Forms version 3.6 had a known bug with Firefox 3. This issue is now resolved.

  • Performance improvements.

    • Session heartbeat feature for XForms pages. Orbeon Forms now enables by default the Session Heartbeat feature. This allows sessions associated with live pages in a user's browser to stay active, therefore preventing situations where the user gets back to a form and gets session expiration errors.

      See also Session Heartbeat.

      This feature is kindly sponsored by Teleflex.

    • Versioned resources. Orbeon Forms now supports versioning of resources such as CSS, JavaScript, and images. This allows more aggressive client-side caching, thereby reducing page loading times as well as server load.

      See Versioned Resources for the full documentation.

      This feature is kindly sponsored by Teleflex.

  • Enhanced user interface controls.

    • Reusable user interface components. Orbeon Forms now implements a complete system of reusable components, based on the XBL 2 specification. This allows you to define and reuse UI components in your forms. There is no limit to the types of components you can build: examples include special date selectors, color pickers, reusable address blocks, etc.

    • Improved date and time controls. You can now type in dates, and the date picker is by default the YUI date picker. We have also added controls for xs:time and xs:dateTime types. The date picker is localized in English, French and Spanish.

    • New YUI controls. Orbeon Forms now use the YUI date picker as well as the YUI Rich Text Editor (RTE). The older JSCalendar and FCKeditor implementations are still available through properties.

    • Modal triggers. Usually, activating a trigger on the client doesn't prevent further actions in the user interface. Sometimes, it is however useful to block such further actions until some processing is complete, for example calling a submission that saves a document.

      See Modal Trigger Behavior for documentation.

      This feature is kindly sponsored by Teleflex.

    • Improved handling of alerts. In XForms the behavior of xforms:alert is not built-in. Instead, the behavior was initially planned to be controlled through CSS. Previous versions of Orbeon Forms displayed an alert icon and message (if provided) only if the value associated with the control was invalid. Orbeon Forms now by default shows the control in alert state when the value is invalid, but also when it is required but empty.

  • Enhanced XForms 1.1 support. In particular:

  • Core XForms support improvements.

    • Inline XML Schema support with XForms. XForms supports using XML Schemas which are embedded within the <xforms:model> element. Orbeon Forms now supports this feature. This is particularly useful when you create a new schema which is just used within an XForms document, or to define a series of simple types used for validation.

      <!-- A simple inline XML Schema -->
      <xs:schema elementFormDefault="qualified" attributeFormDefault="unqualified">
      <xs:simpleType name="link">
      <xs:restriction base="xs:string">
      <xs:pattern value="(https?\://([^/?#]+)/([^?#]*)(\?([^?#]+))?(#(.*))?)?"/>
      <!-- More XForms model constructs below -->

      The XML Schema definitions are directly available to the model, in particular to binds:

      <xforms:bind nodeset="my-link" type="link"/>
    • Event handling improvements. The XML Events ev:observer attribute used to be only supported within a model to refer to a nested instance. It is now globally supported. Support for the more rarely needed ev:target attribute has been added as well.

      See also Using the ev:observer and ev:target Attributes.

  • XPath functions additions and improvements.

    • Access request and session directly from XForms. In the past, accessing request and session information from XForms required using the page flow controller or possibly a page model written in XPL. Now, you can use XPath functions to do so.

    • More utility XPath functions. Additional utility functions have been added, notably xxforms:element(), xxforms:attribute(), xxforms:bind(), xxforms:case(), xxforms:property(), and enhancements to the standard property() function.

      See also XPath functions for more information.

  • More freedom with XForms constructs.

    • Free positioning of label, help, hint and alert elements.

      See Standalone Label, Hint, Help and Alert Elements.

    • XForms models can be positioned in more places, including within dialogs.

      See Placement of Controls and Models.

    • Support for AVTs on XHTML elements outside HTML body. This in particular allows dynamically setting, from XForms, a document's language, with the lang and/or xml:lang attributes on the <html> element.

      See Placement of Controls and Models.

    • Support for <xforms:output> within <xhtml:title>. This allows dynamically controlling, from XForms, the title of the page. For example, the title can be updated to report the current number of errors on a form.

      See Placement of Controls and Models.

    • Attribute Value Templates (AVTs) on XHTML elements. AVTs were already supported on some XForms elements. You can now use AVTs on XHTML elements as well. This allows you to use XForms to influence aspects of XHTML such as class, style or colspan attributes.

      See AVTs on XHTML Elements for documentation.

      This feature is kindly sponsored by Teleflex.

  • Other extensions to XForms constructs.

    • Variables within controls, models and actions. You can now declare variables usable from any XPath expression in an XForms document, using the xxforms:variable (or exforms:variable) element. 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.

      See Variables for documentation.

    • Generalized context attribute on XForms elements. XForms 1.1 introduces the context attribute on <xforms:insert> and <xforms:delete>. Orbeon Forms now supports this convenient attribute on all elements changing the XPath evaluation context, including controls, actions, binds, and submissions. Further versions of XForms are likely to extend support this way.

      See Generalized context attribute for the documentation.

    • ev:event, ev:observer and ev:target all support multiple space-separated event names and identifiers. This is an extension to XML Events 1, which is planned for XML Events 2.

      See also Multiple Event Names, Observers and Targets on Event Handlers.

    • Custom Model Item Properties. You can place user-defined Model Item Properties on the <xforms:bind> element.

      See also Custom Model Item Properties.

    • exforms:iterate attribute on actions. In particular, these additions make it much easier to iterate over nodes within actions.

      See Iteration of XForms Actions over Sequences for documentation and a complete example.

    • Declarative dynamic default instance values.

      See Extension Model Item Property to Specify default instance values.

    • Dataypes to validate XML and XPath 2 expressions.

      See Extension Types.

    • Outputting server log messages with xforms:message. xforms:message supports new level values: xxforms:log-debug, xxforms:log-info, xxforms:log-warn and xxforms:log-error. These cause the message to be logged on the server using the levels "debug", "info", "warn" and "error" as per the log4j terminology. Messages output with these levels appear in the Orbeon Forms logs depending on the configuration of log4j.xml. For example:

      <xforms:message ev:event="xforms-submit-error" level="xxforms:log-error">
      A submission error occurred:
      <xforms:output value="event('error-type')"/>

      See also Displaying Messages with the xforms:message Action.

  • Local configuration properties. You can create a local property file, config/properties-local.xml, for your own Orbeon Forms configuration properties. These add to and override existing properties. This new mechanism facilitates upgrades of Orbeon Forms, as property files no longer have to be merged.

    See also Properties File.

  • Upgrades to core libraries.

    • New Yahoo User Interface library. Orbeon Forms now uses YUI 2.6.0.
    • New eXist database. Orbeon Forms now uses eXist 1.2.4.
  • XML pipelines improvements.

    • Inline transformations in XPL. Often, processor configurations must be determined dynamicaly. XSLT is typically used for that purpose, but this can lead to heavier code. Inline transformations simplify the syntax by allowing transformations directly embedded within processor inputs:

      <p:processor name="oxf:url-generator">
      <p:input name="config" transform="oxf:xslt" href="#instance">
      <!-- This is an inline transformation -->
      <config xsl:version="2.0">
      <xsl:value-of select="/instance/mode"/>
      <p:output name="data" id="example-document"/>

      See also Embedding Transformations within Inputs.

    • Temporary files in the file serializer. The file serializer can now automatically create temporary files and write to those temporary files. It will also delete temporary files, based on a "scope" parameter you specify in the configuration. As with the Scope generator and Scope serializer, you can set the scope to either "request", "session", or "application".

    • Epilogue pipeline configurable with properties. These properties in particular allow you to pick the theme stylesheet, enable XHTML output, etc.

    • Chart Processor enhancements. The chart processor now support two new types of chart: XY charts and time series. For charts that show a lot of data points, you can also limit the number of labels shown in the categories axis with the new max-number-of-labels option.

    • Zip and unzip processors.

      See Processors - Zip and Unzip.

  • Orbeon Forms version. You can know the exact version number of the Orbeon Forms you are running by running java -jar orbeon-cli.jar -v from the command line. The FAQ has more on how to know which version of Orbeon Forms you are running.

Complete list of issues addressed in this release

Orbeon Forms 3.7.1 addresses the following bugs and features:

Compatibility notes

Legacy classic XForms engine

The legacy Classic XForms engine has been deprecated for several releases now, and should not be expected to work in Orbeon 3.7.1 and later.

This is particularly appropriate now that the XForms engine support the noscript mode, an accessible, JavaScript-free rendering mode.

<xforms:delete> Action

The <xforms:delete> action, when omitting the at attribute, now deletes all the nodes referred to by the nodeset attribute. This is as per the XForms 1.1 specification. Previously, this would only delete the first node of the node-set.

<!-- Delete all employee elements under the current context node -->
<xforms:delete xmlns:ev="http://www.w3.org/2001/xml-events" nodeset="employee"/>

You may have to modify your code if you relied on the older behavior. You can easily delete only the first node by writing:

<!-- Delete the first employee element under the current context node -->
<xforms:delete xmlns:ev="http://www.w3.org/2001/xml-events" nodeset="employee[1]"/>

Previous workarounds still work, but they are no longer needed:

<!-- Delete all employee elements under the current context node -->
<xforms:delete xxforms:iterate="employee" nodeset="."/>
<!-- Delete all employee elements under the current context node -->
<xforms:delete while="employee" nodeset="employee"/>

Binds evaluation

With Orbeon Forms 3.6 and earlier, <xforms:bind> node-sets were re-evaluated everytime an XForms recalculation or revalidation was performed. In this version, this is no longer the case: <xforms:bind> node-sets are re-evaluated during the XForms rebuild operation only, as per the XForms specification. This is meant to improve performance, but it also has a side-effect: in certain circumstances, an explicit <xforms:rebuild> action may be necessary.

<!-- This expression sets the xs:date type to the date element depending on another instance value -->
<xforms:bind nodeset="/instance/date[../is-date-type = 'true']" type="xs:date"/>
<!-- Input bound to the date element -->
<xforms:input ref="date">
<!-- This trigger allows changing the type back and forth -->
<xforms:label>Change Type</xforms:label>
<xforms:action ev:event="DOMActivate">
<xforms:setvalue ref="is-date-type" value="if (. = 'true') then 'false' else 'true'"/>
<!-- We need to do a rebuild as the XPath expressions in the bind nodeset are only reevaluated upon insert, delete, instance replacement, but not when a value is set -->

The index() Function

Due to the way repeat processing was implemented in Orbeon Forms 3.6 and earlier, the index() function could be reliably used in more places than in the current version.

XForms 1.1 does not explicitly limit in what type of XPath expressions index() can be used. However, in Orbeon Forms, it is strongly advised at the moment to only use index() within actions, and to avoid using it in control bindings and binds, as doing so may yield unpredictable results.

We hope to remove this limitation in the future.

Image triggers

Orbeon Forms 3.6 and earlier allowed using images within xforms:trigger and xforms:submit using a special appearance, xxforms:image, and a nested element, xxforms:img. This has long been deprecated and is now no longer supported. Use instead the minimal appearance. For example, replace the following:

<xforms:trigger appearance="xxforms:image">
<xxforms:img src="save.png" alt="Save"/>


<xforms:trigger appearance="minimal">
<xhtml:img src="save.png" alt="Save"/>

Notice how the image is now in the XHTML namespace, and placed within the label of the trigger.

Default HTML doctype

The default HTML DOCTYPE produced by the epilogue has changed from -//W3C//DTD HTML 4.01 Transitional//EN (HTML 4.01 transitional) to -//W3C//DTD HTML 4.01//EN (HTML 4.01 strict). This may have an impact on how your web browser interpets CSS rules.

Date picker using YUI widget

Input fields bound to node of type xs:date are now using the YUI date picker widget instead of the jscalendar widget. If your code depends on the jscalendar (or you prefer the jscalendar for whatever reason), you can instruct Orbeon Forms to use the jscalendar by setting the oxf.xforms.datepicker property to jscalendar.

Note that there is a chance that the jscalendar widget might be deprecated in the future, so you should try to use or switch to the YUI when possible.

Deprecation and removal of Java classes

The following classes, usually referenced from web.xml and portlet.xml, are still available but deprecated:

  • OPSServlet and OPSServletDelegate: use OrbeonServlet and OrbeonServletDelegate instead.
  • OPSPortlet and OPSPortletDelegate: use OrbeonPortlet and OrbeonPortletDelegate instead.
  • OPSXFormsFilter and OPSServletFilterDelegate: use OrbeonXFormsFilter and OrbeonServletFilterDelegate instead.
  • OPSServletFilter and OPSServletFilterDelegate: use OrbeonServletFilter and ServletFilterDelegate instead.

The following classes have been deprecated for a long time and are now removed:

  • ProcessorServlet: use OrbeonServlet instead.
  • ProcessorFilter: use OrbeonServletFilter instead.
  • ProcessorServletContextListener: use OrbeonServletContextListener instead.