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
  • Creating keyboard shortcuts with the keypress event
  • Filtering on the event phase
  • Adding context information to events
  • Tunnelling of events properties
  • Allowing duplicate event in the event queue
  • Enhanced support for xforms-select and xforms-deselect
  • Targeting effective controls within repeat iterations
  • Multiple event names, observers and targets on event handlers
  • Catching all events
  • Specifying the current observer as target restriction
  • Observing the preceding sibling element
  • Phantom handlers
  • See also
  1. XForms
  2. Events

Other event extensions

PreviousExtension context informationNextActions

Last updated 1 year ago

Creating keyboard shortcuts with the keypress event

See .

Filtering on the event phase

XML Events 1 only supports filtering event handlers on a subset of the DOM Level 2 Events phases. Orbeon Forms extends that behavior and supports registering handlers that match on one of the 3 main event phases specified by DOM Level 2 Events: capture, target, and bubbling.

Orbeon Forms supports the following values for the phase attribute:

  • capture: only activate the handler during the capture phase (this is compatible with all the specifications)

  • default or unspecified: only activate the handler during the target or bubbling phase (this is compatible with XML Events 1 but not included in the current XBL 2 proposal)

  • target: only activate the handler during the target phase (this is not present in XML Events 1)

  • bubbling: only activate the handler during the bubbling phase (this is not present in XML Events 1)

NOTE: In the future, the XBL 2 default action phase could be integrated if considered desirable. It is hoped that the target and bubbling values will be supported in XML Events 2.

NOTE: In most cases, the phase attribute can be omitted, in which case the target or bubbling phase is matched. This allows placing a handler directly within a target element, or any of its ancestors, which are the most common use cases in XForms.

Adding context information to events

Orbeon Forms supports passing event context attributes with the XForms 2.0 <xf:property> child element. The actions supported are actions which directly cause an event to be dispatched:

  • <xf:dispatch>

  • <xf:send>

  • <xxf:show>

  • <xxf:hide>

Here is how you pass context attributes when executing an action:

<xf:dispatch name="rename-control" target="my-model">
    <xf:property name="control"      value="my/control"/>
    <xf:property name="control-name" value="'beverage-selection'"/>
</xf:dispatch>

NOTE: Prior to standard XForms support, the <xxf:context> child element was introduced for the same purpose and can still be used for backward compatibility. The select attribute can also be used in place of value.

<xf:property> supports the following two attributes:

name

Mandatory

Name of the context attribute.

value

Mandatory

XPath 2.0 expression determining the value of the context attribute.

In order to avoid confusion with standard XForms names, we recommend you use prefixed names if you use custom context information with standard event names (when supported). However, with custom event names, prefixing is not necessary.

Context attributes passed this way can be retrieved using the event() function:

<xf:action event="rename-control">
    <xf:setvalue ref="event('control')/@name" value="event('control-name')"/>
</xf:action>

NOTE: At the moment, with, <xf:dispatch>, only custom events support passing context attributes this way. Built-in events, such as xforms-value-changed, or DOMActivate, ignore nested <xf:property> elements.

Tunnelling of events properties

The xxf:tunnel="true attribute on <xf:property> allows the propagation, or tunnelling, of event properties in the following cases:

  • <xf:send>: the properties are tunneled to event handlers for the xforms-submit-error and xforms-submit-done events as well as event handlers for xxforms-action-error event dispatched while processing event handlers for those events

  • <xf:dispatch>: the properties are tunneled to event handlers for the xxforms-action-error event dispatched while processing event handlers for the event dispatched

Example with xforms-submit-done:

<xf:send submission="my-submission">
    <xf:property name="my-tunnel-property" value="42" xxf:tunnel="true"/>
</xf:send>
<xf:submission id="my-submission">
    <xf:action event="xforms-submit-done">
        <xf:message value="event('my-tunnel-property')"/>
    </xf:action>
</xf:submission>

Example with xxforms-action-error:

<xf:dispatch name="my-event" target="my-target">
    <xf:property name="divisor" value="0" xxf:tunnel="true"/>
</xf:dispatch>
<xf:group id="my-target">
    <xf:action event="my-event">
        <!-- Cause an action error -->
        <xf:setvalue ref="title" value="42 div event('divisor')"/>
    </xf:action>
    <xf:action event="xxforms-action-error">
        <xf:message value="event('divisor')"/>
    </xf:action>
</xf:group>

Allowing duplicate event in the event queue

[SINCE Orbeon Forms 2017.1]

Prior to Orbeon Forms 2017.1, the <xf:dispatch> action used with a delay value would always add all events to the event queue. This was not per the XForms specification, which says that events with the same name and effective target as ones already in the event queue are skipped.

Orbeon Forms 2017.1 rectifies that to follow XForms and skips duplicates. This change of default is usually not a problem.

