Monday, April 7, 2014

Orbeon Forms 4.5

Today we released Orbeon Forms 4.5!

Major features

This release is rich in new features and enhancements:
  • IE11 support. Both Form Builder and deployed forms now work with with IE11.
  • Versioning of form definitions. Publishing a form definition doesn't overwrite the previously published form definition, but creates a new version of it. Orbeon Forms associates the version of the form definition used for creating and editing data. This is supported with relational databases (Oracle, MySQL, and DB2 at this time). (blog post)
  • Improved fields, checkboxes and radio buttons in preview and PDF. Automatic PDF output now shows all radio buttons and checkboxes, nicely highlights fields, supports optional page breaks before sections, and shows the form's title in the page's header and footer. (blog post)
  • Inserting and reordering of grid rows. Repeated grids now have the ability to reorder grid rows and to specify exactly where to insert a new row. (blog post)
  • Repeated sections. Form Builder and Form Runner now support repeated section content. This is very similar to repeating a group of grid rows, except that the entire content of a section can be repeated, including nested grids and subsections. (blog post)
  • Improved help messages appearance and positioning. Help messages have a fresher, more modern look, and are now more lightweight and better positioned. (blog post)
  • Hints for checkboxes and radio buttons. You can now associate hint messages with specific radio button or checkboxes. They appear as tooltips upon hover. (blog post)
  • Form definitions and form data duplication. The summary pages for both Form Builder and your own forms now can have a Duplicate button which allows you to duplicate form definitions (in Form Builder) and form data, including attachments. (blog post)
  • Improved dropdown menus. Dropdown menus are now a bit smarter! (blog post)
  • Improved Form Builder Choices editor. The Form Builder Choices editor allows you to reorder items and to directly localize labels and hints. (blog post)
  • Improved Form Builder variable resolution. We have fixed a long-standing issue which prevented the use of variables in repeated grids. (doc)
  • Detecting login pages in Ajax requests. Administrators can now tell Orbeon Forms which pages are login pages, to help with error recovery. (blog post)
  • This version features full Spanish localization, courtesy of Bruno Buzzi of AGESIC.
  • This version also features Swedish localization for Form Runner.
See Localizing Orbeon Forms for more details about supported languages.
Other bug-fixes and features

