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!