Error summary
Last updated
Last updated
The Error Summary component is a reusable component listing the errors present on your form (or a sub-form):
Main features:
Configurable title at the top
Can handle your entire form or a sub-form
Lists invalid fields, with associated alert messages
Click on an entry focuses input on the invalid field (or links near it in noscript mode)
Keeps track of visited controls, and shows error only for those visited while keeping track of all errors
Handles repeats: if an iteration is moved, the error summary updates
More than one error summary can be placed in the page
The minimal configuration looks like this:
The mandatory observer attribute points to a control to observe. That control and all the descendants of that control are surveyed for changes in validity:
NOTE: This means that unless the error summary only observes a single control, you need a grouping control in your form, such as <xf:group>.
NOTE: For a control to visually appear in the summary, it must have a non-empty <xf:alert> element. However, if it doesn't have one, the error summary still adds the control to the count of current errors.
The title can be dynamic, e.g. for localization purposes:
If specified, the following attributes point to nodes into which the error summary makes useful information available to you:
error-count-ref: current number of errors in the sub-form (xs:integer).
visible-errors-count-ref: current number of visible errors in the sub-form. An error for a control is visible if the control has been visited by the user (xs:integer).
valid-ref: whether the sub-form is valid or not (xs:boolean).
You can use this information for example to show a status icon:
You can dispatch the fr-visit-all event to the error summary. This:
makes the summary consider all controls under the configured observer(s) as visited
marks all controls under the configured observer(s) as visited by adding the xforms-visited and xforms-alert-active-visited classes
This is useful when the user, for example, presses a "Save" button: in that case, you might want to show all the errors on the form right away:
When you do this, make sure that <fr:error-summary> has an id:
Then, to disable the alert icon on invalid controls, until either users went through the control, or users did an action (such as "Save") that dispatched an fr-visit-all, add the following CSS. The first rule disables the background image and the second one enables it, overriding the first rule in cases where the alert is both active and the control is visited. Most likely, you will need to modify the relative path in the second rule, depending on the location of your CSS file. The path should resolve to /your-all/ops/images/xforms/exclamation.png if you are not in separate deployment, and /your-app/orbeon/ops/images/xforms/exclamation.png if you use separate deployment. Note that it is better here to have a relative URL (adjusting the number of .. in the path) rather than an absolute URL (starting with /your-app), as a relative URL allows you to change the context of your application without having to change the CSS.
You can dispatch the fr-unvisit-all event to the error summary. This:
makes the summary consider all controls under the configured observer(s) as not visited
marks all controls under the configured observer(s) as not visited by removing the xforms-visited and xforms-alert-active-visited classes
In Orbeon Forms, a form control can be visited or not. Visited controls have typically been visited by the user, which means that the user navigated through the form control, possibly without changing its value. One way to visit form controls is to navigate using the "Tab" key, or to click on the form control and then click outside of it. Another way is to use the default "Save" or "Send" buttons, which by default visit all the form controls before proceeding. The notion is used to determine whether to show validation errors associated with that form control.
[SINCE Orbeon Forms 2023.1] Form controls are also marked as visited when they are calculated, visible, and their value changes. This is useful to immediately show validation errors associated with such form controls, which are typically implemented with the Calculated Value form control. You can disable this behavior by setting the following property:
[SINCE Orbeon Forms 2024.1] Form controls are also marked as visible as they become invalid. This is useful when you want to immediately show validation errors for field that become invalid not as the result of their value changing, but because their validity depend on something else in the form that has changed. You can disable this behavior by setting the following property:
[SINCE Orbeon Forms 2018.1]
When forms have a large number of errors, the Error Summary can become too large to be very useful. By default, the Error Summary only shows 20 errors, and link buttons appear to show more or less errors if needed.
To change the default, you can set the following property:
The page-size attribute can also be used on the component when used outside of Form Runner.
When there are no visible errors, the entire body of the error summary is hidden. You can had your own header and footer content within that body so it hides and shows depending on whether there are errors or not. Just add the <fr:header> and <fr:footer> elements:
In addition to errors related to controls, the error summary can handle global errors:
The fr:errors element takes a nodeset attribute and iterates on a list of nodes containing information about global errors. If the node-set returned is empty, no global error is displayed.
The nested fr:label (optional) and fr:alert elements are evaluated relative to each node in the node-set. They return respectively:
A label text displayed to the left
An alert text displayed to the right
By default the error summary updates the list of error as they occur on the form.
By specifying the incremental="false" attribute, errors only show on demand with the fr-update and fr-clear events.
To update the visible list of errors with the actual errors in the form, dispatch the fr-update event:
To clear the visible list of errors, dispatch the fr-clear event:
To properly update the error summary within a submission response, you might need an explicit <xf:refresh> action before dispatching fr-update, so that the UI captures all the valid/invalid states: