Orbeon Search

Comments? Feedback?

This wiki does not yet support public comments (a limitation of Google Sites), so we encourage you to post your comments either:

On Twitter by responding to @orbeon.

On our community mailing list: subscribe sending an email to ops-users-subscribe@ow2.org (content of subject/body doesn't matter), you'll get a response with the email to use to send your message to the community mailing list.

Recent site activity

Configuration Properties - XForms

Contents

  1. 1 Submission
  2. 2 Instance inclusion
  3. 3 Intance data types
  4. 4 Noscript mode
  5. 5 Controls
    1. 5.1 XForms 1.1-compatible of switch/case
    2. 5.2 Label, help, hint, alert (LHHA) elements
    3. 5.3 Date picker type
    4. 5.4 Two months view
    5. 5.5 Navigator
    6. 5.6 HTML editor
  6. 6 Ajax portlet
    1. 6.1 Usage
    2. 6.2 Page Inclusion with Dojo
  7. 7 XForms Inspector
  8. 8 Client events optimizations
    1. 8.1 When Events Are Sent to Server
    2. 8.2 Filtering Events
  9. 9 Formatting
    1. 9.1 For <xforms:output>
    2. 9.2 For <xforms:input>
  10. 10 Error Dialog
  11. 11 Automatic inclusion of XBL bindings

Submission

The following property controls some aspects of XForms submission in Orbeon Forms:

<property as="xs:boolean" name="optimize-get-all" value="true"/>


If set to true (the default), Orbeon Forms optimizes submissions with replace="all" and the get method by sending URL of the submission action directly to the web browser. This however means that submission errors cannot be caught by XForms event handlers after Orbeon Forms has started connecting to the submission URL, as should be the case following the XForms specification. If set to false, Orbeon Forms buffers the reply so that errors can be handled as per XForms. However, this solution is less efficient.

The following two properties control optimized XForms submissions:

<property as="xs:boolean" name="oxf.xforms.oxf.xforms.local-submission-forward" value="true"/>

  • If set to true (the default), Orbeon Forms optimizes "local" (i.e. submissions performed to a URL controlled by Orbeon Forms itself) submissions with replace="all", by using the Java Servlet API's forward capability instead of actually performing an HTTP request.
  • If set to false, Orbeon Forms always always uses the HTTP or HTTPS protocol (or other protocol specified), which is less efficient but more flexible.
<property as="xs:boolean" name="oxf.xforms.oxf.xforms.local-submission-include" value="false"/>

  • If set to true (the default is false), Orbeon Forms optimizes "local" (i.e. submissions performed to a URL controlled by Orbeon Forms itself) submissions with replace="instance", replace="text" or replace="none", by directly using the Java Servlet API's include capability instead of actually performing an HTTP request.
  • If set to false, Orbeon Forms always always uses the HTTP or HTTPS protocol (or other protocol specified), which is less efficient but more flexible.

Instance inclusion

The following property controls optimized instance inclusion:

 <property as="xs:boolean" name="oxf.xforms.local-instance-include" value="false"/>

  • If set to true (the default is false), Orbeon Forms optimizes "local" (i.e. submissions performed to a URL controlled by Orbeon Forms itself) instance inclusions, by directly using the Java Servlet API's include capability instead of actually performing an HTTP request.
  • If set to false, Orbeon Forms always always uses the HTTP or HTTPS protocol (or other protocol specified), which is less efficient but more flexible.
Note that for any optimized submission or inclusion to occur, the following is required:
  • URL must be an absolute path, e.g. /foo/bar. Using an explicit protocol (http://foo.com/bar) disables optimized submissions.
  •  No <xforms:header> elements must be passed.
  •  The submission must be synchronous.

Intance data types

The following property controls whether instance types annotations are exposed to XPath 2.0 expressions:

 <property as="xs:boolean" name="oxf.xforms.expose-xpath-types" value="true"/>

  • If set to false (the default as of July 2009), instance types are not made available to XPath expressions.
  • If set to true, they are made available.

More information: XPath 2.0 support.

Noscript mode

The following property controls whether noscript mode is enabled:

<property as="xs:boolean" name="oxf.xforms.noscript" value="false"/>
    The following property controls whether noscript mode is supported:

    <property as="xs:boolean" name="oxf.xforms.noscript-support" value="true"/>

    The noscript mode is enabled only if both properties are true.

    NOTE: The reason there are two properties is that in the future, the XForms engine might be able to determine by itself whether noscript mode is enabled based on what controls and XBL components are in use.

    Controls

    XForms 1.1-compatible of switch/case

    XForms 1.1 specifies that a non-visible case behaves as non-relevant.

    Starting March 2010 builds, a property allows enabling XForms 1.1-compatible behavior. (Orbeon Forms did not support this previously and considered that non-visible cases were hidden but still relevant.)

    <property as="xs:boolean" name="oxf.xforms.xforms11-switch" value="true"/>

    You can also set this property on a per-switch basis:
    <xforms:switch xxforms:xforms11-switch="true">
        ...
    </xforms:switch>

    This property also applies in a similar way to hidden dialogs.

    NOTE: In the future, it is expected that:
    • This will be enabled by default to be XForms 1.1-compliant out of the box.
    • Setting the property to false will revert to the pre-March 2010 behavior, as there are cases where keeping hidden cases relevant makes sense.

    Label, help, hint, alert (LHHA) elements

    By default, since 2009-10-13, LHHA elements are represented as follows:
    • <xforms:label> use the HTML <label> element
    • <xforms:hint> use the HTML <span> element
    • <xforms:help> use the HTML <span> element
    • <xforms:alert> use the HTML <span> element
    NOTE: Before 2009-10-13 they all used to be represented as <label> elements. But this causes issues with some screen readers and the HTML specification is not clear anyway as to whether more than one <label> element is allowed for a given control, and doesn't provide the correct semantic anyway.

    You can configure the following properties in your properties-local.xml to change the default configuration:

    <property as="xs:string"  name="oxf.xforms.label-element"                               value="label"/>
    <property as="xs:string"  name="oxf.xforms.hint-element"                                value="span"/>
    <property as="xs:string"  name="oxf.xforms.help-element"                                value="span"/>
    <property as="xs:string"  name="oxf.xforms.alert-element"                               value="span"/>

    If an element is configured to be a label, a "for" attribute pointing to the control is set by the XForms engine.

    Date picker type

    Two implementations of the date picker widget are available:
    • The YUI-based implementation - Used by default.
    • The jscalendar-based implementation - This implementation is still provided for backward compatibility if you have an application that has been developed before Orbeon Forms started to use the YUI date picker and your application depends on the jscalendar. If you are using this date picker, you should consider moving to the YUI calendar as the jscalendar-based implementation will most likely not be improved going forward and might be deprecated in a future version of Orbeon Forms.
    You choose the implementation by setting the oxf.xforms.datepicker property to either yui or jscalendar. For instance:

    <property as="xs:string"  name="oxf.xforms.datepicker" value="yui"/>

    Two months view

    By default, YUI date picker shows as follows:

    Default YUI date picker


    You can set the oxf.xforms.datepicker.two-months property to true, and the date picker will show two months at a time:


    YUI date picker with two months displayed at a time

    By default, the property is set to false, (only one month is shown). You can override by adding the following to your properties-local.xml:

    <property as="xs:boolean" name="oxf.xforms.datepicker.two-months" value="false"/>


    Navigator

    With the oxf.xforms.datepicker.navigator property set to true (which is the default), when you click on the month headers, a small dialog allows you to type a year and select a month from a drop-down. This is particularly convenient if the date you want to capture has a chance to be further in the future or in the past (such as a birth date).


    Month and year selection in YUI date picker with navigator and two months properties enabled


    You disable the navigator by setting the following property to false (it is true by default):

    <property as="xs:boolean" name="oxf.xforms.datepicker.navigator" value="false"/>


    HTML editor

    When you have an attribute mediatype="text/html" on your <xforms:textarea>, the XForms text area is rendered as an XHTML editor. You can decide the XHTML editor implementation to use with the property:

    <property as="xs:string"  name="oxf.xforms.htmleditor" value="yui"/>

    You can set the value of this property to either:
    • yui to use the YUI RTE (the default)
    • fck to use the legacy FCK editor
    We recommend you leave this property to its default value and only use the FCK editor if you have particular constraints that force you to do so. There are a number of known issues with the FCK editor and support for the FCK editor might be dropped in future versions of Orbeon Forms.

    Ajax portlet

    Usage

    When you enable the Ajax portlet feature, XForms submissions with replace="all" won't trigger the browser to load a new page, but rather the content of the new page will be loaded through Ajax and the HTML page in the browser will be modified to replace the part of the HTML that corresponds to the "current page" with the HTML of the "target page".

    This is particularly useful when are embedding a form produced by Orbeon Forms into another page. In some cases, this can be a better alternative to using an iframe to load the form produced by Orbeon Forms.

    To enable this feature, set the following property to true:

    <property as="xs:boolean" name="oxf.xforms.ajax-portlet" value="false"/>

    When you enable the Ajax portlet feature, you need to make sure that your forms are "embeddable". Embeddable forms are produced either because:
    • You set the oxf.epilogue.embeddable property to true. Use this method if all the forms produced by Orbeon Forms need to be embeddable.
    • You added a orbeon-embeddable=true request parameter. Use this method if only some forms need to be embeddable, in which case you need to add this request parameter on the URI when loading those forms.

    Page Inclusion with Dojo

    If you are using Dojo on your site, and would like to include a form produced by Orbeon Forms, you can use the following markup:

    <div class="form-pane" dojoType="dojox.layout.ContentPane" executeScripts="true"
         evalScripts="true" renderStyles="true" adjustPaths="true"
         href="../../xforms-sandbox/sample/submission-replace-all-1?orbeon-embeddable=true"/>

    Note the orbeon-embeddable=true on the URI, which corresponds to a case where you didn't want to set the oxf.epilogue.embeddable property to true. Because of the way Dojo loads the JavaScript code used by the form, the XForms initialization code doesn't run. So you will need to include code in the page which has the <div> above to call the XForms initialization code. You can do this with:

    <script type="text/javascript">
        var javaScriptLoadingIntervalID = window.setInterval(function() {
            if (typeof ORBEON != "undefined") {
                window.clearInterval(javaScriptLoadingIntervalID);
                ORBEON.xforms.Init.document();
                ORBEON.xforms.Globals.baseURL = "/orbeon";
                ORBEON.xforms.Globals.xformsServerURL = "/orbeon/xforms-server";
            }
        }, 10);
    </script>

    In this code you need to set the value of ORBEON.xforms.Globals.baseURL and ORBEON.xforms.Globals.xformsServerURL. The values start with /orbeon (as in this example) if the Orbeon web application in deployed on /orbeon, on the same server from which your page is loaded.

    Also, when Dojo includes the target form, Dojo loads JavaScript files used by the form, but fails to load the CSS files the form depends. So you need to include CSS files used by your form in the page that does the inclusion. If you have deployed the Orbeon Forms web application, you can see an example of this at:

    http://localhost:8080/orbeon/xforms-jsp/include-form/with-dojo.jsp 

    XForms Inspector

    You can enable the XForms Inspector for all the page in your site by setting the following property to true (the default is false): 

    <property as="xs:boolean" name="oxf.epilogue.xforms.inspector" value="true"/>

    Client events optimizations

    When Events Are Sent to Server

    By default, events produced by users' interactions with a form are sent by the browser to the server right after the interaction happens. Events are sent by the browser to the server through Ajax requests. A combination of large forms and high traffic can result in a high number of Ajax requests hitting your server, which in turn can impact your site performance.

    When this happens, you should consider setting the XForms client events to be in deferred rather than default mode, with either:
    • Globally setting the property oxf.xforms.client.events.mode to deferred in your properties-local.xml, as in: <property as="xs:string"  name="oxf.xforms.client.events.mode" value="deferred"/>
    • Adding the following attribute on the first <xforms:model> of your form: xxforms:client.events.mode="deferred".
    When you set the XForms clients events to be in deferred mode, the client will only send and Ajax request to the server when it encounters an event which matches at least one of the following conditions:
    • The event is a DOMActivate event (e.g. the user clicked on a trigger).
    • The target of the event has the class xxforms-events-mode-default.  This allows you to define controls for which you want events to always be sent to the server. For instance, you will put that class on a control for which you want  validation to be performed as soon as the user tabs out of the control. In addition, you can use the custom MIP xxforms:events-mode and set it to the value default.
    • The list of event to be sent to the server include events for a control which has a parent element P with the class xxforms-events-mode-default as well as events for controls that are not descendants of P. This allows you to put the class xxforms-events-mode-default on, say, an <xhtml:div> around a number of fields and have this group of fields considered as one control from the perspective of the deferred events.

    Filtering Events

    With this property, you can define events which will never be sent from the client to the server. Typically, you might want to filter out DOMFocusIn and DOMFocusOut events. This will:
    • Reduce the number of Ajax requests, as you will avoid having requests made in cases where users just tab through fields without changing any value.
    • Reduce the size of the Ajax requests, which in turn reduces bandwidth usage between the browser and the server and CPU usage on the server.
    The property value is a space-separated list of event names to be filtered. By default that list is empty. To filter the DOMFocusIn and DOMFocusOut events, you'd set it to:

    <property as="xs:string"  name="oxf.xforms.client.events.filter" value="DOMFocusIn DOMFocusOut"/>

    Formatting

    For <xforms:output>

    When an <xforms:output> is bound to a node and that node has a type, the type influences the formatting of the value. For instance, if the node has a type xs:date, instead of being shown as "2009-03-11", the value might be shown as "Wednesday March 11, 2009".

    Out of the box, Orbeon Forms formats differently values of different types. You can change how values are formatted by setting the properties below. The value of each property is an XPath expression executed on the node bound to the <xforms:output>. The XPath expression is expected to return a string containing the value which will be shown to the user.

    <property as="xs:string"  name="oxf.xforms.format.output.date"      value="..."/>
    <property as="xs:string"  name="oxf.xforms.format.output.dateTime"  value="..."/>
    <property as="xs:string"  name="oxf.xforms.format.output.time"      value="..."/>
    <property as="xs:string"  name="oxf.xforms.format.output.decimal"   value="..."/>
    <property as="xs:string"  name="oxf.xforms.format.output.integer"   value="..."/>
    <property as="xs:string"  name="oxf.xforms.format.output.float"     value="..."/>
    <property as="xs:string"  name="oxf.xforms.format.output.double"    value="..."/>

    Your XPath expressions can use the XSLT dates and time formatting functions such as format-date() or format-dateTime().

    For <xforms:input>

    As for <xforms:output>, values shown by <xforms:input> depend on the type of the node bound to the <xforms:input>. In this case however the <xforms:input> must be able to not only show a value coming from an instance in a text field, but also parse a new value in that format typed in by users in the text field. Because the <xforms:input> is able to both format and parse values, what you can do with an <xforms:input> is more restrictive compared to what you can do with an <xforms:output>.

    You can configure formatting for <xforms:input> with the two properties below. The value is a "mask" and follows the syntax of the Java SimpleDateFormat. However, only the following masks are supported:
    • For dates (property oxf.xforms.format.input.date):
      • [M]/[D]/[Y] e.g. 11/5/2008 (also called "North America format")
      • [D]/[M]/[Y] e.g. 11/5/2008 (also called "European format")
      • [D].[M].[Y] e.g. 5.11.2008 (also called "Swiss format")
    • For times (property oxf.xforms.format.input.time):
      • [h]:[m]:[s] [P] e.g. 2:05:12 p.m.
      • [H]:[m]:[s] e.g. 14:05:12
    An <xforms:input> bound to a node of type xs:dateTime is shown as two text fields: one for the date and one for the time. In that case, the date text field uses the formatting defined by oxf.xforms.format.input.date and the time text field uses the formatting defined by oxf.xforms.format.input.time.

    <property as="xs:string"  name="oxf.xforms.format.input.date"  value="[M]/[D]/[Y]"/>
    <property as="xs:string"  name="oxf.xforms.format.input.time"  value="[h]:[m]:[s] [P]"/>


    Error Dialog

    By default, when the Orbeon Forms JavaScript code intercepts an error, it displays to the user an error dialog as shown below.


    Default error dialog

    You can disable this behavior by setting the following property to false (its default value is true):

    <property as="xs:boolean" name="oxf.xforms.show-error-dialog"  value="true"/> 

    If you disable the default error dialog, you might want to provide an alternative way of reporting the issue to the user. You can do this in JavaScript by registering an event listener on ORBEON.xforms.Events.errorEvent.

    Automatic inclusion of XBL bindings

    Properties starting with oxf.xforms.xbl.mapping. specify a mapping of a directory name with a URI:
    <property as="xs:string" name="oxf.xforms.xbl.mapping.orbeon" value="http://orbeon.org/oxf/xml/form-runner"/>

    Consider an example, with  the property above set (which is the default):

    • say element <fr:button> is found by the XForms engine, in the http://orbeon.org/oxf/xml/form-runner namespace
    • the resulting directory name is orbeon, as per the property
    • this is used to resolve a resource called oxf:/xbl/orbeon/button/button.xbl
    • the resource, if found, is automatically included in the page for XBL processing

    This means that you don't have to explicitly include XBL bindings in your pages.

    By default, all the <fr:*> elements are handled this way. If you create your own library of XBL components in your namespace, you can add such a property to also allow for automatic inclusion.