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
  • Introduction
  • Control events
  • xxforms-visible
  • xxforms-hidden
  • Document events
  • xxforms-refresh-done
  • xxforms-state-restored
  • Instance events
  • xxforms-value-changed
  • xxforms-valid
  • xxforms-invalid
  • Model events
  • xxforms-instances-ready
  • Dialog control events
  • xxforms-dialog-open
  • xxforms-dialog-close
  • Repeat control events
  • xxforms-nodeset-changed
  • xxforms-index-changed
  • xxforms-iteration-moved
  • Upload control events
  • xxforms-upload-start
  • xxforms-upload-cancel
  • xxforms-upload-done
  • xxforms-upload-error
  • See also
  1. XForms
  2. Events

Extension events

PreviousKeyboard eventsNextExtension context information

Last updated 3 years ago

Introduction

This page documents extension events, that is events which are not part of the XForms specifications. Such events, by convention, start with the prefix xxforms-.

Control events

xxforms-visible

[SINCE Orbeon Forms 2018.1]

  • Dispatched in response to: control becoming relevant and not hidden, or control becoming visible following xf:toggle

  • Target: control

  • Bubbles: Yes

  • Cancelable: No

  • Context Info: Same as other UI events

When using <xf:switch> without also setting the xxf:xforms11-switch attribute or property to true, controls in non-visible switch cases remain relevant. This means that one cannot rely on xforms-enabled or xforms-disabled to track whether the control is really active for the user. xxforms-visible and xxforms-hidden (below) allow making that distinction.

See also .

xxforms-hidden

[SINCE Orbeon Forms 2018.1]

  • Dispatched in response to: control becoming non-relevant while not hidden, or control becoming hidden following xf:toggle

  • Target: control

  • Bubbles: Yes

  • Cancelable: No

  • Context Info: Same as other UI events

Document events

xxforms-refresh-done

[SINCE Orbeon Forms 2018.1]

  • Dispatched in response to: UI refresh has completed, including dispatching refresh events

  • Target: #document

  • Bubbles: Yes

  • Cancelable: No

  • Context Info: None

This event is dispatched to #document as the last action performed during a UI refresh.

You can listen to it with:

<xf:action 
    event="xxforms-refresh-done" 
    observer="#document">
    ...
</xf:action>

xxforms-state-restored

[SINCE Orbeon Forms 2017.2]

  • Dispatched in response to: form state restored from the XForm state store

  • Target: #document

  • Bubbles: No

  • Cancelable: No

  • Context Info: None

The xxforms-state-restored event is dispatched to the #document element when the form state is restored from the XForm state store. This can happen in the following case:

  1. The form hasn't received updates from the client for a long time, has been evicted from the memory cache and stored into the state store, and is finally restored from the state store when the client issues a new update.

Example:

<xf:action
    event="xxforms-state-restored"
    observer="#document"
    target="#document">

    <xf:message>State restored.</xf:message>

</xf:action>

Instance events

xxforms-value-changed

  • Dispatched in response to: value changed in an instance

  • Target: <xf:instance> element

  • Bubbles: Yes

  • Cancelable: Yes

  • Context Info:

    • event('node') as node(): element or attribute node whose value has changed

    • event('old-value') as xs:string: previous value

    • event('new-value') as xs:string: new value

The xxforms-value-changed event is dispatched to an instance when an element or attribute value is changed in that instance, namely through the following mechanisms:

  • calculate or xxf:default MIP

  • <xf:setvalue> action

  • value of a bound control changed by the user

  • submission result with replace="text"

Example:

<html xmlns:xforms="http://www.w3.org/2002/xforms"
      xmlns:ev="http://www.w3.org/2001/xml-events"
      xmlns="http://www.w3.org/1999/xhtml">

    <head>
        <xf:model>
            <xf:instance id="table">
                <table xmlns=""/>
            </xf:instance>
        </xf:model>
    </head>
    <body>
       <xf:message ev:event="xxforms-value-changed" ev:observer="table">Changed!</xf:message>
        <xf:input ref="instance()">
            <xf:label>Change me:</xf:label>
        </xf:input>
    </body>
</html>

xxforms-valid

  • Dispatched in response to: instance being valid after validation

  • Target: <xf:instance> element

  • Bubbles: Yes

  • Cancelable: Yes

  • Context Info: None

The xxforms-valid event is dispatched to an instance after validation if it is valid.

xxforms-invalid

  • Dispatched in response to: instance being invalid after validation

  • Target: <xf:instance> element

  • Bubbles: Yes

  • Cancelable: Yes

  • Context Info: None

