Thursday, July 16, 2015

How Common Constraints Work

Form Builder allows you to configure several types of validations associated with form controls:

  • Required: whether the value can be empty or not.
  • Datatype: such as string, decimal, date, or time.
  • Formulas: custom formulas, expressed in XPath.

In Orbeon Forms 4.10, we are introducing the additional notion of common constraints. These are validations which are predefined by Form Builder and which you can just select with a dropdown menu.

There are currently two such constraints:

  • “Has Maximum Length”
  • “Has Minimum Length”

Where you could only choose “Formula” in addition to the preset “Required” and “Datatype” validations, you can now select one of the common constraints.

Choice of common constraints
Choice of common constraints

Each of these two common constraints takes a numeric parameter specifying respectively the maximum number of characters and the minimum number of characters allowed in the field.

Setting values for common constraints
Setting values for common constraints

These constraints are equivalent to the following formulas:

string-length(.) le 140
string-length(.) ge 10

But in fact, under the hood, we introduced two new custom validation functions to make things more palatable to Form Builder and the forms engine. With these formulas the constraints become:

xxf:max-length(140)
xxf:min-length(10)

In practice, as a user of Form Builder, you do not have to care about these functions and they remain hidden to you.

One benefit of using custom functions is that special properties can be set by them when they run. For example, if you set the maximum length of a field to 140 characters, a max-length property becomes associated with that field. The new “Character Counter” appearance for example has access to that property and is able to show the number of characters remaining or the number of characters over the limit.

The character counter uses the max-length property
The character counter uses the max-length property

Now that we have a solid foundation, we hope to introduce many more useful custom constraints in the future. And in fact we have already come up with a pretty good list of such constraints. You can see some of them in this RFE.

We hope that you like this new feature!

Wednesday, June 10, 2015

How the new Form Builder Appearance Selector Works

Recently, a customer asked us to implement a feature which looked simple at first: adding a character counter to input fields, text areas, and rich text controls (think a Tweet or an instant message which must fit in an SMS, for example). It looks like this:

Input Field with Character Counter
Input Field with Character Counter

We could have gone the easy way:

  • write 3 new custom controls,
  • add them to the Form Builder toolbox,
  • and done!

This would be easy enough to do with Orbeon Forms custom controls, but it is not an ideal solution. Instead we would like:

  • the “character counter” function to be independent from the control to which it applies (input field, text area, or rich text control),
  • and the ability to switch back and forth, in Form Builder, between a control with and one without the character counter.

Going down to the markup level (that is, how the form definition is specified), an input field looks like:

<xf:input bind="message-bind"/>

What we want to do to add the character counter is add an appearance attribute, like this:

<xf:input
    bind="message-bind"
    appearance="character-counter"/>

The appearance attribute is a standard XForms attribute[1] which allows specifying how a control “looks like” without changing the kind of data it captures.

And the good news is that since Orbeon Forms 4.9 we have a mechanism to bind custom controls with an appearance. Here is how it works:

  1. We create an fr:character-counter component which implements the logic of counting the characters in a field and acts as a wrapper around an existing control,[2]

  2. and we say that fr:character-counter must apply to input fields, text areas, and other controls if desired, when the character-counter appearance is found:

    xf|input[appearance ~= character-counter],
    xf|textarea[appearance ~= character-counter]

This code specifies a “binding” for the custom control, and the cool thing is that it uses standard CSS selectors - yes, the same CSS selectors which developers use daily in their Web apps. This selector says in essence: “use this custom control implementation for input fields and text areas which have the character-counter appearance”.

But there is more: this binding is declarative which allows Form Builder to discover automatically which controls support the character counter, and propose this as an option to the form author in the Control Settings:

Character Counter Appearance Selection in Form Builder
Character Counter Appearance Selection in Form Builder

This is a fully general mechanism, which not only works for the character counter, but also for selection controls, buttons, and more:[3]

Selection Control Appearance Selection in Form Builder
Selection Control Appearance Selection in Form Builder

Under the hood, there is a not-entirely-trivial algorithm[4] which:

  1. looks at the current control’s name (such as xf:input), datatype, and appearances,
  2. checks all available control bindings in the Form Builder toolbox,
  3. and returns the list of appearances which can apply to the control given its name and datatype.

We are quite happy with the underlying architecture, and we hope the user-facing feature will be useful too! This feature will be available in Orbeon Forms 4.10.


  1. XForms specifies or suggests some standard appeararances. For example, a single selection control <xf:select1> with apperance full should show as radio buttons, while the compact appearance should show as a dropdown menu.  ↩

  2. Curious developers can see the very simple implementation of the fr:character-counter control here.  ↩

  3. We used to have a way to switch between selection controls before Orbeon Forms 4.0, but that disappeared during the big Form Builder rewrite which took place at that time. Now this feature is back but in a much more general way.  ↩

  4. Mostly implemented in BindingDescriptor.scala and BindingOps.scala.  ↩

