Orbeon Forms User Guide

Changes in Version 3.7

1. Introduction

Welcome to Orbeon Forms 3.7 beta 1!

Orbeon Forms 3.7 features over 200 improvements since Orbeon Forms 3.6, including in the areas of performance, core XForms engine enhancements, schema validation, session handling, caching, and application server support.

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

NOTE: Orbeon Forms 3.7 is still UNDER DEVELOPMENT as of August 2008. The latest stable release of Orbeon Forms is 3.6.

2. Changes in Version 3.7

2.1. Noteworthy Changes

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

    [TODO: how to enable, 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.

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

  • New YUI. Orbeon Forms now uses YUI 2.5.2.

  • Inline XML Schema support. 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.

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

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

    <xforms:bind nodeset="my-link" type="link"/>
  • 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.

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

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

  • exforms:iterate attribute and XForms 1.1 context() function. 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.

  • ev:observer and ev:target attributes on action handlers. 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.

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

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

  • Change to 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.

  • 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:submission>...<xforms:message ev:event="xforms-submit-error" level="xxforms:log-error">A submission error occurred:<xforms:output value="event('error-type')"/></xforms:message></xforms:submission>

    See also Displaying Messages with the xforms:message Action.

  • 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><url>http://www.example.org/</url><mode><xsl:value-of select="/instance/mode"/></mode></config></p:input><p:output name="data" id="example-document"/></p:processor>

    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.

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

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

2.2. Complete List of Issues Addressed in this Release

NOTE: Orbeon Forms 3.7 is still UNDER DEVELOPMENT as of August 2008. The latest stable release of Orbeon Forms is 3.6.

Orbeon Forms 3.7 addresses the following bugs and features:

3. Compatibility Notes

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

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

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

<xforms:instance><instance><date>2002-08-02</date><is-date-type>false</is-date-type></instance></xforms:instance><!-- 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"><xforms:label>Value</xforms:label></xforms:input><!-- This trigger allows changing the type back and forth --><xforms:trigger><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 --><xforms:rebuild/></xforms:action></xforms:trigger>

3.3. 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"><xforms:label>Save</xforms:label><xxforms:img src="save.png" alt="Save"/></xforms:trigger>

with:

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

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

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

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