Rationale

Some components do not require any custom JavaScript code, for example components which combine other controls (such as a date components made of separate input fields or dropdown menus). In such cases, you implement all the logic with XForms.

On the other hand some components are introduced to encapsulate functionality mainly implemented in JavaScript. Orbeon Forms provides an easy way to interface with the JavaScript side. Each JavaScript-based component must define a JavaScript class used to handle the component's lifecycle as well as hold custom data and functions. This class is called the component's companion class. One instance of this class is created by Orbeon Forms for each instance of relevant (visible) control. We call these instances companion instances.

Directory layout

You place your JavaScript files alongside your XBL file. See Directory layout for details.

To include a companion JavaScript file, use the <xbl:script> element directly within the <xbl:xbl> element:

<xbl:xbl
    xmlns:xf="http://www.w3.org/2002/xforms"
    xmlns:acme="http://www.acme.com/xbl"
    xmlns:xbl="http://www.w3.org/ns/xbl">
​
    <xbl:script src="/xbl/acme/multi-tool/multi-tool.js"/>
​
    <xbl:binding
        id="acme-multi-tool"
        element="acme|multi-tool">
​
        ...binding definition here...
​
    </xbl:binding>
</xbl>

Creating and declaring a companion class

With Orbeon Forms 2016.1 and newer

Orbeon Forms 2016.1 provides a simple way to declare a companion class. Here is the overall structure:

(function() {
​
    // Optional shortcut to jQuery
    var $ = ORBEON.jQuery;
​
    // Register your companion class by its binding name
    ORBEON.xforms.XBL.declareCompanion('acme|multi-tool', {
​
        // Your custom data goes here
        myField: null,
​
        init: function() {
            // Perform your JavaScript initialization here
        },
        destroy: function() {
            // Perform your JavaScript clean-up here
        },
        xformsUpdateReadonly: function(readonly) {
            // Orbeon Forms calls this when the control's readonly status changes
        },
        xformsUpdateValue: function(newValue) {
            // Orbeon Forms calls this when the control's value changes
        },
        xformsGetValue: function() {
            // Orbeon Forms calls this to obtain the control's value
        },
        xformsFocus: function() {
            // Orbeon Forms calls this when the control is handed focus
        },
        // Your custom functions go here
        myFunction: function() {
            ...
        },
    });
})();

The first parameter to declareCompanion() must match the component's binding name, for example:

• if your component's binding is acme|multi-tool

  • pass acme|multi-tool

  • you place the JavaScript file under /xbl/acme/multi-tool/multi-tool.js

• if your component's binding is foo|bar

  • pass foo|bar

  • you place the JavaScript file under /xbl/foo/bar/bar.js

With Orbeon Forms 4.10 and earlier

In the JavaScript file corresponding to your component, declare a companion class as follows:

(function() {
​
    // Optional shortcut to jQuery
    var $ = ORBEON.jQuery;
​
    YAHOO.namespace("xbl.acme");
    YAHOO.xbl.acme.MultiTool = function() {};
    ORBEON.xforms.XBL.declareClass(YAHOO.xbl.acme.MultiTool, "xbl-acme-multi-tool");
    YAHOO.xbl.acme.MultiTool.prototype = {
​
        // Your custom data goes here
        myField: null,
​
        init: function() {
            // Perform your JavaScript initialization here
        },
        destroy: function() {
            // Perform your JavaScript clean-up here
        },
        xformsFocus: function() {
            // Orbeon Forms calls this when the control is handed focus
        },
        // Your custom functions go here
        myFunction: function() {
            ...
        },
​
        ...
    };
})();

• YAHOO.namespace("xbl.acme") defines a namespace for your class. All the XBL components components that ship with Orbeon Forms are in the xbl.fr namespace. If you are defining a component for your company or project named Acme, you could use the namespace xbl.acme.

• ORBEON.xforms.XBL.declareClass() defines your class as an XBL class:

  • It takes 2 parameters: your class, and the CSS class found on the outermost HTML element that contains the markup for your components. This element is generated by Orbeon Forms, and the class name is derived from the by-name binding of your <xbl:binding>. For example, if the binding is acme|multi-tool, the class name is xbl-acme-multi-tool.

