Thursday, March 27, 2014

Review and PDF improvements

With Orbeon Forms 4.5, we are introducing several improvements to the Review mode and the PDF output.

Selection controls

We used to output all selection controls like this:

  • Single selection: output the selected item’s label.
  • Multiple selection: output all selected items’ labels with separators.
  • Boolean input: output “true” or “false”.

But this was not ideal for checkboxes and radio buttons. In these cases, you probably want all options visible in your review or PDF as well. Also, this opens the door to amending printed forms by checking options by hand.

The boolean input was worse, because nobody really wants to see “true” or “false” printed!

So here is how things look like in 4.5:

Review mode
Review mode
PDF output
PDF output

You notice that both checkboxes and radio buttons appear as boxes. That’s because on paper forms, unlike web UIs, there is more often than not no distinction between the two: you just check the boxes that apply, and explanatory text clarifies whether multiple choices are allowed. So for now we have decided on a unified appearance for both.

Highlighting of fields

We now also better highlight fields, for two reasons:

  • It was not always clear where a control’s label stopped and a control’s value started.
  • There is a use case for blank fields to be filled later on paper, in which case the field’s area must be clearly indicated.

This applies not only to input fields, but also to other types of controls which take more of a “field” appearance in review mode and PDF, such as date pickers and dropdown menus.

Highlighting of control fields
Highlighting of control fields

Page breaks before sections

Form Builder now has a built-in option to add a PDF page break before a section. One use case is forms that have a signature section, where there are legal requirements to make sure that certain fields stay together and on the same page.

Page Break Before option
Page Break Before option

Other improvements

Along the way, we also made the following improvements:

  • The “[Select…]” dropdown title no longer appears in Review mode and PDF files (see Fun with dropdown menu titles).
  • We place the form title in the header and the footer of the PDF, alongside page numbering.

With all this, the Review mode and PDF output are looking pretty good! These enhancements will be available in Orbeon Forms 4.5.

Monday, March 17, 2014

Storing configurations outside of the Orbeon Forms war file

Rationale

If you're reading this, you're most likely already familiar with the properties-local.xml file used to configure Orbeon Forms. This file typically goes inside the Orbeon Forms web app, in WEB-INF/resources/config. What if you'd like to package a single war for Orbeon Forms, and deploy that war on multiple servers on which you need to have slightly different configurations? Is it possible to store this configuration outside of the war file? It is, and we'll see how you can do this in the remainder of this post.

Resource managers

The directory WEB-INF/resources, as its name implies, contains files called resources. Resources can be configuration files, XSLT stylesheets, or CSS/JavaScript assets served to the browser. Resources can be stored in a variety of locations, hence Orbeon Forms loading them through a resource manager. Several resource managers come out-of-the-box with Orbeon Forms, and you could even implement your own. The 3 most frequently used resource managers are:

  • The class loader resource manager loads files from the class path. Most of the built-in resources are stored in jar files that ship with Orbeon Forms, and are thus loaded with the ClassLoader resource manager.
  • The web app resource manager typically loads files from the web app's WEB-INF/resources.
  • The file system resource manager loads files from a directory on disk you specify.

Changing the web.xml

By default, Orbeon Forms first attempts to load resources with the class loader resource manager, and if that fails tries with the web app resource manager. But you can change this by adding context params in the Orbeon Forms web.xml. For instance, with the following two context params added, Orbeon Forms will first try to load resources from /etc/orbeon:

<context-param>
  <param-name>oxf.resources.priority.0</param-name>
  <param-value>
    org.orbeon.oxf.resources.FilesystemResourceManagerFactory
  </param-value>
</context-param>
<context-param>
  <param-name>
    oxf.resources.priority.0.oxf.resources.filesystem.sandbox-directory
  </param-name>
  <param-value>/etc/orbeon</param-value>
</context-param>

With this single change to the Orbeon Forms war, and the choice of a "standard" directory in which you'll place your configuration files, say /etc/orbeon, you can deploy the same war on multiple servers, and have different configurations in the /etc/orbeon of each server.

Changing Tomcat's configuration

Tomcat allows you to set the value of context parameters for an app in its own configuration, so you don't even have to change the web.xml. The following two lines added inside your Tomcat's <Context> element for the Orbeon Forms web app (e.g. in your server.xml) are equivalent to the change we did earlier to the web.xml.

<Parameter
 override="false"
 name="oxf.resources.priority.0"
 value="org.orbeon.oxf.resources.FilesystemResourceManagerFactory"/>
<Parameter
 override="false" 
 name="oxf.resources.priority.0.oxf.resources.filesystem.sandbox-directory"
 value="/etc/orbeon"/>

Wednesday, March 12, 2014

Choices editor improvements

Orbeon Forms 4.5 introduces two features related to repeated content, discussed in other posts:

Work on these enhancements also benefits the Form Builder Choices editor [1], and you can now reorder choices and have control over where to insert new ones:

Reordering choices
Reordering choices

In addition, you can now easily switch between the form’s languages directly in the Choices editor, instead of having to close it, switch languages, and come back. This makes localization easier! [2]

These enhancements will be available in Orbeon Forms 4.5.


  1. Which allows you to edit the choices for dropdown menus, radio buttons, checkboxes, and other selection controls.  ↩

  2. This feature was available in Orbeon Forms 3.9 but had gotten lost on the way to 4.0!  ↩