Orbeon Forms User Guide

Changes in Version 3.5

1. Introduction

Welcome to Orbeon Forms 3.5!

Orbeon Forms 3.5 features many improvements over Orbeon PresentationServer (OPS) 3.0.1, including XForms engine performance enhancements, enhanced browser support, and quality improvements. Orbeon Forms 3.5 also features a much simplified directory structure that makes it easier to get started with your own Orbeon Forms applications.

This document describes changes made between Orbeon PresentationServer 3.0.1 and Orbeon Forms 3.5.2.

2. Changes in Version 3.5.1

Orbeon Forms 3.5.1 is an update to Orbeon Forms 3.5.

2.1. Noteworthy Changes

  • Support for combined XForms resources. The XForms engine now supports an option to automatically combine CSS and JavaScript resources used by XForms pages. This can lead to page loading time improvements. See the XForms Reference for details.

    This feature was kindly sponsored by Teleflex.

  • Tree and menu memory leaks. The tree and menu controls have been causing significant memory leaks on the browser, especially on in IE. The leaks could be in the order of several MB per page load. If you are using the tree or menu control, you should consider upgrading to 3.5.1. See issue #306754.

  • Incorrect XPath evaluation of preceding:: and preceding-sibling:: axes. This issue could result in particularly confusing results when using XPath expressions with these axes from XForms. See issue #306836.

  • XSLT memory leak. In certain circumstances, too many objects were stored in the Orbeon Cache when using XSLT. This could cause Orbeon Forms to run out of memory. See issue #306826.

  • XForms Classic memory leaks. In certain circumstances, too many objects were stored in the Orbeon Cache when using XForms Classic. This could cause Orbeon Forms to run out of memory. See issue #306827.

  • Partial support for ev:observer attribute. This attribute, defined by the XML Events specification, allows you to register event handlers by specifying an element identifier, instead of embedding the event handler within that element. This is particularly useful to register event handlers on <xforms:instance> elements, which do not allow you to directly embed XML event handlers. The current support is limited to adding the ev:observer attribute on XForms actions under <xforms:model> with the ev:observer attribute referring to a child <xforms:instance>. See the XForms Reference for details.

  • New xxforms:index() function. 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. See the XForms Reference for details.

  • Attribute Value Templates (AVTs). Support for AVTs is now documented. Support for escaping brackets has been added. See issue #306835.

  • Auto-complete field in repeat. Only the auto-complete initially present when the page was generated used to work in repeat. Now the auto-complete feature also works on auto-complete controls that are added to the page after it is first loaded. See issue #306805.

  • Documentation of submission attribute. The extension attribute xxforms:show-progress="false" of <xforms:submission> is now documented.

2.2. Complete List of Issues Addressed in this Release

3. Changes in Version 3.5

Orbeon Forms 3.5 features the following changes:

3.1. Orbeon PresentationServer is now Orbeon Forms

The product has been renamed Orbeon Forms. Plase refer to the FAQ entry for more information.

3.2. New Orbeon Forms Tutorial

A brand new tutorial is available! It guides you through the Orbeon Forms installation, a simple Hello application, and then shows how to build the Bookcast application, complete with handling of persistence and production of an Atom feed.

3.3. XForms Performance

  • Client-side performance improvements. The client-side event handling has been entirely reworked. Client-side JavaScript performance is now greatly improved and large forms that took seconds to load because of client-side JavaScript now load almost instantly.

  • Server-side performance improvements. New caches have been added to improve server-side performance, including a separate XPath cache and an XForms document cache. In addition, the number of XPath expressions executed as you interact with a form has been reduced.

  • JavaScript and CSS loading. JavaScript and CSS files related to particular XForms controls are loaded only when necessary. In addition, the property oxf.xforms.minimal-resources allows specifying whether "minimal" versions of those resources should be used when possible. See the XForms Reference for details.

  • Read-only and shared instances. XForms instances can be marked as read-only and can be globally shared. See Read-Only XForms Instances and Sharing of Read-Only XForms Instances for details.

3.4. XForms Platform Support

  • Safari and Opera support. Support for Safari 1.3 and above and Opera 8.5 and above in addition to Firefox and Internet Explorer. The main limitation is that the WYSIWYG HTML area does not work on Opera and Safari.

    The Safari support was kindly sponsored by Object Consulting.

  • Support for Liferay portal. Orbeon Forms, including XForms functionality, is now able to deploy as JSR-168 portlets within Liferay portal (version 4.2.1 is the most recent tried, other versions and other portals may also work), including multiple Orbeon Forms portlets at the same time. For more information, see Liferay Deployment.

    This feature was kindly sponsored by Atkins Transport Systems.

