Form Runner JavaScript API
Last updated
Last updated
You can get a reference to an object representing a Form Runner form with the getForm()
function:
The formIdOrElem
parameter is described .
The formIdOrElem
parameter used in APIs can be:
missing or undefined
: this searches for the first Orbeon Forms form on the page
a string
: this is the namespaced id of the form
an HTML element: this is the HTML form element, or a descendant or an HTML form element
If the form is not found, null
is returned. If found, an object is returned, which contains methods described below.
FormRunnerForm
objectThe findControlsByName()
function returns the HTML element(s) corresponding to the given Form Runner control name.
NOTE: The control must be visible or it will not be found. In particular, if the control is in a hidden wizard page, the control will not be found.
A Form Runner control name is the name entered by the form author in Form Builder. Examples:
first-name
street-address
controlName
Yes
string
The name of the Form Runner control.
If no control is found, an empty array is returned.
If there are multiple controls with the same name, the array will contain multiple elements. This can happen in the following cases:
when controls are repeated, for example in a repeated grid or section
when controls appear in the main form and section template and/or in different section templates
On the other hand, if the control exists but is not shown at a given time, for example if it is in a hidden wizard page, the array will be empty.
Example:
The setControlValue()
function allows you to set the value of a Form Runner control.
controlName
Yes
string
The name of the Form Runner control
2023.1
controlValue
Yes
string
| int
The value to set
2023.1 (2024.1.2 for int
)
index
No
int[]
| undefined
If specified, and the control is repeated, the 0-based position of the control
2023.1.1
Here is how to set the value of a text field called my-field
to the value "Hello!":
For single selection controls, pass the index of the item to select:
For multiple selection controls, pass a space-separated string of item indexes:
The following controls are supported:
Text field
Plain text area
Dropdown
Checkboxes
Radio buttons
Number
Currency
Date
Time
The setControlValue()
function returns either:
a JavaScript Promise
which resolves when the value is set on the server
or undefined
if
the control is not found
the control is an XBL component which doesn't support the JavaScript lifecycle
If a control is repeated, use the optional index
parameter to specify which repetition to set. The index is 0-based.
For single-selection controls, you can also pass an integer value rather than a string:
The getControlValue()
function allows you to get the value of a Form Runner control.
controlName
Yes
string
The name of the Form Runner control
2024.1.2
index
No
int[]
| undefined
If specified, and the control is repeated, the 0-based position of the control
2024.1.2
Here is how to get the value of a text field called my-field
:
The getControlValue()
function returns either:
a string
with the value of the control
or undefined
if
the control is not found
the control is an XBL component which doesn't support the JavaScript lifecycle
The activateControl()
function allows you to activate a Form Runner control. This is useful to activating buttons that are present within the form (as opposed to process buttons, which are typically placed at the bottom of the form). However, you can also activate other controls, in particular Text Fields.
controlName
Yes
string
The name of the Form Runner control
The following controls are supported:
Text field (as if the user presses the Return or Enter key)
Button
The activateControl()
function returns either:
a JavaScript Promise
which resolves when the activation has run on the server
or undefined
if
the control is not found
the control is not a trigger or input control
Orbeon Forms supports the notion that form data can be "safe" or not: specifically, it is safe if it's been saved to a database.
This function allows you to tell whether the data is safe or not.
Example:
Process buttons are typically buttons that are not directly part of the form, but placed at the bottom of the form. They include functions such as "Save", "Send", "Next", etc.
You can activate a process button with this function by specifying the button name. Example:
You add a callback function on the client using:
name
Yes
string
Name passed to the server-side callback()
action
fn
Yes
() => void
Callback function to be called on the client
You remove a callback function on the client using:
The name
and fn
parameters must be the same as those passed to addCallback()
.
[SINCE Orbeon Forms 2017.2]
The findControlsByName()
function returns the HTML element(s) corresponding to the given Form Runner control name.
controlName
Yes
string
The name of the Form Runner control.
formIdOrElem
No
formIdOrElem: string | HTMLElement
Prefer using first the getForm()
function, and then, on the object returned, the findControlsByName()
function.
For example, here is how to set the value of a text field called my-field
to the value "Hello!":
NOTE: For dropdowns created with Form Builder, the API does not provide direct support as of Orbeon Forms 2019.1. You can do it with the following JavaScript:
Where the value you pass corresponds to the position of the item starting at 0
.
Prefer using first the getForm()
function, and then, on the object returned, the setControlValue()
function.
[SINCE Orbeon Forms 2019.2]
formIdOrElem
No
formIdOrElem: string | HTMLElement
Prefer using first the getForm()
function, and then, on the object returned, the isFormDataSafe()
function.
[SINCE Orbeon Forms 2017.2]
The wizard.focus()
function sets keyboard focus on a Form Runner control by name, including toggling wizard pages first if needed.
controlName
Yes
string
The name of the Form Runner control.
repeatIndexes
No
array of Int
Repeat indexes.
This function doesn't have any effect if the control is readonly or non-relevant.
Example:
The optional repeatIndexes
parameter allows reaching controls within repeats. For example, with one level of
repeat:
accesses the second iteration of the comment
field.
Similarly, for nested repeats, you add as many elements in the array as there are nested repeats:
When repeatIndexes
is not specified, if the field is repeated, a single field is selected following the current
repeat indexes.
NOTE: This only supports the wizard's free
validation mode. lax
and strict
are not yet supported.
This now also works with the strict
and lax
validation modes. In these modes, the wizard will check whether the switch to the requested wizard page is allowed.
If so, it will switch and focus on the control.
If not, it will ignore the focus()
request.
[SINCE Orbeon Forms 2022.1]
For analytics purposes, it can be useful to capture when the user is interacting with the Error Summary.
You can do so with the errorSummary.addNavigateToErrorListener()
function:
Example:
The parameter to the function is an event object defined as follows:
The listener can be removed with removeNavigateToErrorListener()
by passing the same function object as parameter.
See also .
Form Runner simple processes now support a server action that allows client-side callback functions to be called.
See
You can set a control's value using the .
See