The companion class

Both declareCompanion() and declareClass() create a JavaScript class and:

• add a static instance() method.

  • This is a factory method, which you use to get or create an object corresponding to the "current" component.

  • It returns an instance of the JavaScript class corresponding to the "current" component from which it is called.

  • It creates class instances as necessary, keeping track of existing instances and maintaining a 1-to-1 mapping between instances of the XBL component in the form and instance of your JavaScript class.

• add a container attribute.

  • In your JavaScript code, you can refer to this.container to retrieve the outermost HTML element corresponding to your component.

For example, if you know you have an input field with the class acme-my-input inside your component, you get the HTML element corresponding to that input with the following jQuery:

$(this.container).find('.acme-my-input')[0]

Summary of companion class methods

The init() method is not new in Orbeon Forms 2016.1, but when using the javascript-lifecycle mode it is called automatically. Prior to Orbeon Forms 2016.1, or when not using the javascript-lifecycle mode, it is called either via XForms event handlers, or as a side-effect of calls to setFocus() or enabled().

Calling methods upon XForms events

With Orbeon Forms 2016.1 and newer

You can call a JavaScript method defined in your JavaScript class when an XForms event occurs. For example, to call the myFunction() method on xforms-enabled, write:

<xxf:action type="javascript" event="xforms-enabled">
    ORBEON.xforms.XBL.instanceForControl(this).myFunction();
</xxf:action>

With Orbeon Forms 4.10 and earlier

With Orbeon Forms 4.10 and earlier, you obtain the class using the JavaScript namespaces you declared alongside the class, and directly call the instance() factory function:

<xxf:action type="javascript" event="xforms-enabled">
    YAHOO.xbl.acme.MultiTool.instance(this).myFunction();
</xxf:action>

Support for the external-value mode

Introduction

[SINCE Orbeon Forms 2016.1]

When the external-value mode is enabled, the following two methods must be provided:

• xformsUpdateValue()

• xformsGetValue()

For an example, see the implementation of the fr:code-mirror component: code-mirror.xbl and code-mirror.js.

The xformsUpdateValue method

The XForms engine calls this method:

• if the javascript-lifecycle and the external-value modes are enabled, just after the control is initialized,

• when the internal value of the control changes,

• and in response to calls to ORBEON.xforms.Document.setValue().

Method parameters

xformsUpdateValue() receives a string and must update the associated JavaScript control, making the value accessible to the user.

Method return value

xformsUpdateValue() must return:

• If it sets value is synchronously: undefined (or not return anything).

• If it sets value is asynchronously: a jQuery deferred object whose done() method must be called once the value is known to have been fully applied. For instance:

    var editor   = this.editor;
    var deferred = $.Deferred();
    setTimeout(function() {
        editor.setValue(newValue);
        deferred.resolve();
    }, 0);
    return deferred.promise();

  This allows the XForms engine to know when it is safe to call xformsGetValue() after a new value has been set.

[SINCE Orbeon Forms 2020.1]

In addition to a jQuery deferred object (with a done() method), you can also return a JavaScript Promise object (with a then() method). The latter is the recommended way since JavaScript promises are implemented natively by all major browsers (except IE 11, but Orbeon Forms includes a polyfill for IE 11).

The xformsGetValue method

The XForms engine calls this method when:

• it needs the control's value,

• and in response to calls to ORBEON.xforms.Document.getValue().

xformsGetValue() returns a string obtained from the associated JavaScript control.

External value serialization/deserialization

[SINCE Orbeon Forms 2019.1]

By default, the external value exchanged with the client is identical to the storage value of the component.

By using the xxbl:serialize-external-value and xxbl:deserialize-external-value attributes on <xbl:binding>, you can create XPath expressions that transform the external value back and forth.

This is useful if the value must contain more than the storage value of the component. For example the fr:number component uses this to communicate a display value, an edit value and a decimal separator to the client.

<xbl:binding
    id="fr-number"
    element="
        fr|number,
        xf|input:xxf-type('xs:decimal'),
        xf|input:xxf-type('xs:integer')"