3.5. XForms Printable Formats

  • Read-only mode for forms. A read-only mode is now supported with the xxforms:readonly-appearance attribute. With xxforms:readonly-appearance="static", read-only controls take a static appearance appropriate for read-only rendition of forms in HTML. See Government Forms sample application's View Read-Only option for an example, as well as the Read-Only Mode documentation.

    This feature was kindly sponsored by Esprit.

  • Improved PDF generation. The PDF Template processor has been improved to facilitate the creation of PDF versions of forms based on PDF templates. The processor now supports groups, repetitions, and XPath 2.0. See Government Forms sample application's View PDF option for an example.

3.6. XForms Controls Enhancements

  • Autocomplete control. You enable this on xforms:select1 with the xxforms:autocomplete appearance. See XForms Controls and Google Suggests for examples.

    This feature was kindly sponsored by Mobydoc.

  • WYSIWYG HTML editor control. You enable this on xforms:textarea with the text/html mediatype. See XForms HTML Area for an example.

    This feature was kindly sponsored by Teleflex.

  • Tree control and menu control. You enable this on xforms:select1 and xforms:select (tree only) with the xxforms:tree and xxforms:menu apperances.

    This feature was kindly sponsored by Teleflex.

  • Dialog control. This control allows you to show modal or modeless dialogs.

    This feature was kindly sponsored by Teleflex.

  • Upload control. The upload control now works when submitting instances with replace="instance" or replace="none". From the form user's perspective, this allows uploading files in the background. See XForms Upload for examples.

    This feature was kindly sponsored by Teleflex.

  • Selection controls. Support of hierarchy for single selection controls xforms:select1 when using the minimal and compact appearances. Support for mix-and-match of xforms:item, xforms:itemset and xforms:choices

  • Switch within repeat. Enhanced support of xforms:switch within xforms:repeat.

  • Enhanced xforms:output support. Support for xforms:output in xforms:label, xforms:hint, xforms:help, and xforms:alert. This allow you to dynamically build the value of labels, etc. For example:

    <xforms:trigger><xforms:label>Dynamic label with a number (<xforms:output value="count(/*/*)"/>) in it!</xforms:label></xforms:trigger>

    This feature was kindly sponsored by Esprit.

  • HTML and XHTML within xforms:help Support for HTML and literal XHTML within xforms:help and xforms:hint. See the XForms Reference for documentation.

    This feature was kindly sponsored by Teleflex.

3.7. XForms 1.1 Features

  • Insert and delete actions. Support for the XForms 1.1 context and origin attributes on xforms:insert and xforms:delete.

  • Conditional XForms actions. Support for XForms 1.1 conditional actions with the if (and exf:if) attributes.

  • Repeated XForms actions. Support for XForms 1.1 actions iterations with the while (and exf:while) attributes.

  • New functions. Support for XForms 1.1 digest(), random() and seconds-to-dateTime() functions.

3.8. XForms Submission Enhancements

  • HTTP authentication for instances and submissions. xforms:instance and xforms:submission support the xxforms:username and xxforms:password to supply authorization credentials when using HTTP.

  • AVTs on xforms:submission. Support for attribute value templates (AVT) on xforms:submission action, xxforms:username and xxforms:password attributes.

  • DELETE HTTP method. Support for the XForms 1.1 DELETE HTTP method on xforms:submission.

  • urlencoded-post submission method. Support for the urlencoded-post method is now available. This allows in particular using the HTTP POST method to access APIs such as the Flickr API.

  • XForms 1.1 attributes. Support for xforms:submission's serialize, validate, and relevant attributes.

3.9. XForms Extensions

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

  • exforms:sort() extension function. The exforms:sort() function implements the eXforms proposal's sorting function.

  • xxforms:context() extension function. The xxforms:context() XPath function allows you to obtain the evaluation context for an enclosing xforms:group, xforms:repeat, or xforms:switch.

  • xxforms:evaluate() extension function. The xxforms:serialize() XPath functions allow you to respectively evaluate dynamic XPath expressions and serialize XML documents.

  • xxforms:repeat-current() extension function. The xxforms:repeat-current() XPath function allws you to find the current item of an enclosing xforms:repeat.

  • xxforms:script extension action. A new extension action xxforms:script allows you to call client-side JavaScript code as a result of XForms events.

  • Extension attributes on controls. The following extension attributes on xforms:input and xforms:textarea allow you to control aspects of the underlying HTML controls: xxforms:size, xxforms:maxlenght and xxforms:rows, xxforms:cols. See xforms:input and xforms:textarea.

3.10. XForms Instance Inspector

The new Instance Inspector allows you to visualize all the instances of your XForms page.

3.11. New Example Applications Portal

In previous versions, the examples portal, which shows the built-in Orbeon Form example, was implemented with a custom JSR-168 container. Example applications ran in as a JSR-168 portlet. Because the portal introduced an indirection and was not particularly optimized, this led to performance issues. In addition, it was not clear to users how they could run examples outside the examples portal.