Including the major features and enhancements above, we closed over 110 issues since Orbeon Forms 4.4. We should mention these notable bug-fixes and features:
  • XForms 2.0 bind() function (#1423)
  • Service request or response cannot target control in subsection (#1465)
  • Support repeats in actions (#1105)
  • PDF: Option to output a page break before a section (#1556)
  • FB: UI to edit control, grid and section classes (#1555)
  • PDF: Ability to set form title in header and/or footer (#1558)
  • Processes: reusable confirmation dialog (#1570)
  • XML Schema xs:import doesn't support relative paths (#1340)
Current browser support
  • Form Builder (creating forms):
    • Chrome (latest versions, both in the stable and dev channels)
    • Firefox (latest released version and current Firefox ESR)
    • IE10 and IE11
    • Additional support for Form Runner (accessing form):
      • IE7 (deprecated), IE8, and IE9
      • Safari Mobile on iOS 6 and iOS 7
      • Chrome for Android (stable channel)
    Compatibility notes
    • Date picker. The Date Picker control has been removed from Form Builder. It was similar to the normal Date control, except the date was shown as text in the page, not in a text field. The Date Picker didn't have much of a benefit over the regular Date control, but had a big drawback: it wasn't usable on mobile devices, which expect a text field to enable the native date picker. Note that while the control isn't available in the Form Builder sidebar anymore, the underlying implementation is still there, so your existing forms that use a Date Picker can still be edited in Form Builder, and will still function properly. (#1364)
    • Datatable. The fr:datatable component, deprecated in 4.0, has been completely removed.
    • Deployment. Integrated deployment, consisting in combining your Java/JSP applications with Orbeon Forms within the same WAR, is now deprecated. We recommend using separate deployment instead.
    • Oracle flat view. The truncation of section/control column names has changed. If the section or control name is 14 characters or less, it is kept as is, and the other part is truncated if needed. A numerical suffix is used instead for those columns which would introduce duplicates. (doc)
    You can download the latest version of Orbeon Forms from the downloads page.
      Don't forget to grab a trial license for the PE version.

      Please send feedback:
      We hope you enjoy this release!

      Friday, April 4, 2014

      Configure the URL of your services in properties


      A few weeks ago, we've seen how you can store Orbeon Forms configurations, in particular the properties-local.xml, outside of the Orbeon Forms war file. We've seen how this allows you to have a single war you deploy on all your environments, and keep differences in configurations between these environments outside of the war file.

      This is all good for the Orbeon Forms configurations. Here we'll see that you can use the same mechanism to define custom properties to specify which on what server your services run, or to what server you want data to be posted on submission.

      The xxf:property() XPath function

      Say you have forms you created with Form Builder, those forms use services, and in the service URL you want a different host name depending on the environment you're in. But of course, you don't want to change the forms as you run them on different environments. You can do this by defining a property, say:

      <property as="xs:string"  

      Then, in Form Builder, in the HTTP Service Editor dialog, you refer to the value of the property with:


      Submission server

      When users submit a form, you can setup Orbeon Forms to POST the data captured by the form to one of your servers. You do this with the send action, e.g.:

      send(uri = "")

      However, if you'd like, you can also move the server URL to its own property:

      <property as="xs:anyURI"

      And refer to that property in the send action (note that there is .uri at the end of the value passed to send, as the parameter to send is only a prefix, to which send can add different suffixes; for more on this, see the send action):

      send(property = "com.example.send")

      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


      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:


      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.


      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!  ↩

      Tuesday, February 25, 2014

      Fun with dropdown menu titles

      As we were recently fixing a few issues with the Dropdown Menu control, we started thinking more seriously about the behavior of that control in Form Builder and Form Runner, and it turned out to be interesting!

      The questions revolve around the special item at the top of the list, which we call the dropdown title. It is present to encourage the user to make a selection. With Orbeon Forms 4.4 and earlier, we simply had a rather imperative “[Select…]” title.

      So what title should we show, and when? There are different possibilities. For example:

      • When the control value is optional, we could show a different title, because in that case we shouldn’t tell the user too imperatively to enter data.
      • We could leave a blank title in both required and optional cases.

      For now we have decided to show a message in both cases, as a little bit of additional hinting shouldn’t hurt. And to be polite, we say “please”:

      Encourage the user a bit
      Encourage the user a bit

      Here is how the dropdowns look when you open them:

      Required value
      Required value
      Optional value
      Optional value

      Now when a value is required and a choice is selected, you can argue that there is no point showing “Please select:” to the user anymore, as the user shouldn’t go back to a point where no value is selected. Here we could:

      • entirely remove the title
      • show a blank title

      What if you have selected a choice by mistake, and you want to go back to an empty choice to remember to make a selection at a later time? This argues in favor of leaving a blank title. But if an initial choice is provided, either by default or by loading values from a service, you probably shouldn’t be able to get to a situation where no choice is selected!

      So it’s subtle and there might not be a “one size fits all” solution. For now, we have elected to blank the title when a value is selected even in the required case:

      Blank title for required value
      Blank title for required value

      Of course, when the selection is optional, then it makes sense to have a blank title to deselect the choice.

      Allow deselection
      Allow deselection

      In addition, we have now internationalized the title, something we had apparently overlooked for a long time (of course, Form Builder has allowed you to internationalize choices since the beginning).


      We noticed that in review and PDF modes, we showed the good old “[Select…]” title in the absence of a selection, which was not very useful! It is better to show an empty field, which also allows users who print forms on paper to fill in a value:

      Filled optional value in review
      Filled optional value in review
      Empty optional value in review
      Empty optional value in review

      Finally, instead of being hardcoded this is now entirely implemented in a simple XBL component which is quite easy to adapt.

      These improvements will be available in Orbeon Forms 4.5.

      Thursday, February 20, 2014

      Form versioning

      What versioning does

      Form versioning is an important new feature in Orbeon Forms 4.5. In the past, Orbeon Forms was only keeping track of one form definition for every published form. This meant that if you republished a form, the previous form definition was overwritten. It also meant that when showing data, Orbeon Forms was always using the latest published version of the form definition. However, there were cases where this could lead to unexpected results, as fields might have been added or removed in the new form definition, which means that some values could either not be shown, or would be missing when using a newer version of the form definition.

      Starting with Orbeon Forms 4.5, publishing a form definition doesn't overwrite any previously published one, but creates a new version. Also, Orbeon Forms now keeps track of the version of the form definition that was used when creating data, so it can use the same version in the future when that piece of data is edited, viewed, printed, etc.

      This feature will be available in Orbeon Forms 4.5, and can be used with all the supported relational databases (Oracle, MySQL, and DB2). At this point, it isn't supported with the eXist database. For relational databases it uses columns that were already added in version 4.4, but were still unused at the time; so if you are upgrading from 4.4, the changes to the schema are relatively minor: there are none on DB2, and only minor changes for Oracle and MySQL.

      Data migration

      The idea of data migration is to automatically update data created with an older version of the form definition to match the format of a newer form definition. It's obviously not something that you always want to happen, but there are cases when migrating data makes sense. For now, Orbeon Forms 4.5 doesn't do any data migration: editing, viewing, printing, etc of saved data is always done using the same version of the form definition used when that data was initially created. However we do have ideas on how to migrate data, for the cases where this would be desirable, and it might be something future versions of Orbeon Forms might do.

      The summary page

      The summary page for a form only uses the latest version of the form definition. In particular, this means that there will be additional columns in the table only for fields you marked as show in summary in the last version of the form definition. (Similarly, the summary page will show search fields only for fields marked as show in search in the last version.) In some case, this behavior isn't optimal, as you might have fields marked as show in summary in the last version that didn't exist in earlier versions, and vice versa, fields that were marked as show in summary in earlier versions and that aren't in the last version. A row in the summary page for data created with such an older version will show an empty cell in the corresponding column in the former case, and no data, since there is no corresponding column, in the latter case. This is something that we're planning to improve.