Extension API

Availability

Since Orbeon Forms 2016.1.

Introduction

Form Builder exposes the following developer extension API:

• API to add a custom Form Settings tab

• API to add a custom Control Settings tab

Each extension is implemented with an XBL component. The component interacts with the enclosing dialog via events.

Setting up an XBL component

First, make sure you have chosen a prefix-to-namespace mapping for your components, as explained in Automatic inclusion of XBL bindings.

Below, we assume the following example mapping:

<property
  as="xs:string"
  name="oxf.xforms.xbl.mapping.acme"
  value="http://www.acme.com/xbl"/>

In practice, you would probably choose a prefix different from acme, and a namespace different from http://www.acme.com/xbl.

For more on XBL components, see XBL documentation.

Custom Form Settings tab

Setup

In order to add a custom Form Settings tab, the following property must be set to a non-blank value:

<property
  as="xs:string"
  name="oxf.fb.extension.form-settings"
  value="acme:form-settings"/>

Here, the value acme:form-settings refers to the XBL component implementing the custom tab:

• acme is the prefix you have mapped with the oxf.xforms.xbl.mapping.acme property above

• form-settings is the name you give your XBL component (it doesn't have to be form-settings)

The XBL component

You then create the file implementing the component under:

WEB-INF/resources/xbl/acme/form-settings/form-settings.xbl

Here is a template for the new XBL component:

<xbl:xbl xmlns:xh="http://www.w3.org/1999/xhtml"
         xmlns:xf="http://www.w3.org/2002/xforms"
         xmlns:xs="http://www.w3.org/2001/XMLSchema"
         xmlns:xxf="http://orbeon.org/oxf/xml/xforms"
         xmlns:fr="http://orbeon.org/oxf/xml/form-runner"
         xmlns:xbl="http://www.w3.org/ns/xbl"
         xmlns:xxbl="http://orbeon.org/oxf/xml/xbl"

         xmlns:acme="http://www.acme.com/xbl">

    <xbl:binding element="acme|form-settings" id="acme-form-settings">
        <xbl:handlers>
            <xbl:handler event="fb-initialize" phase="target">

                <!-- Example: access the form instance root -->
                <xf:var name="root" value="event('form-instance')"/>

                <!-- Further initialization -->

            </xbl:handler>
            <xbl:handler event="fb-apply" phase="target">

                <!-- Example: access the form instance root -->
                <xf:var name="root" value="event('form-instance')"/>

                <!-- Further code to save settings  -->

            </xbl:handler>
        </xbl:handlers>
        <!-- Local models -->
        <xbl:implementation>
            <xf:model>

                <!-- Local instance -->
                <xf:instance>
                    <some-local-instance/>
                </xf:instance>

                <!-- Further model content -->

            </xf:model>
        </xbl:implementation>
        <!-- View template -->
        <xbl:template>
            <xh:div>
                This will appear as the tab's content.
            </xh:div>
        </xbl:template>
    </xbl:binding>

</xbl:xbl>

Responding to events

Events dispatched

Form Builder dispatches events to the component, following a predefined lifecycle:

• fb-initialize is dispatched to initialize the tab when the dialog shows.

• fb-apply is dispatched to save the settings, if any, to the form definition.

Handlers for these events can access the form definition and read from / write to it. Component authors have to be very careful not damaging the form definition in the process.

Event parameters

fb-initialize and fb-apply both take the following parameters:

Parameter Name	Type	Value
form	element(xh:html)	root element of the form definition
form-instance	element(form)	root element of the form definition's form instance
form-metadata	element(metadata)	root element of the form definition's form metadata

Custom Control Settings tab

Setup

In order to add a custom Control Settings tab, the following property must be set to a non-blank value:

<property
  as="xs:string"
  name="oxf.fb.extension.control-settings"
  value="acme:control-settings"/>

Here, the value acme:control-settings refers to the XBL component implementing the custom tab:

• acme is the prefix you have mapped with the oxf.xforms.xbl.mapping.acme property above

• control-settings is the name you give your XBL component (it doesn't have to be control-settings)

The XBL component

You then create the file implementing the component under:

WEB-INF/resources/xbl/acme/control-settings/control-settings.xbl

For instance, see control-settings.xbl, an example of custom Control Settings that lets form authors enter, for each control, a "question identifier", which value is stored in an attribute of the form data, on the element corresponding that corresponds to the current control.

For an example template, see above for acme:form-settings.

Responding to events

Events dispatched

Form Builder dispatches the following events to the component:

• fb-initialize is dispatched to initialize the tab when the dialog shows.

• fb-apply is dispatched to save the settings, if any, to the form definition.

Handlers for these events can access the form definition and read from / write to it. Component authors have to be very careful not damaging the form definition in the process.

Event parameters

fb-initialize and fb-apply both take the following parameters:

Parameter Name	Type	Value
form	element(xh:html)	root element of the form definition
form-instance	element(form)	root element of the form definition's form instance
form-metadata	element(metadata)	root element of the form definition's form metadata
data-holders	element()*	all data holders for the given control

In addition, fb-initialize takes the following parameters:

Parameter Name	Type	Value
original-control-id	xs:string	original control id, such as first-name-control
original-control-name	xs:string	original control name, such as first-name

In addition, fb-apply takes the following parameters:

Parameter Name	Type	Value
control-name	xs:string	new control name, such as first-name

Between fb-initialize and fb-apply, the control name (and id) might have been changed in the dialog by the user. The original-control-name and control-name parameters reflect that change when needed.