To allow duplicates, the xxf:allow-duplicates="true" attribute is supported:

<xf:dispatch
    name="my-event"
    targetid="my-targetid"
    delay="10"
    xxf:allow-duplicates="true"/>

xxf:allow-duplicates is an AVT.

Enhanced support for xforms-select and xforms-deselect

[TODO: describe support for these events on xf:upload]

Targeting effective controls within repeat iterations

The following actions all support attributes resolving to a particular control:

  • <xf:dispatch> (target attribute)

  • <xf:setfocus> (control attribute)

  • <xf:toggle> (case attribute)

  • <xxf:show> (neighbor attribute)

When that control is within a repeat iteration, the actual control targetted is chosen based on the current set of repeat indexes. However, in some cases, it is useful to be able to target the control within a particular iteration. This is achieved with the xxf:repeat-indexes extension attribute on these actions. This attribute takes a space-separated list of repeat indexes, starting with the outermost repeat. Example:

<!-- Repeat hierarchy -->
<xf:repeat ref="todo-list">
    <xf:repeat ref="todo-item">
        <xf:switch>
             <xf:case id="edit-case">...</xf:case>
             <xf:case id="view-case">...</xf:case>
        </xf:switch>
    </xf:repeat>
</xf:repeat>

<xf:trigger>
    <xf:label>Toggle Me!</xf:label>
    <!-- Toggle the case within the 5th todo item of the 3rd todo list -->
    <xf:toggle event="DOMActivate" case="edit-case" xxf:repeat-indexes="3 5"/>
</xf:trigger>

Multiple event names, observers and targets on event handlers

  • For event: the handler is called if any of the specified events matches.

    <xf:action event="DOMFocusIn DOMFocusOut">
        <!-- Reacting to either the "DOMFocusIn" and "DOMFocusOut" events -->
        ...
    </xf:action>
  • For observer: the event handler is attached to all the observers specified.

    <xf:action event="DOMActivate" observer="my-input my-trigger">
        <!-- Observing both the "my-input" and "my-trigger" controls -->
        ...
    </xf:action>
  • For target: the handler is called if any of the specified targets matches.

    <xf:action event="xforms-submit-done" target="create-submission update-submission">
        <!-- Checking that either the "create-submission" and "update-submission" controls is a target -->
        ...
    </xf:action>

Catching all events

The special #all event name on event can be used to catch all events:

<xf:group>
    <!-- Stop propagation of all events -->
    <xf:action event="#all" propagate="stop"/>
    ...
</xf:group>

Specifying the current observer as target restriction

The special #observer target name on target can be used to specify that the listener must be activated only if the event target is the listener's observer:

<xf:group>
    <!-- Restrict activation to events dispatched to the group -->
    <xf:action event="my-event" target="#observer"/>
    ...
</xf:group>

In this example, this is identical to:`

<xf:group>
    <!-- Restrict activation to events dispatched to the group -->
    <xf:action event="my-event" phase="target"/>
    ...
</xf:group>

Observing the preceding sibling element

The observer attribute can be set to the value #preceding-sibling:

<xf:repeat ref="...">
    ...
</xf:repeat

<xf:action
  event="xforms-enabled xforms-disabled xxforms-index-changed xxforms-ref-changed"
  observer="#preceding-sibling"
  target="#observer">
    
</xf:action>

In this example, we observe events targeted to the repeat element just before the event handler.

This is useful in situations where it is not possible to explicitly set an id on a control, for example when doing complex things with XBL.

Phantom handlers

Event handler support the xxf:phantom="true" attribute to specify that the event handler is listening to events flowing across XBL scopes.

XForms events flow along XBL boundaries and are fully encapsulated. This attribute allows special consumers of events to have a global view of events flowing in the XForms page. Example:

<xf:action
  observer="my-observer"
  event="xforms-enabled"
  xxf:phantom="true">

In this example, the handler will catch events that happen not only in the current XBL scope, but also those in nested XBL scopes.

This is an advanced feature and should be used wisely. It is used in Orbeon Forms by the error summary (fr:error-summary) and by Form Builder.

[SINCE Orbeon Forms 2020.1]

xxf:phantom="true" handlers can be placed within repeats. This was not previously allowed.

See also

Note that the context attribute name cannot be a qualified name (QName), because this would not be compatible with . However, a QName can be used as custom event name.

The event, observer and target attributes, defined by the , only support one event name, observer, or target respectively. Orbeon Forms supports as an extension a list of space-separated values. The behavior is as follows:

The extensions above have been for inclusion in XML Events 2.

Keyboard events
DOM 2 Events
[SINCE Orbeon Forms 2023.1]
XML Events specification
requested
Standard support
UI refresh events
Keyboard events
Extension events
Extension context information