The xxforms-invalid event is dispatched to an instance after validation if it is invalid.

Model events

xxforms-instances-ready

[SINCE Orbeon Forms 2017.1]

  • Dispatched in response to: model initialization

  • Target: <xf:model> element

  • Bubbles: Yes

  • Cancelable: No

  • Context Info: None

The xxforms-instances-ready event is dispatched to a model upon model initialization, after all model instances are loaded but before the initial rebuild, recalculate and revalidate. Therefore this event takes place after a model's xforms-model-construct but before a model's xforms-model-construct-done.

This event should rarely be needed.

Dialog control events

xxforms-dialog-open

  • Dispatched in response to: xxf:show action

  • Target: <xxf:dialog> element

  • Bubbles: Yes

  • Cancelable: Yes

  • Context Info: None

The xxforms-dialog-open event is dispatched to a dialog in response to running the <xxf:show> action targeting that dialog.

You can respond to this event before the dialog opens, for example to perform initialization of data:

<xxf:dialog id="hello-dialog">
  <xh:div>
    Hello!
  </xh:div>
  <xf:setvalue 
    ev:event="xxforms-dialog-open" 
    ref="..." 
    value="..."/>
</xxf:dialog>

You can set the focus on a specific control of the dialog with a setfocus action on the target or bubbling phase of this event:

<xf:setfocus 
    ev:event="xxforms-dialog-open" 
    control="my-control">

When the dialog opens upon receiving the xxforms-dialog-open event, it sets the focus on the first relevant, non-readonly control. This means that in general you don't need to use an explicit setfocus action.

xxforms-dialog-close

  • Dispatched in response to: xxf:hide action

  • Target: <xxf:dialog> element

  • Bubbles: Yes

  • Cancelable: Yes

  • Context Info: None

The xxforms-dialog-close event is dispatched to a dialog in response to:

  • running the <xxf:hide> action targeting that dialog

  • the user closing the dialog with the dialog close box, if present

Repeat control events

xxforms-nodeset-changed

  • Dispatched in response to: node-set changed on <xf:repeat>

  • Target: <xf:repeat> element

  • Bubbles: Yes

  • Cancelable: Yes

  • Context Info:

    • event('xxf:from-positions') as xs:integer*

      • previous positions of all the iterations that moved

    • event('xxf:to-positions') as xs:integer*

      • new positions of all the iterations that moved, in an order matching event('xxf:from-positions')

    • event('xxf:new-positions') as xs:integer*

      • positions of all newly created iterations

The xxforms-nodeset-changed event allows you to detect changes to a repeat node-set:

  • Nodes added to the nodeset, unless the nodeset was empty

  • Nodes reordered

This event is not dispatched when the repeat control becomes relevant or non-relevant. (A repeat control is considered non-relevant if its node-set is empty.)

Example:

<xf:group>
    <xxf:script ev:target="my-repeat" ev:event="xxforms-nodeset-changed xforms-enabled xforms-disabled">
        alert("Nodeset changed!");
    </xxf:script>
    <xf:repeat ref="record" id="my-repeat">
        ...
    </xf:repeat>
</xf:group>

In this example:

  • The ev:target attribute ensures that this particular handler only catches events for my-repeat, in case there are some nested repeats or some other repeats within the group.

  • The ev:event attribute lists not only xxforms-nodeset-changed event, but also the xforms-enabled and xforms-disabled event so the event runs when the nodeset goes from empty to non-empty or from non-empty to empty.

We recommend that you put the handler for xxforms-nodeset-changed outside the `` element, as shown in the example above. This ensures that, in case the repeat node-set becomes empty, actions associated with your event handler will still execute within a non-empty XPath context.

If nodes related to a repeat are inserted with xf:insert or xf:delete (including instance replacement upon submission), you could detect changes to the repeat node-set with XForms 1.1 using xforms-insert and xforms-delete events on instances. However these events are harder to use in this scenario, and will not catch situations where the repeat nodeset changes without insertions / deletions.

Currently, we interpret handlers placed directly within <xf:repeat> as being attached to a particular repeat -iteration*, not to the repeat element itself. This means you can write things like:

<xf:repeat ref="value" id="my-repeat">
    <xf:action ev:event="my-event">
        <xxf:variable name="position" select="position()"/>
        <xf:setvalue ref="." value="$position"/>
    </xf:action>
    ...
</xf:repeat>

The context size is the size of the repeat nodeset, and the context position that of the current iteration. Things work as if within the repeat you had an implicit group, which is in fact now how XForms 1.1 specifies repeat.

Now the question is: what happens if you dispatch an event to <xf:repeat> itself?

