Orbeon Forms 2022.1
Last updated
Last updated
Saturday, December 31, 2022
Today we released Orbeon Forms 2022.1! This release is packed with new features and bug-fixes!
Form Runner now features a new Landing page, organized in cards which provides quick access to:
Quick links, including Form Builder and the Administration page
Your published forms
Your in-progress Form Builder forms
Demo forms
Some cards directly list content, including the list of published forms and the list of in-progress Form Builder forms.
You can configure whether you want to have a particular card on the Landing page. For example, you can hide the demo forms for production deployment.
All Form Runner and Form Builder navigation bars now provide a direct link to the Landing page. This can be disabled if not desired.
We have made the Summary page layout fluid, similar to the Forms/Admin page (previously known as the Home page).
Finally, Form Runner buttons now are sticky, so that they are always visible when scrolling. This is particularly useful on the Summary and Forms pages, which can display long lists of forms or form data.
Previously, Form Runner featured a static landing page, as well as a Home page, which doubled as an Admin page when the user was an administrator. The Home page is now replaced by a Published Forms page, which shows published forms accessible to the user, but no administration functions, and a separate Forms Admin page, which is only accessible to administrators.
The Forms Admin page is very similar to the Published Forms page, but features additional administration functions and shows library forms.
Form Builder has long supported drag and drop of form controls between grid cells. This release introduces drag and drop of form controls from the toolbox to grid cells, which is more intuitive to newcomers and also convenient for experienced users. You can still click on toolbox controls to add them to a grid cell as before, but you can now also drag and drop them.
Previously, Form Runner permissions were configured per form. This release introduces the ability to configure permissions per app, as well as globally. This is particularly useful when you have a large number of forms, and want to configure permissions for all of them at once.
Per-app and global permissions are currently set using configuration properties. In the future, we plan to add a UI to configure them.
See also the documentation.
The new List permission allows specifying that the user can list form data on the Form Runner Summary page.
With earlier versions of Orbeon Forms, the ability to "Read" implied the ability to List on the Summary page.
For more details, see the documentation.
This version includes lots of improvements to the look and feel of Form Runner and Form Builder, including:
wide navigation bar
flat buttons
use of the system font by default
lighter background and rounded corners
more modern dialogs
The Image Attachment form control now supports resizing images upon upload. You can configure the maximum width and height of images, and the control will automatically resize images to fit within these dimensions before storing the image in the persistence layer.
You can also choose the resulting image format, which can be PNG or JPEG, and the quality of the JPEG image.
The Summary, Forms, and Admin pages now support quick selection of multiple form data or published forms. These pages already allowed you to perform operations on one or more rows, such as deleting data, publishing forms, etc. However, you had to check each checkbox individually. We have now implemented two new features that improve on this:
A menu to quickly select items on the Summary page (the Admin page already had such a menu).
The ability to “shift-click” checkboxes.
The menu allows you to select all items, or to select only items that match a particular status. For example, you can select only published forms on the Admin page, or only form data that is not an in-progress draft in a form's Summary page. The number of selected items is conveniently displayed in the menu.
If you are familiar with for example Gmail, you might know that you can select a checkbox, and then shift-click another one, and all the checkboxes in the interval will be selected. Similarly, you can deselect a series of checkboxes. The exact logic is a little subtle, but we implemented something very similar in Form Runner.
This doesn’t only apply to the Form Runner Summary, Forms, and Admin pages: it applies to any checkboxes in a repeated grid. And it also applies to the Checkboxes form control, so you can quickly select and deselect a range of checkboxes.
See also:
Blog post: Improved selection of multiple items
Orbeon Forms 2018.2 introduced Simple Data Migration (see also the original blog post). This feature allows the form author to make changes to a published form, including adding and removing form fields, grids, and sections, without creating a new form version.
This release introduces a number of improvements to Simple Data Migration. With Orbeon Forms 2022.1, you can move form controls within the form as long as they remain within the same nesting of repeated content, republish the form over the existing version, and things will just work. For example:
Move controls at the top-level of a form, even across grids and sections.
Move controls within a given level of repeated grids or repeated sections, even across nested grids.
Simply moving a form control this way allows you to reorganize your form while keeping access to existing data.
See also:
Blog post: Improved simple data migration
This release enhances the send
action with the ability to send multiple items to a service endpoint in a single HTTP request using a so-called multipart request format. This allows sending form data along with its attachments, and even to add a PDF file or an Excel export to that. The configuration is simple as you just specified multiple content
tokens:
See also:
In this release, we have introduced many accessibility improvements. In particular:
Screen readers now read control labels for more complex form controls
Screen readers now read groups of radio buttons and checkboxes
Screen readers can now read form control hints
Control focus highlights are nicer and more consistent and supported on control groups
Focus highlights on groups can be disabled via configuration property and are enabled by default. The following illustrates highlights on selection controls and groups (in practice focus highlights are only shown on keyboard focus):
Users of Orbeon Forms are used to using variable references in formulas to refer to the values of other form controls. However, you couldn't use variables in some places where you might have expected them to work. We have now improved this, and with this version you can use variables like before in the following formulas:
Required
Validation
Calculated Value
Initial Value
Visibility
Read-Only
But you can also use them the following formulas:
Repeated grids and sections:
Minimum Number of Repetitions
Maximum Number of Repetitions
Freeze Repetitions
Number and Currency fields
Prefix
Suffix
Dynamic Dropdown:
Resource URL
Choices formula
Label formula
Value formula
Hint formula
Actions
Simple Actions
Action Syntax
Control name
Formula
Using variables also has the benefit that when renaming controls, the variable references are automatically updated.
See also:
Blog post: Improvements to variables in formulas
The File Scan API has been updated with the following enhancements to the original version:
The provider can return a modified file name, content type, or even replace the entire content.
The provider can return custom error messages in the current language of the form.
An extension mechanism via hash maps is provided.
See also:
It was already possible to attach multiple PDF templates to a form. It is now possible to create multiple email templates for a form. This allows you to send different emails to different recipients, with different content, and even with different attachments.
When running the email
action, you can now specify a new template
parameter to select the email template to use. If you don’t specify a template, the default template is used.
Form Builder now shows the control names in overlay, which makes it easier to find the control you want to edit. The following screenshot shows the submitter-pta-position
control names in the overlay:
For sections with repeated content, like for the "Repetition Label", the "Add Repetition Label" tab allows you to set a label that applies to the button used to add repetitions.
The PDF output of Orbeon Forms has been improved in several ways.
Orbeon Forms now embeds the richer Inter font into PDF files by default.
PDF bookmarks are now generated correctly for sections and allow quick navigation in the resulting PDF.
In addition:
Printed checkboxes now show differently from radio buttons for clarity.
The PDF renderer library has been updated and provides bug-fixes and better CSS support.
Orbeon Forms already had a "Radio buttons with Other" form control. The nwe "Dropdown with Other" control is similar to the existing "Dropdown" control, but it also allows the user to enter a custom value. (#5172)
Form Builder already used CSS grids for rendering the form being edited. Starting with Orbeon Forms 2022.1, by default, Orbeon Forms also uses CSS grids for all grids at runtime as well. Previously, the default was to use HTML tables at runtime. This is made possible with the removal of Internet Explorer support.
Form Builder has a UI to specify whether the Wizard should have a separate table of contents (TOC). Previously, this was only configurable via properties.
In addition, showing the section status is supported even when the TOC is not separate. There is also a Form Builder UI to control this.
The Actions editor now supports running an action when a control disappears.
In addition, when a service exposes URL parameters, an action can explicitly specify the value of the parameter.
The JavaScript API supports setting headers (#5142)
Administrator can configure the behavior of the Version dropdown of the Publish dialog (#5281)
The Search API has a new option to return all indexed fields (#4968)
Email addresses support including a personal name (#5313)
The date picker has a new option to select week start day (#5334)
New XPath function to obtain link back to Form Runner (#5338)
The Summary search supports the new "Dropdown with Other" form control (#5408)
The Summary page aligns table headers depending on content (#1693)
Combined "drop-up" buttons can now be configured for Form Runner (#5546)
The fr:control-string-value()
and fr:control-typed-value()
function can access controls within section templates (#5246)
This release no longer supports Internet Explorer. In particular, Internet Explorer 11 is no longer supported.
With this release, we have removed support for the date picker based on the long-deprecated YUI library. This date picker was used in the following cases:
With Form Builder/Form Runner, when forms had not been migrated (that is, either republished or migrated using the Admin page).
When using plain XForms outside of Form Builder/Form Runner.
With this release, Form Runner now automatically migrates forms at runtime to use the new date picker, even if they have not been explicitly migrated. However, if you are using plain XForms outside of Form Runner, the new date picker currently does not work.
Specifically, with plain XForms:
xf:input
fields bound to an xs:date
, xs:time
, or xs:dateTime
node don't work and show plain input fields instead.
fr:date
, which worked outside of Form Runner with Orbeon Forms 2021.1, currently doesn't work.
We plan to add support for the new date picker in plain XForms in a future point release. If you are using plain XForms and not Form Builder/Form Runner, we don't recommend upgrading until backward compatibility is added.
The fr:number
field doesn't work outside of Form Runner (#5533).
We plan to add support for the new date picker in plain XForms in a future point release. If you are using plain XForms and not Form Builder/Form Runner, we don't recommend upgrading until backward compatibility is added.
With earlier Orbeon Forms versions, the landing page was at /home/
. This was a static landing page, which mixed links to the Form Runner Home page, Form Builder, and demo forms. The new Landing page replaces this page and automatically redirects to the /fr/
path. The /home/
path now redirects to /fr/
.
The /fr/
path pointed to the combined Home page. It how points to the Landing page. Instead, the Home page is now split into the Forms and Admin pages:
/fr/forms
now points to published forms (Forms page)
/fr/admin
now points to published forms with administrative functions (Admin page)
If the data posted contains extra elements, those were ignored prior to Orbeon Forms 2022.1. With Orbeon Forms 2022.1 and newer, they cause an error.
See Initial data posted to the New Form page.
Form Builder already used CSS grids for rendering the form being edited. Starting with Orbeon Forms 2022.1, by default, Orbeon Forms also uses CSS grids for all grids at runtime as well. Previously, the default was to use HTML tables at runtime. This is made possible with the removal of Internet Explorer support.
There can be impact on custom CSS, since the markup now contains <div>
elements instead of <table>
, <tr>
, <td>
, etc., and the default CSS use display: grid
and related CSS properties.
Although we do not recommend it, it is possible to change the default back to HTML tables with the following property:
The ability to mark a field as "Show in email subject", as highlighted in the screenshot below, taken from Orbeon Forms 2021.1, is no longer supported. Instead, you can specify what the subject of the email should be in the Email Settings dialog, and use template parameters to add the value of fields to the subject of the email.
If, with earlier versions of Orbeon Forms, you were calling service APIs and passing headers, they had to match the headers configured with the header-driven method. Starting Orbeon Forms 2022.1, the headers can only be the Orbeon-*
headers.
See Providing user information for more.
xf:load
handling of xxf:show-progress
Before Orbeon Forms 2022.1, when loading a javascript:
URI, xf:load
was ignoring the value of the xxf:show-progress
attribute, and always behaving as if the attribute was set to false
. Instead, starting with Orbeon Forms 2022.1, if you don't specify xxf:show-progress
, it defaults to false
for javascript:
URIs, and to true
otherwise.
This allows you to keep the progress indicator when using xf:load
to run JavaScript that loads a page. Conversely, in the unlikely case you had some code doing a <xf:load resource="javascript: …" xxf:show-progress="true"/>
but didn't want the progress indicator to be kept, then you will need to either remove the xxf:show-progress="true"
or change the value of the attributes to false
.
JavaScript companion classes are very important with Orbeon Forms. Since Orbeon Forms 2016.1, the javascript-lifecycle
mode provides an easy way to register custom JavaScript to provide behavior to custom components.
The older way to associate companion classes, without the javascript-lifecycle
mode, is deprecated in this version. Specifically, the following is deprecated:
use of ORBEON.xforms.XBL.declareClass()
(use ORBEON.xforms.XBL.declareCompanion
instead)
use of the instance()
method on the component class (use javascript-lifecycle
and instanceForControl()
instead)
explicit calling of the init()
and destroy()
method on component instances (Orbeon Forms manages those calls instead)
xxbl:parameter()
The xxbl:parameter()
XSLT function has been removed in this version of Orbeon Forms.
The documentation for the following functions stated that an empty sequence was returned in some cases, but the implementation was not correct and returned an empty string instead. Starting with Orbeon Forms 2022.1, the implementation is correct and returns an empty sequence when appropriate. This affects the following functions:
fr:document-id()
fr:form-title()
fr:workflow-stage-value()
fr:username()
fr:user-group()
fr:wizard-current-page-name()
Usually this change does not cause any problems. However, in some cases, the result can be different. For example the following condition:
This would work before Orbeon Forms 2022.1 and return true()
when no workflow stage was set. However, with Orbeon Forms 2022.1, this will return false()
because when no workflow is set, the function returns an empty sequence, and comparing an empty sequence with anything always returns false()
. Instead, the formula above must be written as: