Orbeon Forms
  • Getting started
  • Installation
    • Logging
    • Configuration banner
    • Docker
    • Azure
    • Tomcat
    • WildFly
    • WebSphere
    • WebLogic
    • GlassFish
    • Caches
    • Replication
    • Upgrading
  • Configuration
    • Properties
      • General
        • HTTP client
      • Form Runner
        • Detail page
          • Attachments
          • Email properties
          • PDF
          • Table of contents
        • Persistence
        • Summary page
      • Form Builder
      • XForms
    • Advanced
      • Workflows
      • Session management
      • State handling
      • Client-side error handling
      • Clustering and High Availability
      • Configuring a Form Runner eXist database
      • Creating a production WAR
      • Environments
      • JavaScript and CSS assets
      • Limiter filter
      • Run modes
      • Security
        • Content-Security-Policy header
      • SAP Hybris Module
      • XForms logging
    • Troubleshooting
      • Troubleshooting with the orbeon.log
      • Memory and threads
      • Relational database logging
      • Misc
  • Form Builder
    • Form settings
      • Time window
    • Form editor
      • Form area
      • Toolbox
      • Buttons bar
      • Control settings
      • Dependent fields and sections
      • Validation
      • Choices editor
      • Publishing
      • Cut, copy and paste
      • Section and grid settings
      • Section settings
      • Grid settings
      • Quick control search
      • Repeat settings
      • Repeated grids
      • Undo and redo
      • Keyboard shortcuts
    • Formulas
      • Examples of formulas
      • Formulas inspector
      • Formulas console
    • Summary page
    • Form localization
    • Advanced
      • Edit source
      • Services and actions
        • HTTP services
        • Database services
        • Simple Actions
        • Action Syntax
        • Action Syntax examples
        • Synchronizing repeated content
      • Testing a form in web mode
      • Testing PDF production
      • Testing offline functionality
      • Email Settings dialog
      • Field-level encryption
      • Messages
      • Section templates
      • Template syntax
      • XML Schemas support
      • Extensibility
        • Extension API
        • Integration
        • Toolbox component metadata
  • Form Runner
    • Overview
      • Terminology
    • Pages
      • Landing page
      • Published Forms page
      • Forms Admin page
      • Summary page
    • Components
      • Alert dialog
      • Attachment
      • Autocomplete
      • Captcha
      • Character counter
      • Checkbox input
      • Currency
      • Date
      • Dropdown date
      • Static and dynamic dropdown
      • Error summary
      • Grid
      • Handwritten signature
      • Hidden field
      • Image
      • Image annotation
      • Image attachment
      • Number
      • Open selection
      • Repeater
      • Formatted Text / Rich Text Editor
      • Section
      • Single-selection tree
      • Source code editor
      • Time
      • US phone
      • US state
      • Video
      • Video attachment
      • Wizard
      • XForms inspector
      • Yes/No answer
    • Features
      • Automatic calculations dependencies
      • Datasets
      • Excel and XML import
      • Excel and XML export
      • Summary page Excel Export
      • Form definitions and form data Zip Export
      • Purging historical data
      • Lease
      • Localization
      • Supported languages
      • Mobile support
      • Multitenancy
      • Form Runner navigation bar
      • PDF production
        • Automatic PDF
        • Automatic PDF header and footer configuration
        • PDF templates
      • Responsive design
      • Revision history
      • S3 storage
      • Simple data migration
      • TIFF production
      • Versioning
      • Wizard view
      • Workflow stage
    • Persistence
      • Using a relational database
      • Relational database schema
      • Purging old data using SQL
      • Auditing
      • Autosave
      • Database support
      • Flat view
    • Linking and embedding
      • Linking
      • Java Embedding API
      • JavaScript Embedding API
      • Liferay full portlet
      • Liferay proxy portlet
      • Securing Form Runner access
      • Form Runner offline embedding API
      • Angular component
      • React component
    • Access control and permissions
      • Users
      • Login & Logout
      • Deployed forms
      • Form fields
      • Editing forms
      • Owner and group member
      • Organizations
      • Scenarios
      • Token-based permissions
    • Styling
      • CSS
      • Grids CSS
      • Automatic PDF styling and CSS
    • APIs
      • Authentication of server-side service APIs
      • Persistence API
        • CRUD API
        • Search API
        • List form data attachments API
        • Form Metadata API
        • Lease API
        • Reindexing API
        • Caching
        • Versioning
        • Revision History API
        • Zip Export API
        • Custom persistence providers
      • Other APIs
        • Connection context API
        • Duplicate form data API
        • File scan API
        • Form Runner JavaScript API
        • Generate XML Schema API
        • PDF API
        • Publish form definition API
        • Run form in the background API
      • Data formats
        • Form data
        • Date and time
        • Form definition
    • Architecture and integration
      • Architecture
      • Access form data
      • Integration
    • Advanced
      • Buttons and processes
        • Simple process syntax
        • Core actions
        • Form Runner actions
          • Save action
          • Send action
          • Email action
        • XForms actions
        • Predefined buttons, processes and dialogs
        • Summary page buttons and processes
      • Custom dialogs/model logic
      • Services
      • Singleton form
      • Monitoring HTTP requests
  • XForms
    • Core
      • Attribute Value Templates (AVTs)
      • Binds
      • Validation
      • Variables
      • Keyboard focus
      • XForms JavaScript API
      • Error handling
        • Detailed behavior
      • Model-Bind variables
      • XForms 2.0 support
    • Events
      • Standard support
      • UI refresh events
      • Keyboard events
      • Extension events
      • Extension context information
      • Other event extensions
    • Actions
      • Repeat, insert and delete
      • Scripting actions
      • Extensions
    • Controls
      • Label, hint, help
      • Input
      • Output
      • Text area
      • Button
      • Upload
      • Dialog
    • Submission
      • Standard support
      • JSON support
      • Asynchronous submissions
      • Caching extension
      • Other submission extensions
    • XPath
      • Type annotations
      • Expression analysis
      • Tips
      • Compatibility
      • Standard functions
      • Maps and arrays Functions
      • Extension functions
        • Core functions
        • Utility functions
        • Model functions
        • Controls functions
        • XML functions
        • JSON functions
        • HTTP functions
        • Form Runner functions
        • Other functions
        • Deprecated functions
    • XBL components
      • FAQ
      • Guide
        • XBL Tutorial
        • Bindings
        • XForms models
        • Including content
        • Event handling
        • Conventions
        • Map XBL example
        • Learning from existing components
      • Advanced topics
        • XBL Modes
        • JavaScript companion classes
        • XBL library
        • Extensions
        • Attachment controls
    • XForms tutorial
      • Introduction
      • Installation
      • The Hello application
      • The Bookcast application
        • The basic app
        • Database access
        • Polishing the app
        • Adding a feed
    • Using XForms from Java apps
  • XML Platform
    • Page Flow Controller
      • Basics
      • XML submission
      • Navigating between pages
      • Paths and matchers
      • Other configuration elements
      • Typical combinations of page model and page view
      • Examples
      • Authorizing pages and services
    • Processors
      • URL generator
      • Request generator
      • PDF to image converter
    • Resources
      • Resource managers
      • Setting up an external resources directory
    • Other
      • Binary and text documents
  • FAQ
    • Licensing
    • PE and Dev Support
    • Form Builder and Form Runner
    • Resources and support
    • Other technical questions
  • Contributors
    • Automated tests
    • Building Orbeon Forms
    • Localizing Orbeon Forms
    • Validation functions
    • Contributor License Agreement
  • Release notes
    • Orbeon Forms 2022.1.9
    • Orbeon Forms 2024.1.1
    • Orbeon Forms 2023.1.7
    • Orbeon Forms 2024.1
    • Orbeon Forms 2023.1.6
    • Orbeon Forms 2023.1.5
    • Orbeon Forms 2021.1.11
    • Orbeon Forms 2022.1.8
    • Orbeon Forms 2023.1.4
    • Orbeon Forms 2023.1.3
    • Orbeon Forms 2023.1.2
    • Orbeon Forms 2022.1.7
    • Orbeon Forms 2023.1.1
    • Orbeon Forms 2023.1
    • Orbeon Forms 2022.1.6
    • Orbeon Forms 2021.1.10
    • Orbeon Forms 2022.1.5
    • Orbeon Forms 2021.1.9
    • Orbeon Forms 2022.1.4
    • Orbeon Forms 2022.1.3
    • Orbeon Forms 2021.1.8
    • Orbeon Forms 2022.1.2
    • Orbeon Forms 2022.1.1
    • Orbeon Forms 2022.1
    • Orbeon Forms 2021.1.7
    • Orbeon Forms 2021.1.6
    • Orbeon Forms 2021.1.5
    • Orbeon Forms 2021.1.4
    • Orbeon Forms 2021.1.3
    • Orbeon Forms 2021.1.2
    • Orbeon Forms 2021.1.1
    • Orbeon Forms 2021.1
    • Orbeon Forms 2020.1.6
    • Orbeon Forms 2019.2.4
    • Orbeon Forms 2019.1.2
    • Orbeon Forms 2018.2.5
    • Orbeon Forms 2018.1.4
    • Orbeon Forms 2020.1.5
    • Orbeon Forms 2020.1.4
    • Orbeon Forms 2020.1.3
    • Orbeon Forms 2020.1.2
    • Orbeon Forms 2019.2.3
    • Orbeon Forms 2020.1.1
    • Orbeon Forms 2020.1
    • Orbeon Forms 2019.2.2
    • Orbeon Forms 2019.2.1
    • Orbeon Forms 2019.1.1
    • Orbeon Forms 2019.2
    • Orbeon Forms 2019.1
    • Orbeon Forms 2018.2.4
  • Release history
  • Use cases
  • Product roadmap
  • Index of features
