Monday, April 29, 2013

HTML labels and hints in Form Builder

Since Orbeon Forms 4.1, released two weeks ago, the labels and hints for forms you create in Form Builder can be more than just plain text: you can now use HTML in your labels and hints, right from Form Builder. For instance, this allows you to add formatting, as in the example below, where part of the label is in italic, or to add a link to a page with additional information about that field.

By default, labels and hints are just plain text, as this is the most common scenario, and you wouldn't want a less-than sign (<) to be interpreted as the start of an HTML tag. To avoid this, you explicitly enable the HTML mode with a checkbox, which in Form Builder is shown next to labels and hints.

Thursday, April 18, 2013

Orbeon Forms 4.1

Today we released Orbeon Forms 4.1, which introduces a few new features since 4.0.1:

  • Form Builder
  • Form Runner
    • Proxy portlet: ability to configure forwarding of headers and parameters (#886)
    • Ability to create new Form Runner resources via properties (#919)

In addition, the following fixes and enhancements have been implemented since 4.0.1:

  • Form Builder
    • Edit Source must not send data to server incrementally (#848)
    • Incorrect section template update in builder (#633)
    • Show label editor when adding new control (#909)
    • No yellow background when hovering label (#767)
    • Can edit labels within section templates (#902)
    • Use smaller font for hint editor (#914)
    • Label editor: label disappears (#915)
    • Icons to edit repeated grid show when the grid is within a section template (#781)
    • FB grid icons linger in wrong position when resizing window (#602)
    • Form Builder title is empty (#714)
    • Section title editor appears over section help icon (#636)
    • Show "click here to enter/add a label/hint" when label or hint is empty (#901)
    • For first label edited, the text field shows too high (#931)
    • Have placeholder on input for label/hint so form authors know what the field is for (#930)
    • Database service information lost (#934)
  • Form Runner
    • Improve eXist search performance (#921)
    • Full text search not returning anything with eXist 2 (#922)
    • Data in collapsed section is not validated (#927)
    • User with create permission see PDF and review buttons but gets a 403 (#935)
    • Undeclared variable in XPath expression: $form-resources (#932)
    • Empty buttons showing the second time the Form Submitted dialog shows (#939)
  • XForms engine
    • Use a single property for input/textarea string replacement (#867)
    • Non-relevant group around <li> with AVT doesn't place xforms-disabled (#889)
    • REGRESSION: Uploading large files causing "Got unexpected request sequence number" error (#894)
    • xf:case: xforms-case-selected/deselected are not placed on first delimiter (#893)
    • Fix basepath of TinyMCE (#896)
  • Other
    • First automated client-side test using ScalaTest Selenium DSL
    • Upgrade to Scala 2.10.1
    • PE license: check build date against subscription end when it make sense
    • Add Saxon numberer for Spanish

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.

We hope you enjoy this release!

Please send feedback:

Wednesday, April 17, 2013

More powerful buttons

Photo by Keoni Cabral

Up to version 4.1, Orbeon Forms had a few configurable buttons to specify what happens with form data:

  • The “Save” button saves data to the database.
  • The “Submit” button saves data and shows a dialog after saving (with options to clear data, keep data, navigate to another page, or close the window).
  • The “Send” (AKA “workflow-send”) button saves the data and then allows:
    • sending an email
    • sending form data to a service
    • redirecting the user to a success or error page

The reason these specific buttons came to be is mostly historical: as more functionality was needed over time, more buttons were added with properties to configure them. The distinction between “Submit” and “Send” in particular is arbitrary!

Since recently we’ve been asked for more options, we used the opportunity to implement a much more flexible system.

First, let’s start by saying that we don’t want to implement a full-fledged workflow engine: that’s something other products do better than Orbeon Forms. Instead the idea is to be able to specify very simple sequential processes to execute when the user presses a button.

We started with specifying a list of reusable actions:

  • validate: validate form data
  • save: save data via the persistence layer
  • success-message: show a success message
  • error-message: show an error message
  • pdf: create a PDF file from the data
  • email: send an email
  • send: send the data to an HTTP service
  • review, edit, summary: navigate to these Form Runner pages
  • navigate: navigate to an external page
  • visit-all: mark all controls as visited
  • unvisit-all: mark all controls as not visited
  • expand-all: expand all sections
  • collapse-all: collapse all sections
  • result-dialog: show the result dialog
  • captcha: trigger the captcha
  • success: complete the process
  • process: run a sub-process

Then we needed to:

  • specify which of these actions to run and in which order
  • decide what to do when they succeed or fail
  • decide how to associate them with buttons

We came up with a very simple syntax which you place in configuration properties. For example, the good old “Save” button is specified this way:

require-valid
then save
then success-message("save-success")
recover error-message("database-error")

Notice that there are action names, like save and success-message (require-valid itself is a sub-process which runs a number of steps and stops processing if the data is not valid), and two different combinators, then and recover. When an action succeeds, then is used to specify what is the following action. When an action fails, recover can be used to specify what action to do in that case.

So in the example above what you want to say is the following: start by validating the data, then in case of success save the data, and then if that’s successful show a success message. If saving has failed, then show an error message.

A process which just saves the data without checking validity and shows success and error messages looks like this:

save
then success-message("save-draft-success")
recover error-message("database-error")

Validating and sending data to a service looks like this:

require-valid
then send("oxf.fr.detail.send.success")

Some actions can take parameters. In the example above we point to properties to configure the send action. This means that, within a single process, you can have any number of send actions which send data to various services. This also allows you to have separate buttons to send data to different services. These two scenarios were not possible before.

We are keeping but deprecating these buttons:

  • save (which uses a property to determine whether to validate or not)
  • submit
  • workflow-send

And we introduce new buttons with predefined behavior:

  • save-final: validate and save to the db
  • save-draft: save to the db without validating
  • send: validate and send to a service

In fact all buttons can do the same tasks if they are configured appropriately! But by default the buttons above are preconfigured to do different tasks, for convenience.

So how do you can figure things? Say you want to specify a couple of buttons on your “acme/hr” form. Like before, you define a property:

<property
  as="xs:string"
  name="oxf.fr.detail.buttons.acme.hr"
  value="save-draft send"/>

This places “Save” and “Send” buttons on the page. Each button is automatically associated with processes of the same names (save-draft and send). These particular buttons and process names are standard, but we can override them specifically for our form. Again, this is done with a property:

<property
  as="xs:string"
  name="oxf.fr.detail.process.send.acme.hr"
  value='require-valid
         then pdf
         then email
         then send("http://example.org/")
         then navigate("/success")
         recover navigate("/failure")'/>

Button labels can be overridden as well, as was the case before:

<property
  as="xs:string"
  name="oxf.fr.resource.*.*.en.detail.buttons.send"
  value="Fancy Send"/>

All the configuration above for a button called send could have been done with an entirely custom button named foo.

We hope this shows a little bit what’s now possible! This feature will be available in Orbeon Forms 4.2.

Tuesday, April 9, 2013

Making a distinction between the "read" and "update" permissions

Since Orbeon Forms 4.0, Form Builder provides a UI allowing form authors to define who can do what on the forms they create, once they are published. For each role, form authors can define which function users can perform. The functions are create, read, update, and delete (CRUD). In 4.0, read and update where grouped together; i.e. users with a given role where either allowed to both read and update, or were not allowed to do either. We now separated read and update to make this more granular, for instance allowing form authors to say that a given role can read the data but not update it, as is the case for the clerk role in the screenshot below.

This feature will be in the upcoming 4.1 release, and you can already try it today in the 4.1 M1 milestone build.

Thursday, April 4, 2013

Let Charles help you monitor HTTP requests


You often need to monitor HTTP requests, be it from your browser to the server, or from the server to backend services. You can setup Orbeon Forms to log the body of Ajax requests and responses, as well as the body of requests and responses Orbeon Forms makes to backend services. All that information goes into a log file, in which it is sometimes hard to quickly find what you're looking for, and a software specifically designed to help you monitor HTTP requests can often show this information in a better way.

For this, until recently, I've been recommending (and myself using) the OS X app HTTP Scoop. If not on OS X, I pointed folks to WireShark, which is extremely powerful, but also rather hard to use. I recently discovered Charles, have been using it full time for the last week, and now wholeheartedly recommend it. It is simple to use, like HTTP Scoop, but runs on Windows and Linux, and provides lots of additional features. You can download a 30-day trial, and it costs $50 after that.

Unlike HTTP Scoop or WireShark, Charles works as a proxy; this means that apps need to be configured to go through that proxy instead of connecting directly to the server. On OS X and Windows, Charles registers itself as a proxy with the system, and so requests from browsers that honor that system configuration will automatically go through Charles, which is the case with Chrome, Safari, and IE. Firefox doesn't use the proxy setup done at the system level, but Charles comes with a Firefox add-on which makes this setup for you.

Next, so Charles can also intercept HTTP requests made by Orbeon Forms, typically to backend services, you'll want to add the following two properties to your properties-local.xml.
<property as="xs:string"  name="oxf.http.internal-paths"  value=""/>
<property as="xs:string"  name="oxf.http.forward-cookies" value="JSESSIONID"/>
<property as="xs:string"  name="oxf.http.proxy.host"      value="localhost"/>
<property as="xs:integer" name="oxf.http.proxy.port"      value="8888"/>
As a side-note, Charles is developed by Karl von Randow, who also develops Camera+, my favorite iPhone app, which I pitched to many people as what Apple's built-in Camera app should have been.