Orbeon Forms User Guide

XForms Reference: Extensions

1. Introduction

This part of the XForms reference documentation focuses on extensions over XForms provided by Orbeon Forms, as well as XForms engine configuration.

Please be sure to visit:

2. Placement of Controls and Models

XForms does not specify normatively where XForms controls and models must be placed within an HTML document. The convention is to place <xforms:model> elements within <xhtml:head>, and controls within <xhtml:body>. Orbeon Forms is more flexible on this:

  • <xforms:model> can be placed within <xhtml:head> as is usual, but also under <xhtml:body> and even nested within other XForms elements. For example:

    <xxforms:dialog id="my-dialog" model="my-dialog-model"><xforms:label>My Dialog</xforms:label><xforms:group>...</xforms:group><xforms:model id="my-dialog-model"><!-- Model used by the dialog -->...</xforms:model></xxforms:dialog>

    In this particular case, this allows you to write your dialog as a module in a completely separate file and to XInclude that file within your main form.

    At the moment, nested models behave exactly as if they were placed under <xhtml:head>. It is just a syntactic convenience to be able to place them within elements such as <xxforms:dialog>.

  • Attribute Value Templates (AVTs) can be placed on HTML elements outside <xhtml:body>.

    <xhtml:body lang="{instance('language')}">...</xhtml:body>

  • A single <xforms:output> control may be placed within <xhtml:title>. This allows dynamically changing the HTML document title using XForms.

    <xhtml:title><xforms:output value="instance('resources')/title"/></xhtml:title>
Note

Even though AVTs and <xforms:output> elements may be placed before any XForms model, they are still considered part of the XForms "view" of the XForms document and refer to data placed in models.

3. XForms 1.1 Support

3.1. Media Type for xforms:output

In XForms 1.0, xforms:output is only used to display text. However, XForms 1.1 supports a mediatype attribute on that element allowing display of other media types.

3.1.1. Image Types