​
    xxbl:mode="... value external-value javascript-lifecycle ..."
    xxbl:serialize-external-value="... expression serializing the value to the client... "
    xxbl:deserialize-external-value="... expression deserializing the external value from the client... "
>
... rest of the binding...

For xxbl:serialize-external-value:

• XPath context item: XPath string of the control's storage value

• Expression result: XPath string to send to the client's companion class's xformsUpdateValue() method

For xxbl:deserialize-external-value:

• XPath context item: XPath string provided by the client's companion class's xformsGetValue() method

• Expression result: XPath string to use as the control's storage value

Support for the javascript-lifecycle mode

Introduction

[SINCE Orbeon Forms 2016.1]

When the javascript-lifecycle mode is enabled, the following methods should be provided:

• init()

• destroy()

• xformsUpdateReadonly()

NOTE: The XForms engine does not call these methods if they are not present.

On the JavaScript side, the lifecycle of a companion instance does not exactly follow that of the XForms controls when repeats are involved.

For an example, see the implementation of the fr:code-mirror component.

The init method

The init() method is called when the control becomes relevant, including:

• when the page first loads and the control is initially relevant

• when the control becomes relevant at a later time

• when a new repeat iteration is added

• when xxf:full-update or xxf:dynamic replace an entire block of HTML on the client

The destroy method

The destroy() method is called when the control becomes non-relevant, including:

• when the control becomes non-relevant after the page has loaded

Since Orbeon Forms 2016.1, it is not called:

• when a repeat iteration is removed

• when xxf:full-update or xxf:dynamic replace an entire block of HTML on the client

The assumption is that, when HTML elements are removed from the browser DOM, the associated JavaScript resources are garbage-collected. This means that you have to be careful about clean-up of event handlers in particular in such cases.

The xformsUpdateReadonly method

The xformsUpdateReadonly() method is called when the control's readonly status changes.

It takes a boolean parameter set to true if the control becomes readonly and to false if the control becomes readwrite.

It is not called just after the control is initialized.

Read-only parameters

So your JavaScript can access the current value of parameters and be notified when their value changes, include the oxf:/oxf/xslt/utils/xbl.xsl XSL file, and call xxbl:parameter() function for each parameter, as in:

<xbl:xbl>
    <xbl:script src="/xbl/orbeon/currency/currency.js"/>
    <xbl:binding id="fr-currency" element="fr|currency">
        <xbl:template xxbl:transform="oxf:unsafe-xslt">
            <xsl:transform version="2.0">
                <xsl:import href="oxf:/oxf/xslt/utils/xbl.xsl"/>
                <xsl:template match="/*">
                    ...
                    <xsl:copy-of select="xxbl:parameter(., 'prefix')"/>
                    <xsl:copy-of select="xxbl:parameter(., 'digits-after-decimal')"/>
                    ...
                </xsl:template>
            </xsl:transform>
        </xbl:template>
    </xbl:binding>
</xbl:xbl>

The arguments of xxbl:parameter() are:

1. The element corresponding to your component, e.g. the <fr:currency> element written by the user of your component. If your template matches on /*, this will be the current node.

2. The name of the parameter.

Then in JavaScript, you can access the current value of the property with:

var prefixElement =
    $(this.container).find('.xbl-fr-currency-prefix')[0];
​
var prefix =
    ORBEON.xforms.Document.getValue(prefixElement.id);

Whenever the value of a parameter changes, a method of your JavaScript class is called. The name of this method is parameterFooChanged if "foo" is the name of your property. Parameters names are in lowercase and use dash as a word separator, while the method names use camel case. E.g. if your parameter name is digits-after-decimal, you will defined a method parameterDigitsAfterDecimalChanged.

Sending events from JavaScript

You can dispatch custom events to bindings from JavaScript using the ORBEON.xforms.Document.dispatchEvent() function. If you are calling it with custom events, make sure you are allowing the custom event names on the binding first:

<xbl:binding xxf:external-events="acme-super-event acme-famous-event">
    <xbl:handlers>
        <xbl:handler event="acme-super-event" phase="target">
            ...
        </xbl:handler>
    </xbl:handlers
    ...
</xbl:binding>