Powered by GitBook
On this page
  • What it does
  • Basic usage
  • Getting information from the error summary
  • Controls marking as visited
  • Marking all controls as visited
  • Marking all controls as not visited
  • Automatically marking controls as visited
  • Setting a page size
  • Adding a header and a footer
  • Global errors
  • Non-incremental mode
  • See also
  1. Form Runner
  2. Components

Error summary

PreviousStatic and dynamic dropdownNextGrid

Last updated 3 months ago

What it does

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

Basic usage

The minimal configuration looks like this:

<fr:error-summary observer="my-group">
    <fr:label>Your Form Contains the Following Errors</fr:label>
</fr:error-summary>

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:

<xf:group id="my-group">
    <xf:input>
        <xf:label>Title</xf:label>
        <xf:alert>The book title is missing</xf:alert>
    </xf:input>
    <xf:input>
        <xf:label>Author</xf:label>
        <xf:alert>The author name is missing</xf:alert>
    </xf:input>
    <xf:input>
        <xf:label>Link</xf:label>
        <xf:alert>The link must be a valid HTTP or HTTPS URL </xf:alert>
    </xf:input>
</xf:group>

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:

<fr:error-summary observer="my-group">
    <fr:label><xf:output value="instance('resources')/summary-title"/></fr:label>
