Extension API

Search…
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.
Extensibility
Integration
Last modified 1yr ago
Copy link
On this page
Availability
Introduction
Setting up an XBL component
Custom Form Settings tab
Setup
The XBL component
Responding to events
Custom Control Settings tab
Setup
The XBL component
Responding to events