Wednesday, July 25, 2012

Keeping Form Builder light

In Orbeon Forms 3.9, Form Builder had for each control label:

  1. A read-only version of the label, shown most of the time.
  2. An HTML input, shown when editing the label.

Both hold the same value, and only one is shown at a given point in time. But do we really need to have a different input field for every label? After all, you can only edit one label at a time, can’t you? So why not have just one input, and re-use it to edit all the labels in the form?

This is exactly what we did for Orbeon Forms 4.0. We did this for control labels, control hints, and section labels. As a result, the HTML for Form Builder is “lighter”; it contains less elements, which creates less work for the browser, and thus provides a snappier experience for form authors.

Monday, July 23, 2012

Orbeon Forms 4.0 M8

Today we released Orbeon Forms 4.0 M8 (Milestone 8). Like 4.0 M7 and the previous milestones this is not a final release.

We have addressed the following issues in this build:
  • Form Runner
    • Send email: support TLS and custom port (#395)
    • New L&F: editor for title and description in Form Settings (#376)
    • fr:number doesn't show nicely in review mode (#316)
    • Silent fr:autocomplete JS error on Review page (#389)
    • Silent fr:button JS error on Review page (#390)
    • XForms inspector: navigating from FR review to edit page causes JS exception (#137)
    • TinyMCE content doesn't show in PDF (#300)
    • Modernize XBL of fr:dropdown-date/fr:fields-date/fr:autocomplete
    • A few more small improvements to the phone number control (see our post on the main improvements)
  • XForms engine
    • Don't produce duplicate templates ids (#374)
  • Other
    • File serializer: support of oxf: and file: URLs
    • File processor: move operation, support both filesystem paths and oxf: and file: URLs for move and delete
There are a bunch of changes we are working on a separate branch, related to the improved look and feel. This is taking a while because we are also using the opportunity to improve how Form Builder handles editing controls, grids and sections attributes.

More information is available in the in-progress release notes for 4.0.

You can download the builds using these links:
Don't forget to grab a trial license for the PE version.

Please send feedback preferably to the ops-users list or via twitter (if short!), or feel free to comment on this blog entry if appropriate.

Wednesday, July 18, 2012

Designing a great phone number field

For a long time now we've had a US phone number field in Orbeon Forms which looks like this:
While fixing a validation highlighting issue for 4.0, we spent some time cleaning-up that control, and along the way thought about how to improve it. We thought about the following:
  1. Should we use two fields as is the case now, or a single field?
  2. What characters should the user be allowed to enter?
  3. How do you store and format the value?
Let's consider the number of fields. When using two fields, you have to think about what happens after the user has typed the area code. With a naive implementation, you have to tab (or click) to get to the other field. In the worst case scenario, if the user enters the value head down, she might end up typing too many characters in the first field, as shown here. You could configure the field to prevent entering more than 3 characters, but then the user might type the whole number and realize most of the typing got lost, so that's not a great solution either.

Or, you can could automatically jump from the first field to the second one. This is tricky too, and there are lots of botched implementations of that idea out there. For example, if the jump occurs after the user has typed the 3rd number and wants to edit the area code, she has to shift-tab or click. And it is probably safe to assume that some users know "tab", but fewer know "shift-tab"! You could be smarter and jump to the second field only when the user types the 4th character. That would be much better, but that still requires shift-tab or a click to navigate to the area code.

So it's hard to get the two-field solution right. This is not to say that there is no benefit to it. For example it makes it very clear that you need an area code. But you can do this using a placeholder in a single field, so for now we have decided to revise this component and to use a single field with a placeholder to indicate the format:
Now what values should the user be allowed to enter? You find countless examples online of indications along the lines of "Please enter the phone number (without dashes or spaces)". Uh, no: if the computer can do the work, the user shouldn't! So don't tell the user that some characters should not be entered, when it's likely that the user will enter them. For a phone number, you do want to allow at least spaces, dashes, parentheses, slashes, and periods. There might be more but these are the most common. Let the user go wild and format the number as she is used to!
What about really unexpected characters, like letters, or a dollar sign? For now, we have decided to leave them in because it seems it's more likely that such characters were mistakes on the user's part. So those will trigger a validation error.

Finally, when the user leaves the field, you could do two things: leave the value as is, or format it. We think it's better to format it: first, your form data will look consistent this way. Second, if formatting is separate, you can store into the format a canonical value. For example, we store a plain string of 10 digits. So we do this:
  • remove known extra characters
  • if the resulting string contains only digits, store them and reformat the value
  • otherwise leave the string alone so the user can fix it
And one cool aspect is that this is easy to implement using the Orbeon Forms component system and the format/unformat capability of input fields. The entire source of the component can be seen here (and keep in mind that most of the code is the metadata needed for Form Builder, not the actual runtime control!).

Let us know what you think: is this a phone number field that you can see yourself use? Did we miss anything? What other formats would you like to see (international phone number, other countries)?

Monday, July 16, 2012

Orbeon Forms 4.0 M7

Today we released Orbeon Forms 4.0 M7 (Milestone 7). Like 4.0 M6 and the previous milestones this is not a final release.

We have addressed quite a number of issues in this build, in particular:
  • Form Builder
    • Delete grid row with confirmation doesn't work anymore (#362)
    • Static image doesn't support hint so label is misaligned in repeat (#254)
    • Make Box Selector default for Multi List Box control (#170)
    • Better names for several controls in the toolbox
    • Removed some rarely used controls from the toolbox
  • Form Runner
    • box-select doesn't show nicely in review mode (#317)
    • Summary page search options show English only (#370)
    • workflow-send does not send the app/form name (#232)
    • fr:us-phone control doesn't show its alert when tabbing out of second field (#208)
    • Improvements to fr:us-phone component
  • XForms engine
    • Don't dispatch xforms-value-changed on group and switch
    • xforms:item/xforms:choices: ref and context attributes are ignored (#382)
  • Other
    • Orbeon Forms doesn't deploy on JBoss 7 (#146)
More information is available in the in-progress release notes for 4.0.

You can download the builds using these links:
Don't forget to grab a trial license for the PE version.

Please send feedback preferably to the ops-users list or via twitter (if short!), or feel free to comment on this blog entry if appropriate.

Thursday, July 12, 2012

A finite state machine to the rescue

On this blog, we often mention new features we recently implemented in Orbeon Forms, but rarely discuss how they have been implemented. Today, let’s make an exception, and come back to a feature discussed a couple of weeks ago: Form Builder’s new UI to edit labels and hints.

UI programming often consists in doing something in reaction to some event (event → action). For instance: in Form Builder, when the mouse pointer enters a cell, show the icons to edit the control in that cell. Sometimes, you only want to take the action if a condition is met (event, if condition → action). Yet, in other cases, the action to be performed depends on a state, for instance: if form authors click somewhere on the page, and the label is in the edit state, switch it to read-only mode. Putting all this together, for the case of editing the labels and hints, you get the situation in this diagram:

FSM diagram
FSM diagram

Now, that is hairy, isn’t it? (And this diagram only shows states, events, and conditions, but not the actions to be performed.) Having this logic spread throughout your code makes things hard to maintain (read: impossible to maintain!). Luckily, the concept of finite state machine (FSM) comes to the rescue. A FSM allows us to break our code into the following parts:

  1. A description of the transitions shown in the above diagram, what conditions need to be met for a transition to happen, from which and to which state it goes, and what actions need to run when that transition is made.
  2. The implementation of the events, conditions, and actions referred to in #1.
  3. A generic FSM “engine”, which take the transitions, events, conditions, and actions from #1 and #2 and runs them.

Last month, we develped a new FSM engine and used it to implement Form Builder’s new UI to edit labels and hints, and since then, we already started using that engine to implement other Form Builder features.

Monday, July 9, 2012

Orbeon Forms 4.0 M6

Today we released Orbeon Forms 4.0 M6 (Milestone 6). Like 4.0 M5 and the previous milestones this is not a final release.

We have addressed quite a number of issues in this build, in particular:
  • Form Builder
    • FB: Dirty/validation don't work anymore (#114)
    • FB: Form dirty just after publish (#116)
    • Expand cell over existing control doesn't expand after confirmation (#191)
    • Default value XPath error shows error dialog in dev mode (#337)
    • xxf:dynamic NPE with update of XBL with models (#360)
  • Form Runner
    • Noscript: character encoding when switching pages (#49)
    • Unauthorized when trying to use import feature (#173)
    • Error in persistence layer is not propagated to the UI (#140)
    • Error page still shows after correcting persistence layer error (#356)
    • Don't redirect to /edit if there was an error saving
    • Don't load source form unnecessarily (827760e524)
  • XForms engine
    • Fix NPE upon error in 2-pass submissions (ea9429cd83)
  • Other
    • PFC: Add unauthorized-handler support
    • SQL Processor: NPE in ValueOfCopyOfInterpreter (#349)
    • SQL Processor: exception when writing xs:base64Binary with sql-type="blob" (#350)
In short things are coming along and being more and more polished. Under the hood this build also includes quite a bit of refactoring.

We have decided to temporarily disable the Form Builder Custom XML feature in this build. We might push this to after the 4.0 release for reasons of schedule.

More information is available in the in-progress release notes for 4.0.

You can download the builds using these links:
Don't forget to grab a trial license for the PE version.

Please send feedback preferably to the ops-users list or via twitter (if short!), or feel free to comment on this blog entry if appropriate.

Keeping code alive

There is a great bit by Joel Spolsky dating back to year 2000:
Old code has been used. It has been tested. Lots of bugs have been found, and they've been fixed. There's nothing wrong with it. It doesn't acquire bugs just by sitting around on your hard drive.
Joel also recognizes three types of issues with old code (architectural problems, inefficiency, ugliness), which he recommends be addressed without fully rewriting your software by refactoring, optimizing, and prettifying.

At Orbeon, as we are working very hard on releasing Orbeon Forms 4.0, we have taken an approach of careful migration and refactoring. When we need to do more than trivial changes to old JavaScript or Java, we often start by moving some of that code to CoffeeScript or Scala, respectively. This has lots of benefits:
  • Low risk. It's not a rewrite from scratch. (In the case of Java to Scala we even get help from tools to perform an initial migration.)
  • Revisited code. In the process, we re-read the code and are forced to understand it again. Sometimes we add new comments to unclear code, or even fix obvious mistakes.
  • Smaller, more expressive code. We are moving to better languages after all.
  • Future proofing. This sets things up for more refactoring in the future. (In fact, we often perform some refactoring right away.)
Little of this would be possible without a stack of great, modern technologies which includes ScalaCoffeeScriptLESS, and jQuery, none of which existed back when we started working on Orbeon Forms. We consider ourselves lucky to have them!

Monday, July 2, 2012

Orbeon Forms 4.0 M5

Today we released Orbeon Forms 4.0 M5 (Milestone 5). Like 4.0 M4 and the previous milestones this is not a final release.

In this build we have implemented the following improvements:
  • Invalid controls in Form Builder do not prevent saving and publishing the form (#341).
  • Orbeon Forms outputs the HTML 5 doctype by default (#306).
  • The language selection logic in Form Runner is rewritten and allows configuring which of the languages present in a form must be visible (#166, #117).
  • We fixed an error in Form Builder when inserting a specific XBL control (#322).
  • The $fr-roles variable works again (#328).
  • fr:tabview events have been fixed (#329).
  • We removed unwanted messages in the logs about missing instances (#174).
  • The Page Flow Controller (PFC) has been partially rewritten to address the following:
    • It now displays the configured error page in more relevant cases, including when accessing a non-existing Form Runner form (#150).
    • Some elements and attributes now have more meaningful names, and the older names are deprecated.
    • It supports an error handler in the PFC itself (instead of the web application level).
    • It serves resources directly, so serving CSS, JavaScript and images should be faster.
We have also removed support for some old bits and pieces which were getting in the way:
  • XForms: the "nospan" HTML mode.
  • XPL: the uri and encapsulation attributes.
  • PFC: custom matchers ("glob" and regular expressions are now built-in).
  • Core: the Apache Jakarta ORO library (we use Java regular expressions everywhere).
  • XUpdate support.
Work on the look and feel is still in progress but not yet committed. Stay tuned for this!

More information is available in the in-progress release notes for 4.0.

You can download the builds using these links:
Don't forget to grab a trial license for the PE version.

Please send feedback preferably to the ops-users list or via twitter (if short!), or feel free to comment on this blog entry if appropriate.