In this version of Orbeon Forms:

  • The Orbeon JSR-168 container is removed. Applications, including all the examples, are now directly displayed without going through the portal. This means that examples now run much faster by default.

  • JSR-168 support is still present (in fact it is much improved), but Orbeon Forms no longer comes with its own portal. Use a portal such as Liferay to deploy Orbeon Forms portlets.

  • The example applications portal layout is simply created in a theme under config/theme-portal.xsl.

  • Example descriptors (example-descriptor.xml) included with each example are now removed. The Orbeon Forms source code viewer no longer uses this file and automatically gathers the list of files for each application.

3.12. Improved Applications Directory Structure

The Orbeon Forms resources (found under WEB-INF/resources) are now better organized:

  • A single top-level apps directory contains all the applications deployed within Orbeon Forms. To create your own applications, simply create a subdirectory of the apps directory that contains a Page Flow file (page-flow.xml). Adding or removing applications is is simply a matter of adding or removing directories.

  • The only remaining top-level directory, besides the apps directory, is the config directory, which contains Orbeon Forms configuration files that you can modify according to your needs.

  • The contents of the private ops directory is moved to JAR files: ops-resources-private.jar and ops-resources-public.jar. You should rarely have to modify these resources, unless you are adding functionality to Orbeon Forms or fixing Orbeon Forms bugs.

    • ops-resources-private.jar contains private Orbeon Forms resources.

    • ops-resources-public.jar contains public Orbeon Forms resources. This JAR file can be expanded in order to allow its content to be served directly by a web server such as Apache.

The new directory structure makes it easier to get started with your own Orbeon Forms applications. It also makes upgrading to a new version of Orbeon Forms easier, since the files you are not likely to modify are packaged in JAR files that you simply replace during an upgrade.

3.13. New Government Forms Sample Application

Previous versions of Orbeon Forms came with the "BizDoc" and then the "DMV Forms" sample applications. Orbeon Forms 3.5 comes with the Government Forms application, which shows how you can handle complex forms with Orbeon Forms. In particular:

  • Create, save, update, and delete forms persisted in the eXist XML database using a REST API directly from XForms.

  • Perform as-you-type validation and display an always up-to-date error summary.

  • Produce read-only, XML or PDF versions of your forms.

  • Handle internationalization and change language on the fly.

3.14. Other Enhancements

  • XInclude processor. The XInclude processor now supports an extension attribute, xxi:omit-xml-base, which disables producing xml:base attributes upon inclusion. This can be quite useful when performing schema validation on the result, or when xml:base resolution on the result must be performed relative to the URL base of the including document, such as when including an XForms model into an XForms page.

  • New XForms Submission processor. A new XForms Submission processor has been added. It exposes the functionality of <xforms:submission> to XML pipelines and allows you to call REST services from XPL without creating XForms pages.

  • New Execute processor. A new Execute processor has been added. It allows executing external commands and retrieving the command's standard output and standard error.

  • XUpdate processor. The XUpdate processor now supports an extension element, xu:node-set, which allows functions to return node-sets.

  • Delegation processor. When using the delegation processor to call web services, by default the processor throws an exception when the remote service returns a SOAP fault. Now the delegation processor can also be configured to return the SOAP fault document instead of throwing an exception.

  • Portlet preferences processor. Two processors, oxf:portlet-preferences-generator and oxf:portlet-preferences-serializer, allow for reading and writing portlet preferences. See JSR-168 Portlets for more information.

3.15. Library Upgrades

  • Upgrade to the Yahoo! User Interface library as a support library for the client-side part of the XForms engine. Orbeon Forms no longer uses Sarissa.

  • The embedded eXist database has been upgraded to version 1.1.1.

  • The embedded Saxon XSLT, XQuery and XPath engine has been upgraded to version 8.8.

  • Other JAR files have been updated to more recent versions, including dom4j (1.6.1), Jaxen (1.1 beta 9), and ant (1.6.5).

3.16. Bug-Fixes

Too many bugs have been fixed to be listed here. You can search for closed bugs on the ObjectWeb Tracker.

3.17. Upgrade Notes

Since the Orbeon Forms resources (found under WEB-INF/resources) have been reorganized, you will have to do a few changes when you upgrade from OPS 3.0 or 3.5 M1 to Orbeon Forms 3.5. We suggest the following:

  • First, backup everything ;-)

  • Rename your old resources/ops to resources/ops.bak.

  • Rename your old resources/config to resources/config.bak.

  • Copy the new Orbeon Forms resources/config directory to your resources directory.

  • If you hadn't make any custom changes under the config directory, that should be it. Otherwise, you will need to merge those changes into the new config directory. Note in particular that theme.xsl no longer exist, and is replaced instead by theme-plain.xsl and theme-portal.xsl (referred from epilogue-servlet.xpl).