</fr:error-summary>

Getting information from the error summary

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).

<fr:error-summary observer="my-group" errors-count-ref="instance('errors')/errors-count" valid-ref="instance('errors')/valid">
    <fr:label>Your Form Contains the Following Errors</fr:label>
</fr:error-summary>

You can use this information for example to show a status icon:

<xf:group ref=".[not(instance('errors')/valid = 'true')]">
    <xhtml:img src="/apps/my-app/images/warning.png" alt="Form is invalid"/>
</xf:group>

Controls marking as visited

Marking all controls as visited

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:

<xf:trigger>
    <xf:label>Save</xf:label>
    <xf:dispatch ev:event="DOMActivate" name="fr-visit-all" targetid="my-error-summary"/>
</xf:trigger>

When you do this, make sure that <fr:error-summary> has an id:

<fr:error-summary observer="my-group" id="my-error-summary">
    ...
</fr:error-summary>

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.

.xforms-alert-active         { background-image: none }
.xforms-alert-active-visited { background-image: url(../../../ops/images/xforms/exclamation.png) }

Marking all controls as not visited

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

Automatically marking controls as visited

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:

<property
    as="xs:boolean"
    name="oxf.xforms.xbl.fr.error-summary.visit-value-changed"
    value="false"/>
<property
    as="xs:boolean"
    name="oxf.xforms.xbl.fr.error-summary.visit-invalid"
    value="false"/>

Setting a page size

[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:

<property 
    as="xs:integer" 
    name="oxf.xforms.xbl.fr.error-summary.page-size"
    value="10"/>

The page-size attribute can also be used on the component when used outside of Form Runner.

Adding a header and a footer

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:

<fr:error-summary observer="my-group">
    <fr:label>Your Form Contains the Following Errors</fr:label>
    <fr:header><xhtml:div class="fr-separator">&#160;</xhtml:div></fr:header>
</fr:error-summary>

Global errors

In addition to errors related to controls, the error summary can handle global errors:

<fr:error-summary observer="my-group">
    <fr:errors nodeset="instance('errors')/error">
        <fr:label ref="label"/>
        <fr:alert ref="alert"/>
    </fr:errors>
</fr:error-summary>

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

Non-incremental mode

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.

<fr:error-summary observer="my-group" id="my-error-summary" incremental="false">
    ...
</fr:error-summary>

To update the visible list of errors with the actual errors in the form, dispatch the fr-update event:

<xf:dispatch name="fr-update" targetid="my-error-summary"/>

To clear the visible list of errors, dispatch the fr-clear event:

<xf:dispatch name="fr-clear" targetid="my-error-summary"/>

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:

<xf:action ev:event="xforms-submit-done">
    <xf:dispatch name="fr-visit-all" targetid="error-summary"/>
    <xf:refresh/>
    <xf:dispatch name="fr-update" targetid="error-summary"/>
</xf:action>

See also

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 2024.1]
Enhanced validation in Form Builder and Form Runner