Thursday, October 22, 2015

Repeated grids and sections just got more subtle

We recently implemented two improvements to repeated grids and repeated sections, which appear as two new options in the “Sections/Grid Settings” dialog:

The Sections/Grid Settings dialog
The Sections/Grid Settings dialog

Initial values

The new “Apply Initial Value Formulas when Adding Iterations” option specifies whether the “Initial Value” formulas apply to new fields when you add a new row to a repeated grid or a new section repetition to a repeated section.

As a reminder, the “Initial Value” formula applies only once to new form data, unlike the “Calculated Value” formula which applies to new form data but also any time anything changes in form data.

Previously, the “Initial Value” formula would apply to initial iterations in a repeated grid or section when the form loaded, but not to new iterations added by the user while filling out the form.

With this new option, you have a choice to keep things as they were, or to allow Form Runner to apply the “Initial Value” formulas to newly-added iterations, which we think is what most users would want.

Here is an example showing how, with the option enabled, new iterations can have dynamic initial values. As the user adds rows, the following formulas apply to the fields in that new row:

  • a constant value, “42”
  • the date and time at which the new row got added (using the current-dateTime() formula)
  • the current number of controls in the form

Each new row gets the new values exactly once, and existing rows are left untouched:

Initial values as iterations are added
Initial values as iterations are added

Number of initial iterations

The new “Initial Number of Iterations Uses Template” option specifies, when an enclosing repeated section creates a new iteration, how many iterations the enclosed repeated grid or section will contains:

  • when enabled: the number of iterations shown in Form Builder (which can be no iterations at all, one iteration, two iterations, etc.)
  • when disabled: exactly one iteration

The following screenshot shows a case with a repeated grid within nested repeated sections. At first, when the form shows, there are two iterations of the repeated grid.

Initial iterations when the form loads
Initial iterations when the form loads

With the option enabled on the grid, adding a new iteration of Repeated section 2 causes the new iteration to contain a new repeated grid with two iterations:

Number of initial iterations coming from the template
Number of initial iterations coming from the template

While, with the option disabled on the grid, adding a new iteration of Repeated section 2 causes the new iteration to contain a new repeated grid a single iterations:

One initial iteration only
One initial iteration only

These two options are enabled by default for new forms and new repeated grids and sections. They are disabled by default for grids and sections created with previous versions of Orbeon Forms. So if you have existing forms and want the new behavior for some or all repeated grids/sections, you need to open these forms in Form Builder and enable the relevant options.

These improvements will be available in Orbeon Forms 4.11.