Orbeon Forms User Guide

Changes in Version 2.7

1. JBoss Support

JBoss is now supported. See the installation instruction for more information on how to setup OPS on JBoss.

2. XForms

2.1. Compliance Matrix

In line with our commitment to fully support the XForms specification, we now clearly document the level of support for each part of the specification in a compliance matrix.

2.2. Open Selection

The <xforms:select> and <xforms:select1 controls let the end-user select on of more items from a list. You can now add the selection="open" attribute on those controls; when specified, the end-user can enter a value of its choice in text field, of choose one of more of the suggested values.

2.3. Linking Attribute

You can now use the src attribute on <xforms:label>, <xforms:hint>, <xforms:help>, <xforms:alert>, and <xforms:message> to specify the URL from where the text should be loaded, instead of having the text inline in the XForms view or in the XForms instance (ref or bind attribute).

2.4. Single-Node and Node-Set Binding Attributes

In your XForms views, in addition of using the ref and nodeset attributes to reference nodes of the XForms instance, you can now use the bind attribute. You first assign an id to a nodeset in the XForms model: e.g. <xforms:bind nodeset="/company/ceo" id="ceo"/>; you then reference this id in your XForms view: e.g. <xforms:input bind="ceo"/>.

2.5. Nested Bind

You can now nest <xforms:bind> elements in the XForms model. The nodeset XPath expression in nested elements is relative to the nodeset selected by the nodeset expression on the parent element.

2.6. doc() in Model Item Properties

You can now use the XPath 2.0 doc() function in XPath expressions in the XForms model. For instance, assuming that you have a "lookup table" defined in an XML file mapping department id to department name, you can write a model item property calculating the value of <department-name> element based on the value entered by the user for <department-id>:

<xforms:bind nodeset="/instance/department-name" calculate="doc('oxf:/departments.xml')/departments/department[@id = /instance/department-id]/name"/>

2.7. Short Form Element Names

In this version the names generated by OPS for HTML form elements are much shorter than in previous versions. Under certain circumstances (low bandwidth between server and end-user, large forms, complex XForms instances with many levels of nested elements using namespaces), submitting a form was slow as a lot of data had to be sent from the browser back to the server. A new name generation scheme has been implemented in this version. It solves the problem and guaranties that names will be short even if your XForms instance has many levels of nested elements and is using namespaces.

2.8. Handling of Prefixes and Namespace Declarations

In previous versions of OPS, when a form was submitted and the XForms instance recreated, all the elements and attribute where in the right namespace, but the actual prefix was not necessarily kept and namespace declarations where inserted only where used. In this version, Presentation Server keeps the exact value of the prefixes and the location of namespace declaration when a form is submitted and the XForms instance is recreated.

2.9. xxforms:hidden Extension Control

The XForms extension control xxforms:hidden is supported again and documented.

2.10. Semantic of XForms Conditionals

The <xxforms:choose> used to run all the "true" <xxforms:when>. Instead, it now only run the first one if any, and the <xxforms:otherwise> otherwise. This is inline with the behavior of the <xsl:choose>.

2.11. <xforms:message>

<xforms:message> is now supported. This lets you display a message in a dialog when a submit control is clicked. See the message action documentation for more details.

3. XPath 2.0 Support

Using XPath 2.0 expressions is now supported in:

  • XPL: for XPointer expressions, test expressions in a <p:when>, and select expressions in a <p:for-each>.
  • Page Flow: for when expressions in <action> and <result>.
  • XForms: binding expressions in the XForms view (ref and nodeset attribute), XPath expressions in model item properties (<xforms:bind>), and XPath expressions in XForms actions.

4. User-Defined Processor Inputs

User-defined processor inputs, used by several processors including the XSLT processor and the Email processor, are now documented (XPL documentation, XSLT documentation). The URI schemes to access user-defined inputs and outputs are now input: and output:, to avoid confusion with the oxf: scheme used for the OPS resource manager sandbox.

5. eXist Native XML Database

OPS ships with the latest stable version of eXist (eXist-1.0b2-build-1107). This fixes the issue of connecting to an external eXist instance. Here is an example datasource.xml to connect to a standalone eXist:

<datasource><!-- Specify the driver for the eXist database --><driver-class-name>org.exist.xmldb.DatabaseImpl</driver-class-name><!-- Example of URL for a non-embedded use --><uri>xmldb:exist://localhost:8080/exist/xmlrpc</uri></datasource>

6. Examples Setup

All the examples using the SQL processor now work out of the box without configuring datasources at the application server or servlet container level. This includes the following examples:

  • Address Book
  • Employees
  • Data in multiple formats
  • XForms Upload
  • Email

7. Saxon Upgraded to Version 8.1.1

Saxon is the default XSLT engine and is used throughout OPS for XPath 2.0 expressions. Saxon 8.1.1 is now bundled with OPS. See the changes section of the Saxon documentation for more details.

8. Documentation Printing

Printing the documentation has been improved through the use of CSS. As you print a given section of the documentation the left sidebar showing the chapters will not be printed.

9. Processors

9.1. SQL Processor

  • The SQL processor now supports external datasource definitions using the optional datasource input. Those directly refer to connections without using JNDI names mapped by the container. This allows examples to work out of the box. This is an example of datasource definition:

    <datasource><!-- Specify the driver for the database --><driver-class-name>org.hsqldb.jdbcDriver</driver-class-name><!-- This causes the use of the embedded database --><uri>jdbc:hsqldb:file:orbeondb</uri><!-- Optional username and password --><username>sa</username><password/></datasource>
  • OPS ships with a recent version of HSQLDB (version 1.7.2.8).

  • The SQL processor now supports reading BINARY, VARBINARY and LONGVARBINARY columns in addition to BLOB.

  • The SQL processor's data input and output are now optional. This removes the need for "dummy" input content or Null serializers with the SQL processor.

9.2. URL generator

9.2.1. Relative URLs

The URL generator now supports URLs relative to the location where the generator is used, instead of just absolute URLs.

9.2.2. XInclude Dependencies

The URL generator also deals correctly with XInclude dependencies. For example, if a file called file1.xml includes a file called file2.xml, which in turn includes a file called file3.xml, and you modify file3.xml, then file1.xml is re-read automatically. Of course, this works with other dependency scenarios as well!

9.3. Java Processor

The Java processor now works correctly in command line mode. It also supports relative source paths and supports specifying alternate compilers.

9.4. Email Processor

The Email processor now supports Cc and Bcc recipients. See the Email example for an illustration.

9.5. Scope Generator

The Scope generator is now able to marshall regular JavaBeans in addition to XML stored as Strings, W3C and dom4j documents. This functionality deprecates the Bean generator. These two processors previously had some overlap in functionality.

9.6. Error Processor

The error processor now follows the same configuration mechanism as the main processor. The following property names have been deprecated:

  • oxf.servlet.error.processor.uri
  • oxf.servlet.error.input.*

The new names are as follows:

  • oxf.error-processor.name
  • oxf.error-processor.input.*

Visit Packaging and Deployment for more information on configuring the error processor, as well as Error Pipeline for information about creating an error pipeline.

10. Command Line Interface

The command to invoke is now:

java -jar cli-orbeon.jar ...

instead of:

java -jar orbeon.jar ...