Orbeon Forms User Guide

Changes in Version 2.6

1. XForms

1.1. XForms Upload

The XForms Upload control has been fixed. It comes with an example and is documented in the XForms reference documentation.

1.2. XForms Conditionals

Two new extension controls provide a mechanism to selectively enable markup and other XForms controls depending of the values stored in the XForms instance. The syntax is modeled after the XSLT language: if and choose/when/otherwise. See the XForms Conditionals documentation for more information.

1.3. Itemset Support

The XForms element <itemset> is now supported. You can use it in conjunction with XForms selection controls (<xforms:select and <xforms:select1>) when you want the list of items the end-user has to pick from to come from the instance, instead of being listed in view. For more details, see the XForms controls documentation and the XFormsControls example.

1.4. Support for ref Attribute on Label, Alert, Help, and Hint

You can now use the ref attribute on <xforms:label>, <xforms:alert>, <xforms:help>, and <xforms:hint> to have the displayed message come from the instance instead of being specified in the view. For more details, see the Label, Alert, Help, and Hint documentation.

1.5. Support for ref Attribute on Submit Controls

You can now bind a submit control (<xforms:submit>) to a node in the instance with the ref attribute. If you do so, the submit control will only be displayed if the node it is bound to is relevant. This way you can define in the XForms model rules that specify when a submit control is to be displayed.

2. Standard Representation of Binary and Text Documents

In OPS XPL and pipelines only deal with XML documents. In order to handle non-XML data such as binary and text documents in pipelines, OPS defines two standard XML document formats to embed binary and text documents within an XML infoset. This solution has the benefit of keeping XPL simple by limiting it to pure XML infosets, while allowing XPL to conveniently manipulate any binary and text document.

These document formats are widely used by processors such as the URL generator, the HTTP serializer, the Email processor, and converters.

3. Improved Request Body and Uploaded Files Support

It was possible in the past with the Request generator to obtain the request body, which was automatically parsed as XML. This behavior has now been changed. It is instead possible to obtain the request body as xs:anyURI or xs:base64Binary (standard binary document format). Parsing may then be done using the URL generator. In addition, the body can now be read several times. This change brings consistency with the handling of uploaded files, and the support for binary files thoughout OPS.

In a related change, the Request generator now supports specifying whether uploaded files or the request body must be generated as xs:anyURI or xs:base64Binary.

4. URL Generator

4.1. Binary Mode

The URL generator now supports streaming binary files encoded with Base64. The XForms Upload example, among others, illustrates this capability.

4.2. Text Mode

The URL generator now supports reading text files. The Employees example illustrates this capability.

4.3. XML Content Type

The URL generator now correctly detects as XML the following content types:

  • application/xml, the recommended content type for XML
  • text/xml, the now deprecated content type for XML
  • content types ending with +xml such as image/svg+xml

5. Serializers

5.1. New Serializer Architecture

The pre-2.6 serializer architecture did not clearly separate the following concerns:

  • Conversion of XML documents to a character or byte stream.
  • Sending a character or text stream to a particular destination, such as a web browser through HTTP, or a file on disk.

The new architecture introduces converters in charge of the first task, and plain serializers in charge of the second task. It relies on the standard representation for binary and texts documents.

Backward compatibility for existing serializers is kept, but it is recommended to use the new converters and serializers whenever possible.

5.2. HTTP Serializer

A new serializer, the HTTP serializer, supports decoding of binary or text data, and sending the resulting stream to an HTTP client. The XForms Upload example illustrates this capability. The HTTP serializer can be used for example in conjunction with converters and the URL generator.

The HTTP serializer uses the recommended application/xml content type by default rather than text/xml.

5.3. New Configuration Parameters

The omit-xml-declaration and standalone configuration parameters of the XML converter are now documented. The cache-control/use-local-cache configuration parameter of the HTTP serializer is now documented.

6. Examples

6.1. BizDoc Application Changes

The data access layer of the BizDoc application has been refactored to support the following backends:

  • XML databases: XML documents are accessed through the XML:DB processors. Currently, the backend assumes the built-in open source eXist database.
  • SQL databases: XML documents are accessed as a text or native XML format.

It is now possible to visualize each document as XML from the user interface.

6.2. New "Employees" Example

The new Employees example application illustrates the following aspects of OPS:

  • CRUD operations, paging and sorting with a SQL backend
  • XForms controls and validation with XML Schema
  • XForms upload control
  • Reading plain text files
  • Using the Java processor
  • Exporting Comma-Separated Values (CSV) files
  • Exporting and importing Excel files
  • Calling and implementing Web Service
  • Authentication (login / logout) and roles
  • LDAP access

7. Page Flow

XSLT views in Page Flow can now access the XForms instance using document('input:instance') or doc('input:instance'). In the past, it was often necessary for the model to aggregate its output with the XForms instance to make both documents accessible from the view.

8. Email Processor

The Email processor features the following improvements:

  • Multipart hierarchy: it is possible to have multiple levels of multipart messages.
  • Binary attachments: binary files such as images and PDF files can be attached to an email.
  • Dynamic attachments: attachments can be generated dynamically. It is for example possible to attach a dynamically generated chart or PDF file.
  • Character encoding: character encoding can be specified for text content.

In addition, property naming has been revisted. The test-smtp-host and test-to replace the deprecated host and forceto properties.

9. Custom Processors

There is a new facility to declare custom processors that does not involve modifying the original processors.xml file. To do this, create a file called oxf:/config/custom-processors.xml. Its format is the same as the original processors.xml.

The Processor API has been enhanced to provide access to the inputs and outputs actually connected (as opposed to just those that have been declared). This provides access to optional inputs and outputs. Please refer to the Javadoc for the Processor class for more information, as well as the ListInputs unit test.

10. WebDAV Resource Manager

A WebDAV resource manager is now included. It supports basic authentication.

11. J2SE 5.0 Support

The source code of OPS now compiles with Java 5.