We propose the current solution:

  • if an event targets <xf:repeat>, then instead we dispatch it to the current repeat iteration, setting the appropriate XPath context for handlers associated with the iteration

  • in the case where there is no repeat iteration (empty repeat nodeset), the XPath context becomes empty

xxforms-index-changed

  • Dispatched in response to: index changed on <xf:repeat>

  • Target: <xf:repeat> element

  • Bubbles: Yes

  • Cancelable: Yes

  • Context Info:

    • event('xxf:old-index') as xs:integer: previous index

    • event('xxf:new-index') as xs:integer: new index

The xxforms-index-changed event allows you to detect changes to a repeat index.

<xf:repeat ref="value" id="my-repeat">
    <xf:action ev:event="my-event">
        <xxf:variable name="position" select="position()"/>
        <xf:setvalue ref="." value="$position"/>
    </xf:action>
    ...
</xf:repeat>

The xxforms-index-changed event is not dispatched during control creation, only when the index changes. In order to obtain the index during creation, you can attach a listener for xforms-enabled to the <xf:repeat> element and use the index() or xxf:index() function to obtain that repeat's initial index:

<xf:group>
    <xf:repeat ref="item" id="my-repeat">
        <!-- Test handler with ev:target="#observer" -->
        <xf:action ev:event="xforms-enabled" ev:target="#observer">
            ... use index('my-repeat') or xxf:index() here ...
        </xf:action>
    </xf:repeat>
    <!-- Test handler with ev:target -->
    <xf:action ev:event="xforms-enabled" ev:target="my-repeat">
        ... use index('my-repeat') here ...
    </xf:action>
</xf:group>

xxforms-iteration-moved

  • Dispatched in response to: iteration containing the control has changed since the last refresh or the time the iteration was first created

  • Target: control element

  • Bubbles: No

  • Cancelable: Yes

  • Context Info: None

The xxforms-iteration-moved event is dispatched during refresh, just after xforms-value-changed (if dispatched).

This event is not dispatched when the repeat control becomes relevant or non-relevant.

NOTE: A repeat control is considered non-relevant if its node-set is empty.

The iteration in which a control is present can change when repeat node-sets change as a consequence of inserted nodes, for example.

This event is useful for example to run xxf:script actions to update client-side data in response to moved iterations. Here is an example from the fr:currency implementation:

<xf:input ref="$result">
    <xxf:script id="xf-ch" ev:event="xforms-value-changed xxforms-iteration-moved">
        YAHOO.xbl.fr.Currency.instance(this).update();
     </xxf:script>
    <xxf:script id="xf-ro" ev:event="xforms-readonly">YAHOO.xbl.fr.Currency.instance(this).readonly();</xxf:script>
    <xxf:script id="xf-rw" ev:event="xforms-readwrite">YAHOO.xbl.fr.Currency.instance(this).readwrite();</xxf:script>
</xf:input>

NOTE: This event doesn't bubble, so event listeners must directly observe the controls receiving the event.

Upload control events

xxforms-upload-start

  • Dispatched in response to: upload started on the client

  • Target: <xf:upload> element

  • Bubbles: Yes

  • Cancelable: Yes

  • Context Info: None

xxforms-upload-cancel

  • Dispatched in response to: upload canceled by user on the client

  • Target: <xf:upload> element

  • Bubbles: Yes

  • Cancelable: Yes

  • Context Info: None

xxforms-upload-done

  • Dispatched in response to: upload completed on the server

  • Target: <xf:upload> element

  • Bubbles: Yes

  • Cancelable: Yes

  • Context Info:

    • event('filename') as xs:string

      • the untrusted filename sent by the browser

      • for example MyImage.png

    • event('content-type') as xs:string

      • the untrusted content type sent by the browser

      • for example image/png

    • event('content-length') as xs:string

      • the untrusted content length sent by the browser

      • for example 33270

xxforms-upload-error

  • Dispatched in response to: upload ended with an error

  • Target: <xf:upload> element

  • Bubbles: Yes

  • Cancelable: Yes

  • Context Info:

    • event('xxf:error-type') as xs:string

      • size-error if the upload was too large

      • upload-error if the cause of the error is unknown

      • NOTE: other error types may be added in the future

    • event('xxf:permitted') as xs:integer?

      • if size-error, and if known, maximum upload size allowed by configuration

    • event('xxf:actual') as xs:integer?

      • if size-error, and if known, actual upload size detected

See also

See also .

The form has been to another server.

UI refresh events
UI refresh events
replicated
Standard support
UI refresh events
Keyboard events
Extension context information
Other event extensions