For the <xforms:output> control to display an image, you need to:

  • Have a mediatype attribute on the <xforms:output>. That attribute must refer to an image mediatype, such as image/* or image/jpeg.

  • Use the value attribute on <xforms:output> or bind to the control to a node without type, with an xs:anyURI type or with an xs:base64Binary type.

The resulting value from the instance is interpreted either as a URI pointing to an image, or as a base64-encoded binary representation of the image. The image will display in place of the xforms:output. It is possible to dynamically change the image pointed to. For example:

<xforms:output mediatype="image/*" value="'/images/moon.jpg'"/>
<xforms:model><xforms:instance><image-uri/></xforms:instance><xforms:bind nodeset="image-uri" type="xs:anyURI"/></xforms:model>...<xforms:output mediatype="image/*" ref="image-uri"/>

The image URI may or may no be reachable from the client browser. Orbeon Forms hides this from the developer. For example, to upload and show an image:

<!-- Hide xforms:output when there is no URI available --><xforms:group ref="image[normalize-space() != '']"><!-- Image output --><xforms:output ref="." mediatype="image/*"><xforms:label/></xforms:output></xforms:group><!-- File chooser --><xforms:upload ref="image"><xforms:label/><xforms:filename ref="@filename"/><xforms:mediatype ref="@mediatype"/><xxforms:size ref="@size"/></xforms:upload>

In that example, the upload control stores a temporary URI pointing to a local file: resource. While this URI is not visible from the client web browser, the output control automatically proxies it so that the end user can see the image.

3.1.2. HTML Type

When an xforms:output control has a mediatype attribute with value text/html, the value of the node to which the control is bound is interpreted as HTML content. Consider the following XForms instance:

<xforms:instance id="my-instance"><form><html-content>This is in &lt;b&gt;bold&lt;/b&gt;!</html-content></form></xforms:instance>

You bind an xforms:output control to the html-content node as follows:

<xforms:output ref="instance('my-instance')/html-content" mediatype="text/html"/>

This will display the result as HTML, as expected: "This is in bold!". If the mediatype is not specified, the result would be instead: "This is in <b>bold</b>!". In the XForms instance, the HTML content must be escaped as text. On the other hand, the following content will not work as expected:

<xforms:instance><form><html-content>This is in in<b>bold</b>!</html-content></form></xforms:instance>
Note
When using a mediatype="text/html", an HTML <div> element will be generated by the XForms engine to hold the HTML data. As in HTML a <div> cannot be embedded into a <p>, if you have a <xforms:output mediatype="text/html"> control, you should not put that control into a <xhtml:p>.

3.2. origin Attribute on xforms:insert Action

Orbeon Forms supports the XForms 1.1 origin attribute on the xforms:insert action. This attribute allows specifying the source node to use as template. This allows storing templates separately from the node-set specified by the nodeset attribute. For example:

<xforms:insert nodeset="address" at="last()" position="after" origin="instance('template-instance')"/>

The template copied in this case comes from an XForms instance:

<xforms:instance id="template-instance"><address><street><number/><name-1/><name-2/></street><apt/><city/><state/><zip/></address></xforms:instance>

3.3. context Attribute on xforms:insert Action

Orbeon Forms supports the XForms 1.1 context attribute on the xforms:insert action. This attribute allows specifying a context for insertion, which along with the origin attribute allows inserting content into elements:

<xforms:insert context="instance('main-instance')/books" nodeset="book" origin="instance('book-instance')"/>

With original instances as follows:

<xforms:instance id="main-instance"><instance><books/></instance></xforms:instance><xforms:instance id="book-instance"><book><title>Cosmos</title><author>Carl Sagan</author></book></xforms:instance>

The result of a first insertion is:

<xforms:instance id="main-instance"><instance><books><book><title>Cosmos</title><author>Carl Sagan</author></book></books></instance></xforms:instance>

3.4. validate and relevant Attributes on <xforms:submission>

Orbeon Forms supports the XForms 1.1 validate and relevant attributes on <xforms:submission>. These boolean attributes disable processing of validation and relevance respectively for a given submission:

<xforms:submission id="my-submission" method="post" validate="false" relevant="false" resource="http://example.org/rest/draft/" replace="none"/>

For more information, please visit the XForms 1.1 specification.

3.5. serialization Attribute on <xforms:submission>

Orbeon Forms supports the XForms 1.1 serialization on <xforms:submission>. This is particularly useful to specify the value none with a get method:

<xforms:submission id="my-submission" method="get" serialization="none" resource="http://example.org/document.xml" replace="instance" instance="my-instance"/>

For more information, please visit the XForms 1.1 specification.

3.6. Preliminary support for asynchronous handling of <xforms:submission>

Orbeon Forms partially supports the XForms 1.1 mode="asynchronous" attribute on <xforms:submission>. The limitations are:

  • Asynchronous submissions in an Ajax request are delayed until after everything else in the request has run (including other submissions).

  • Asynchronous submissions are "fire and forget": they only work with replace="none" and no xforms-submit-done / xforms-submit-error events are dispatched.

  • All asynchronous submissions started during a given Ajax request run serially.

<xforms:submission id="test-submission" mode="asynchronous" ref="." method="put" resource="http://my.service.com/" replace="none"/>

For more information, please visit the XForms 1.1 specification.

Note

XForms 1.1 specifies that mode="asynchronous" should be the default, but due to the client-server nature of the Orbeon Forms XForms engine, Orbeon Forms still defaults to mode="synchronous".

3.7. Conditional Execution and Iteration of XForms Actions

Orbeon Forms supports the XForms 1.1 if and while attributes on XForms action elements. For more information, please visit the XForms 1.1 specification.

3.8. XForms 1.1 Functions

[TODO: List all XForms 1.1 functions implemented]

4. Extensions

4.1. Read-Only Mode

4.1.1. Making an Entire Instance Read-Only

You often want to present a form without allowing the user to enter data. An easy solution is to use the readonly MIP in the model. By making for example the root element of an instance read-only, all the controls bound to any node of that instance will appear read-only (because the read-only property is inherited in an instance):

<xforms:instance id="my-form"><form>...</form></xforms:instance><xforms:bind nodeset="instance('my-form')" readonly="true()"/>

4.1.2. Static Appearance for Read-Only Mode

Sometimes, read-only controls don't appear very nicely in web browsers. For example, a combo box will appear grayed out. It maybe be hard to read, and there is not much point showing a combo box since the user can't interact with it. Furthermore, with some browsers, like IE 6 and earlier, it is not even possible to make disabled controls appear nicer with CSS. In order to make read-only versions of forms look nicer, Orbeon Forms supports a special extention attribute that allows you to produce a "static" appearance for read-only controls. You enable this on your first XForms model:

<xforms:model xxforms:readonly-appearance="static">...</xforms:model>

The attribute takes one of two vales: static or dynamic (the default). When using the value static, read-only controls do not produce disabled HTML form controls. This has one major limitation: you can't switch a control back to being read-write once it is displayed as read-only.

You can also set the xxforms:readonly-appearance attribute directly on individual XForms controls.

See the Government Forms sample application's View Read-Only option for an example of this feature in action.

4.2. Formatting

4.2.1. Rationale

It is usually recommended to use native XML types within XForms instances, as this guarantees interoperability and maintainability. For example, a date of January 10, 2005 is stored in ISO format as: 2005-10-01. However it is often necessary to format such values on screen in a user-readable format, like "January 10, 2005", "10 janvier 2005", or "10. Januar 2005".

Orbeon Forms provides an extension attribute, xxforms:format, for that purpose. xxforms:format must contain an XPath 2.0 expression. In your XPath expression you can use all the XPath 2.0 functions, including those for date manipulation (external documentation). However since XPath 2.0 functions don't provide any facility for date and time formatting, you can in this attribute also use the following XSLT 2.0 functions:

The XPath expression is evaluated by the XForms engine whenever the value bound to the xforms:input control changes and needs to be updated on screen. It is evaluated in the context of the instance node bound to the control. This means that the current value of the control can be accessed with ".". Often the value must be converted (for example to a date) in which case the conversion can be done with a XPath 2.0 constructor such as xs:date(.) or with as cast such as (. cast as xs:date?).

4.2.2. xforms:input

When using xforms:input and a bound xs:date type, you can control the formatting of the date using the xxforms:format extension attribute on the xforms:input control. For example:

<xforms:input ref="date" xxforms:format="format-date(xs:date(.), '[MNn] [D], [Y]', 'en', (), ())"/>
Note

This only controls the appearance of the date as shown to the user. It does not control the format of the date captured in the XML document, or determines the format into which the user can type the date.

4.2.3. xforms:output

When using xforms:output, you can control the formatting of the date using the xxforms:format extension attribute on the xforms:output control.

<xforms:output ref="date" xxforms:format="format-date(xs:date(.), '[MNn] [D], [Y]', 'en', (), ())"/><xforms:output ref="size" xxforms:format="format-number(., '###,##0')"/>

4.2.4. Default Formatting

For both xforms:input and xforms:output, if the bound node is of one of the following types: xs:date, xs:dateTime, xs:time, xs:decimal, xs:integer, xs:float, and xs:double, and if no xxforms:format attribute is present on the control, formatting is based on properties. If the properties are missing, a built-in default formatting is used. The default properties, as well as the built-in defaults, are as follows:

<property as="xs:string" name="oxf.xforms.format.date" value="if (. castable as xs:date) then format-date(xs:date(.), '[FNn] [MNn] [D], [Y]', 'en', (), ()) else ."/><property as="xs:string" name="oxf.xforms.format.dateTime" value="if (. castable as xs:dateTime) then format-dateTime(xs:dateTime(.), '[FNn] [MNn] [D], [Y] [H01]:[m01]:[s01] UTC', 'en', (), ()) else ."/><property as="xs:string" name="oxf.xforms.format.time" value="if (. castable as xs:time) then format-time(xs:time(.), '[H01]:[m01]:[s01] UTC', 'en', (), ()) else ."/><property as="xs:string" name="oxf.xforms.format.decimal" value="if (. castable as xs:decimal) then format-number(xs:decimal(.),'#,##0.00') else ."/><property as="xs:string" name="oxf.xforms.format.integer" value="if (. castable as xs:integer) then format-number(xs:integer(.),'#,##0') else ."/><property as="xs:string" name="oxf.xforms.format.float" value="if (. castable as xs:float) then format-number(xs:float(.),'#,##0.000') else ."/><property as="xs:string" name="oxf.xforms.format.double" value="if (. castable as xs:double) then format-number(xs:double(.),'#,##0.000') else ."/>

They produce results as follows:

  • 2004-01-07 as xs:date is displayed as Wednesday January 7, 2004

  • 2004-01-07T04:38:35.123 as xs:dateTime is displayed as Wednesday January 7, 2004 04:38:35 UTC

  • 04:38:35.123 as xs:time is displayed as 04:38:35 UTC

  • 123456.789 as xs:decimal is displayed as 123,456.79

  • 123456.789 as xs:integer is displayed as 123,456

  • 123456.789 as xs:float or xs:double is displayed as 123,456.789

Note:

  • With the "if" condition in the XPath expressions, a value which cannot be converted to the appropriate type is simply displayed as is.
  • For values of type xs:time or xs:dateTime, if you wish the time to be displayed using the current timezone instead of UTC, replace in the value attribute UTC by [ZN].

4.3. Iteration of XForms Actions over Sequences

Orbeon Forms supports the exforms:iterate attribute, also available as xxforms:iterate attribute, on XForms action elements. Consider the following instances:

<xforms:instance id="main-instance"><instance/></xforms:instance><xforms:instance id="template-instance"><book><title/><author/></book></xforms:instance><xforms:instance id="source-instance"><instance><title>Don Quixote de la Mancha</title><author>Miguel de Cervantes Saavedra</author><title>Jacques le fataliste et son maître</title><author>Denis Diderot</author><title>Childhood's End</title><author>Arthur C. Clarke</author></instance></xforms:instance>

The following action iterates over the <title> elements of source-instance. For each of those, a new <book> element, copied from the template stored in template-instance, is inserted into main-instance. Then values from the <title> and <author> elements are copied over to the new structure. The XForms 1.1 context() function provides access to each of the iterated nodes:

<xforms:action ev:event="xforms-ready" xxforms:iterate="instance('source-instance')/title"><xforms:insert context="instance('main-instance')" nodeset="book" origin="instance('template-instance')"/><xforms:setvalue ref="instance('main-instance')/book[last()]/title" value="context()"/><xforms:setvalue ref="instance('main-instance')/book[last()]/author" value="context()/following-sibling::author"/></xforms:action>

The resulting main-instance is as follows:

<instance><book><title>Don Quixote de la Mancha</title><author>Miguel de Cervantes Saavedra</author></book><book><title>Jacques le fataliste et son maître</title><author>Denis Diderot</author></book><book><title>Childhood's End</title><author>Arthur C. Clarke</author></book></instance>

Note that because Orbeon Forms uses XPath 2.0, xxforms:iterate is not limited to returning node-sets, but can return sequences of items such as strings.

For more information about eXforms extensions, please visit the eXforms site.

4.4. Generalized context attribute

XForms 1.1 introduces the context attribute on <xforms:insert> and <xforms:delete>. Orbeon Forms supports this convenient attribute on all XForms elements changing the XPath evaluation context, including controls, actions, binds, and submissions.

The context attribute overrides the in-scope XPath evaluation context for an action. It applies before the ref and context attributes, but after the model attribute.

One convenient use is to just change the context within a group:

<xforms:group context="personal-information">...</xforms:group>

Note that it is also possible to use ref in this case, but doing so has the side effect of binding the group to an instance data node, which may affect group relevance, for example.

4.5. Enhanced event() Function Support

Orbeon Forms enhances the XML Events event() function to take a qualified name as parameter:

event($attribute-name as QName) item()*

This allows namespacing attribute names, therefore better allowing for extension attributes.

The following standard event attributes are implemented:

[TODO: describe standard Orbeon Forms support for event() function]

On all events, the following extension attributes are supported:

  • event('xxforms:type') as xs:string

    Return the event type (also known as event name), for example "DOMActivate".

  • event('xxforms:target') as xs:string

    Return the id of the event target.

  • event('xxforms:bubbles') as xs:boolean

    Return whether the event is allowed to bubble or not.

  • event('xxforms:cancelable') as xs:boolean

    Return whether the event is cancelable or not.

On all UI events (DOMActivate, DOMFocusIn, DOMFocusOut, xforms-select, xforms-deselect, xforms-enabled, xforms-disabled, xforms-help, xforms-hint, xforms-valid, xforms-invalid, xforms-required, xforms-optional, xforms-readonly, xforms-readwrite, xforms-value-change), the following extension attributes are supported:

  • event('xxforms:binding') as node()?

    Return the event target's single-node binding if any.

  • event('xxforms:label') as xs:string?

    Return the event target's label value if any.

  • event('xxforms:hint') as xs:string?

    Return the event target's hint value if any.

  • event('xxforms:help') as xs:string?

    Return the event target's help value if any.

  • event('xxforms:alert') as xs:string?

    Return the event target's alert value if any.

  • event('xxforms:repeat-indexes') as xs:string*

    Return the event target's current repeat indexes, if any, starting from the ancestor repeat.

On xforms-select, the following extension attributes are supported:

  • event('xxforms:item-value')

    When this event is dispatched to in response to a selection control item being selected, returns the value of the selected item.

On xforms-submit-serialize, the following extension attributes are supported:

  • event('xxforms:binding') as node()?

    Return the submission's single-node binding if any.

  • event('xxforms:serialization') as xs:string

    Return the submission's requested serialization, e.g. application/xml, application/x-www-form-urlencoded, etc..

4.6. Enhanced <xforms:dispatch> Support

Orbeon Forms supports passing event context attributes with the <xxforms:context> child element. The actions supported are actions which directly cause an event to be dispatched:

  • <xforms:dispatch>

  • <xforms:send>

  • <xxforms:show>

  • <xxforms:hide>

Here is how you pass context attributes when executing an action:

<xforms:dispatch name="rename-control" target="my-model"><xxforms:context name="my:control" select="my/control"/><xxforms:context name="my:control-name" select="'beverage-selection'"/></xforms:dispatch>

<xxforms:context> supports the following two attributes:

name Mandatory Name of the context attribute. In order to avoid confusion with standard XForms names, we recommend you use qualified names.
select Mandatory XPath 2.0 expression determining the value of the context attribute.

Context attribute passed this way can be retrieved using the event() function:

<xforms:action ev:event="rename-control"><xforms:setvalue ref="event('control')/@name" value="event('control-name')"/></xforms:action>
Note

At the moment, with, <xforms:dispatch>, only custom events support passing context attributes this way. Built-in events, such as xforms-value-changed, or DOMActivate, ignore nested <xxforms:context> elements.

4.7. Enhanced Support for xforms-select and xforms-deselect

[TODO: describe support for these events on xforms:upload]

4.8. Targetting effective controls within repeat iterations

The following actions all support attributes resolving to a particular control:

  • <xforms:dispatch> (target attribute)

  • <xforms:setfocus> (control attribute)

  • <xforms:toggle> (case attribute)

  • <xxforms:show> (neighbor attribute)

When that control is within a repeat iteration, the actual control targetted is chosen based on the current set of repeat indexes. However, in some cases, it is useful to be able to target the control within a particular iteration. This is achieved with the xxforms:repeat-indexes extension attribute on these actions. This attribute takes a space-separated list of repeat indexes, starting with the outermost repeat. Example:

<!-- Repeat hierarchy --><xforms:repeat nodeset="todo-list"><xforms:repeat nodeset="todo-item"><xforms:switch><xforms:case id="edit-case">...</xforms:case><xforms:case id="view-case">...</xforms:case></xforms:switch></xforms:repeat></xforms:repeat><xforms:trigger><xforms:label>Toggle Me!</xforms:label><!-- Toggle the case within the 5th todo item of the 3rd todo list --><xforms:toggle ev:event="DOMActivate" case="edit-case" xxforms:repeat-indexes="3 5"/></xforms:trigger>

4.9. Validation Extensions

4.9.1. Extension Events

Orbeon Forms supports extensions events dispatched to an instance when it becomes valid or invalid: xxforms-valid and xxforms-invalid. These events are dispatched just before xforms-revalidate completes, to all instances of the model being revalidated. For a given instance, either xxforms-valid or xxforms-invalid is dispatched for a given revalidation.

These events can be used, for example, to toggle the appearance of icons indicating that a form is valid or invalid:

<xforms:instance id="my-instance">...</xforms:instance><xforms:action ev:event="xxforms-invalid" ev:observer="my-instance"><xforms:toggle case="invalid-form-case"/></xforms:action><xforms:action ev:event="xxforms-valid" ev:observer="my-instance"><xforms:toggle case="valid-form-case"/></xforms:action>

4.9.2. Extension Types

Orbeon Forms supports the built-in xxforms:xml extension type. This types checks that the value is well-formed XML:

<xforms:bind nodeset="my-xml" type="xxforms:xml"/>

Note that this checks the string value of the node, which means that the node must contain escaped XML.

Orbeon Forms supports the built-in xxforms:xpath2 extension type. This types checks that the value is well-formed XPath 2.0. Any variable used by the expression is assumed to be in scope:

<xforms:bind nodeset="my-xpath" type="xxforms:xpath2"/>
Note

In both these cases, Orbeon Forms checks for the required MIP: if it evaluates to false() and the value is the empty string, then the instance data node is considered valid. This is contrary to XForms 1.1 as of August 2008.

4.9.3. Controlling the XML Schema Validation Mode

When an XML Schema is provided, Orbeon Forms supports controlling whether a particular instance is validated in "lax" mode, "strict" mode, or not validated at all.

Orbeon Forms implements a "lax" validation mode by default, where only elements that have definitions in the imported schemas are validated. Other elements are not considered for validation. This is in line with XML Schema and XSLT 2.0 lax validation modes, and with the default validation mode as specified in XForms 1.1

In addition, the author can specify the validation mode directly on each instance with the extension xxforms:validation attribute, which takes values lax (the default), strict (the root element has to have a definition in the schema and must be valid), or skip (no validation at all for that instance).

<xforms:model schema="my-schema.xsd"><xforms:instance id="my-form" xxforms:validation="strict"><my-form>...</my-form></xforms:instance><xforms:instance id="items" xxforms:validation="skip"><items>...</items></xforms:instance></xforms:model>

Nodes validated through a schema receive datatype annotations, which means that if an element or attribute is validated against xs:date in a schema, an XForms control bound to that node will display a date picker.

4.10. JavaScript Integration

4.10.1. Rationale

While XForms gets you a long way towards creating a dynamic user-friendly user interface, there are some dynamic behaviors of the user interface that cannot be implemented easily or at all with XForms, or you might already have some JavaScript code that you would like to reused. A JavaScript API is provided to handle those cases, or other use cases involving JavaScript that you might have.

4.10.2. Getting and Setting Controls Value

In JavaScript, you get the current value of an XForms control var value = ORBEON.xforms.Document.getValue("myControl") where myControl is the id of the XForms control, for instance: <xforms:input id="myControl">.

You set the value of an XForms control with ORBEON.xforms.Document.setValue("myControl", "42") where myControl is the id of the XForms control, and 42 the new value. Setting the value with JavaScript is equivalent to changing the value of the control in the browser. This will trigger the recalculation of the instances, and the dispatch of the xforms-value-changed event. More formally, the Value Change sequence of events occurs.

As an example, consider you have the model below. It declares an instance with two elements foo and bar, where bar is a copy of foo, implemented with a calculate MIP.

<xforms:model><xforms:instance id="instance"><instance><foo>42</foo><bar/></instance></xforms:instance><xforms:bind nodeset="/instance/bar" calculate="/instance/foo"/></xforms:model>

The input control below is bound to foo, and the output control is bound to bar. When activated, the trigger executes JavaScript with the <xxforms:script> action. It increments the value of the input control bound to foo. When this happens the value displayed by the output control bound to baris incremented as well, as bar is a copy of foo.

<xhtml:p><xforms:input ref="foo" id="foo"><xforms:label class="fixed-width">Value of foo:</xforms:label></xforms:input></xhtml:p><xhtml:p><xforms:output ref="bar"><xforms:label class="fixed-width">Value of bar:</xforms:label></xforms:output></xhtml:p><xhtml:p><xforms:trigger><xforms:label>Increment foo with JavaScript</xforms:label><xxforms:script ev:event="DOMActivate">var fooValue = ORBEON.xforms.Document.getValue("foo"); ORBEON.xforms.Document.setValue("foo", Number(fooValue) + 1);</xxforms:script></xforms:trigger></xhtml:p>

4.10.3. Dispatching Events

You can dispatch your own events from JavaScript by calling the function ORBEON.xforms.Document.dispatchEvent(). The parameters to this function are:

targetId Mandatory Id of the target element. The element must be an element in the XForms namespace: you cannot dispatch events to HTML elements. In addition, the id must identify either a relevant and non-readonly XForms control, or a model object that supports event handlers such as <xforms:model>, <xforms:instance>, or <xforms:submission>.
eventName Mandatory

Name of the event.

Warning

For security reasons, by default Orbeon Forms prohibits client-side JavaScript from dispatching any external events except DOMActivate, DOMFocusIn and DOMFocusOut. Furthermore, these events can only be dispatched to relevant and non-readonly XForms controls. In order to enable dispatching of custom events, you must first add the xxforms:external-events attribute on the first <xforms:model> element, for example:

<xforms:model xxforms:external-events="acme-super-event acme-famous-event">...</xforms:model>

This attribute contains a space-separated list of event name. In this example, you explicitly enable your JavaScript code to fire the two events acme-super-event and acme-famous-event to any relevant and non-readonly XForms controls, or to any model object supporting event handlers. Note that you can only enable custom events, but you cannot enable standard XForms or DOM events in addition to DOMActivate, DOMFocusIn and DOMFocusOut.

Since the event handlers for custom events can be called by JavaScript code that runs on the client, you need to be aware that these handlers can potentially be activated by anybody able to load the form in his browser.

form Optional The form object that corresponds to the XForms form you want to dispatch the event to. This argument is only needed when you have multiple "XForms forms" on the same HTML page. Typically, this would only happens if you are running your form in a portal and you have multiple portlets using XForms on the same page. When the parameter is not present or null, the first form on the HTML page with the class xforms-form is used.
bubbles Optional Optional boolean indicating if this event bubbles, as defined in DOM2 Events. The default value depends on the definition of the custom event.
cancelable Optional Optional boolean indicating if this event bubbles, as defined in DOM2 Events. The default value depends on the definition of the custom event.
incremental Optional When fals