Friday, May 15, 2015

Namespacing jQuery

Starting with version 4.9, Orbeon Forms isn't polluting the JavaScript global namespace on the browser by exposing its own version of jQuery.

You will benefit from this improvement if you're embedding a form created with Orbeon Forms into an existing web page, whether you do this using the server-side embedding API, the proxy portlet, or full portlet. In any of those cases, starting with Orbeon Forms 4.9, you don't have to worry about the version of jQuery used by Orbeon Forms conflicting with the version of jQuery used by your page.

However, if your own code, designed to run with Orbeon Forms 4.8 or earlier, was relying on Orbeon Forms exposing its version of jQuery, you will need to change it, but the change should be very simple: in your JavaScript code, instead of $ or jQuery, use ORBEON.jQuery.

Tuesday, May 5, 2015

Orbeon Forms 4.9

Today we released Orbeon Forms 4.9!

Major features and enhancements
  • Form Builder
    • New control for showing explanatory text. Lots of forms require explanations, often inline with form fields. Until now, you had to use workarounds to do this in Form Builder, such as using a Text Output field with an HTML label. The new Explanation control addresses this need, and allows you to place explanatory rich text anywhere in your form. (blog post, #507)
    • Custom alerts for invalid data types and missing required fields. Since version 4.3, Form Builder allows you to set separate alert messages for constraints. Now you can also set separate alerts to show when the datatype is incorrect, as well as when a field is required but missing. (doc, #1978)
    • Deselecting all radio buttons. Radio buttons do not have a way, in HTML, to be completely deselected except programmatically. This is usually not something you need to do in a form, but in Form Builder this is often desirable. The Itemset Editor now allows you to do just this (with thanks to Aaron Spike).  (#595)
    • Performance improvements. We improved performance of very large forms in Form Builder. (#2183#2181)
  • Form Runner
    • Fix for occasional data loss with section templates. This is an important fix, which we have also backported to previous version of Orbeon Forms. We recommend patching Orbeon Forms if you are using section templates. (#2106)
    • New wizard validated mode. This new wizard mode allows you to only navigate forward if there are no errors on all preceding pages as well as the current page. This helps ensure that the user follows specific steps when filling out a form. (blog post, #2066)
    • Email validation too strict on TLDs supported. Up until recently, it was possible to know which top-level domains (such as .com, . fr, etc.) were actually in use and to include such tests as part of email validation. But currently there are 810 of those, and the number is likely to grow. So we have relaxed our email validator to allow any TLD. (#2116)
    • Configurable PDF file name. You can now configure the filename to use with the PDF button on the Form Runner Detail page. The filename is configurable via XPath and can even depend on form data. (#2122)
    • Accessibility improvements.
      • Screen readers will now tell you whether an input field is invalid and/or required, via the aria-invalid and aria-required attributes. (#2148)
      • The Refresh button now includes a label. (#2158)
      • Button with menus tell you they are collapsed or expanded (#2162)
    • Performance improvements. We implemented a couple of performance enhancements, in particular to handle large form updates under Chrome. (#2185, #2174)
  • XForms
    • Nested required and type elements. You can now use elements instead of attributes to assign required and type model item properties. This allows giving them distinct identifiers and alert messages. (doc and doc, #1978)
    • New functions to access the username,  group and roles. The following functions can be used to access current user information: xxf:username(), xxf:user-group(), and xxf:user-roles(). These functions also work when using headers-based permissions. (doc#2062#2063)
  • Other
    • Namespaced jQuery.  Orbeon Forms is now a better JavaScript citizen by namespacing our version of jQuery. This way you can include your own version of jQuery or Zepto.js in your page, and it won't conflict with the version used by Orbeon Forms. (blog post#1155)

Internationalization

See Localizing Orbeon Forms for the latest localization support. Localization depends on volunteers, so please let us know if you want to help!

Other new features and bug-fixes

Including the major features and enhancements above, we closed over 80 issues since Orbeon Forms 4.8.2 (and almost 100 since 4.8.0).
    Current browser support
    • Form Builder (creating forms)
      • Chrome 42 (latest stable version) and Chrome 44 dev (current dev channel)
      • Firefox 37 (latest  stable version) and the current Firefox ESR
      • IE 11
      • Safari 8
      • Form Runner (accessing form)
        • All browsers supported by Form Builder (see above)
        • IE8, IE9 and IE10
        • Safari Mobile on iOS 7 and iOS 8
        • Chrome for Android (stable channel)
      Compatibility notes
      • jQuery. The version of jQuery used by Orbeon Forms is now "namespaced", which means you can't use it directly anymore by referring to $ or jQuery. Instead, if you want to refer to the version of jQuery used by Orbeon Forms, use ORBEON.jQuery.
      • HTTP header forwarding
        • The oxf.xforms.forward-submission-headers property is deprecated. Use  oxf.http.forward-headers when needed.
        • You don't need to add Orbeon-Client to oxf.http.forward-headers anymore.
        • The XForms xxf:forward-submission-headers attribute on xf:model, which allows to specify header forwarding on a per-form basis, is removed. Use instead the global oxf.http.forward-headers property.
      • XForms error handling
        • XPath static errors now always cause an error upon form load, and XPath dynamic errors never do. (doc)
        • The oxf.xforms.fatal-errors-during-initialization property is removed.
      • Authentication. There is now a separate servlet filter called orbeon-form-runner-auth-servlet-filter which provides authentication information to Form Runner. Previously the functionality performed by this filter was done internally. If you make changes to the Orbeon Forms web.xml file, you need to make sure that this filter is present. If you use the stock web.xml, there shouldn't be any need for changes.

      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!

        Thursday, April 23, 2015

        Automatic web links in PDF files

        Orbeon Forms can automatically produce nice PDF files without any extra work (see the documentation).

        While PDFs are useful for printing and archival, they also have a few smarter features. For example, web links in a PDF file can be made clickable, and this is something that Orbeon Forms leverages:

        1. Links in rich text content are clickable and open your web browser to the target link.
        2. Links identified in regular input fields and text areas are automatically highlighted and clickable as well. [1]

        And now we have added detection and automatic linking of email addresses in input fields and text areas as well. Here is an example of PDF output with the various types of links Orbeon Forms detects:

        Examples of automatic links in a PDF file
        Examples of automatic links in a PDF file

        This enhancement will be included in Orbeon Forms 4.9. And for the curious, you can see the regular expressions we use for this.


        1. This feature was introduced with Orbeon Forms 4.6, but we hadn’t covered in a blog post yet!  ↩

        Monday, April 6, 2015

        Adding explanatory text to your forms

        Some forms are complex, and form authors want to provide guidance to the end-users who will be filling out those forms. For every field, in addition to a label, form authors can provide:

        • hint, shown below the field. Using a hint works well for short pieces of information that fit comfortably below the field.
        • A help message, shown in a popover when users click on a help icon next to the field. The help works well for longer pieces of texts that users won't necessarily need.
        In some cases however, form authors would like to have the explanatory text displayed in-line in the form, instead of in a popover. For instance, this can make sense when end users are likely to need that information, or if the form author wants to draw users' attention to a piece of information. For this, the upcoming Orbeon Forms 4.9 introduces a new "control": the explanation control.

        In Form Builder, the explanation control shows in the left sidebar, just like other controls, so form authors can add it anywhere in the form where other controls can be added. Upon inserting an explanation control, in Form Builder, form authors can type text in a rich text editor:


        At runtime, when users fill out the form, this text will just show as-is:


        Just like the text in the label, hint, and help, text entered in the explanation control is fully localizable, and forms can have different version of that text for all the different languages supported by the form. Form authors can localize the text in an explanation control directly from Form Builder, just like they do for the labelhint, and help.

        We'd like to thank Aaron Spike, from the Martin Luther College for contributing a large part of the underlying code for this feature. Thank you, Aaron!

        Tuesday, March 31, 2015

        Orbeon Forms 4.8.2

        Today we released Orbeon Forms 4.8.2 PE. This update to Orbeon Forms 4.8 PE contains bug-fixes and is recommended for all Orbeon Forms 4.8 PE users.

        Specifically, this release addresses the following issues since version 4.8.1:
        • Form Builder
          • XBL template bind attribute prefix/namespace lost when control inserted (#2095)
        • Form Runner
          • xxbl:mirror="true" not working after oxf.xforms.cache.documents.size reached (#2106)
          • Wrong value in date/time control when using picker (#2086)
          • Error when generating schema for form using section template (#2091)
          • NPE when running pipeline with output from CLI (#2092)
          • Autocomplete: fr-set-label has no effect if resource doesn't use the value (#2098)
          • POST to /new handles missing data-format-version incorrectly (#2104)
          • PDF: Wrong language if fr-language was passed to new/edit/view page (#2110)
          • Tables in HTML control labels don't show in the PDF (#2135)
          • Email validation too strict on TLDs supported (#2116)
          • Persistence proxy to support header/cookies forwarding (#2053)
          • Liferay Proxy Portlet - init-param "enable-url-parameters" is backwards (#2138)
          • Error "The moduleId is not correct" when deploying portlet (#2153)
          • Disable Liferay "speed filters" in proxy portlet (#2155)
        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!