XBL - Existing XBL Components

Rationale

A number of pre-built XBL components ship with Orbeon Forms. You can use those components:
  • From Form Builder: Choose the control you want to use in the left side-bar.
  • In your own XForms code, the definitions of fr:* components are automatically included if you use them. In other words, just use and enjoy: you don't have anything special to do to use any of the components shown below.

Components 

Date
This component is deprecated as of Orbeon Forms 4.5.

The <fr:date> components builds on the <xforms:input> bound to node of type xs:date but provides the following additional functionality:
  • You can use the appearance="fr:inline" to have the date picker shown inline in the page (instead of having the date picker shown when you click in the input field). When you use this appearance, no text filed is displayed and you need to click on a date in the date picker to select it.

  • You can use the mindate and maxdate properties to put a constraint on the dates that can be selected in the date picker. Dates before the mindate and after the maxdate will be grayed out. You can set a "static" mindate or maxdate using an attribute:
<fr:date ref="date" mindate="2009-05-06" maxdate="2009-05-24">
    <xforms:label>Contract start date:</xforms:label>
</fr:date>

Or you can have a "dynamic" mindate or maxdate using sub-elements:

<fr:date ref="date" appearance="fr:inline">
    <xforms:label>Contract start date:</xforms:label>
    <fr:mindate ref="../mindate"/>
    <fr:maxdate ref="../maxdate"/>
</fr:date>

The above control might be rendered as follows if the current date is May 15, the mindate is May 5 and the maxdate is May 25:

  • The date picker opens at a given month:

    1. If the bound node holds a valid date, then the date picker will show the month corresponding to that date.
    2. If the bound node does not hold a valid date, then the date shows the month corresponding to today's date.
    3. You can override the above behavior, which is inherited from <xforms:input> bound to a node of type xs:date, by setting the pagedate property.

    You can set a "static" pagedate using an attribute:
<fr:date ref="date" pagedate="1970-01-01">
    <xforms:label>You birth date:<xforms:label>
</fr:date>

Or you can have a "dynamic" pagedate using a sub-element:

<fr:date ref="date" pagedate="1970-01-01">
    <xforms:label>You birth date:<xforms:label>
    <fr:pagedate ref="../pagedate"/>
</fr:date>

Setting a pagedate is particularly useful when you don't have an initial date, because no date has been set yet, but you know that the date to be entered won't be around the current date, but rather around some other date.

Date Picker

This component is deprecated as of Orbeon Forms 4.5.

The date picker component works very much like like an <xforms:input> bound to a node of type xs:date, except instead of the date being editable through a text field, the date is printed next to the date picker icon. Using this component instead of an <xforms:input> will guarantee you that the date entered by users is valid.


To use the component, write:

<fr:date-picker ref="date" id="data-picker">
    <xforms:label>Arrival date</xforms:label>
</fr:date-picker>

Inside the control, you can use the usual <xforms:label>, <xforms:hint>, <xforms:help>, and <xforms:alert>, as you would with XForms controls. You must make the ref attribute point to a node of type xs:date.

Accordion menu

This component is deprecated as of Orbeon Forms 4.5.

Overview

The accordion menu component is not unlike the <xforms:switch>: it defines a number of "cases", each with a title and some content. Each case can be selected (visible) or not (hidden). The screenshot below shows an accordion menu component with 3 cases:



You used the accordion menu component with:

<fr:accordion class="fr-accordion-lnf" id="my-accordion">
    <fr:case>
        <fr:label>First section (lorem ipsum)</fr:label>
        <xhtml:div>
            Lorem ipsum dolor sit amet, [...]
        </xhtml:div>
    </fr:case>
    <fr:case selected="true" id="my-second-case">
        <fr:label>Second section (XForms input)</fr:label>
        <xforms:input ref="cost">
            <xforms:label>Cost</xforms:label>
        </xforms:input>
    </fr:case>
    ...
</fr:accordion>

Note:
  • The <fr:case> elements define the different sections of the accordion menu.
  • For each case, you specify the label for that case with <fr:label>.
  • Inside the <fr:case>, after the <fr:label>, you can put any markup (XForms, XHTML) you want.
  • You can specify a class on the <fr:accordion>. By using fr-accordion-lnf, as in the code above, you pick the default style. Should you want to use a completely different style, specify another class on <fr:accordion> and create your CSS using that class as appropriate.
  • You can specify which cases should be selected (i.e. open) when the accordion is first shown, by addition the attribute selected="true".

Events

You can programmatically open an close cases by dispatching events to the accordion control. It supports the following events:
  • fr-toggle – to toggle a specific case. Like the XForms <xforms:toggle> action used with cases, this event changes the state of a case. The dispatch target is the corresponding <fr:case> element.
    <xforms:trigger appearance="minimal">
        <xforms:label>Toggle one</xforms:label>
        <xforms:dispatch ev:event="DOMActivate" target="my-second-case" name="fr-toggle"/>
    </xforms:trigger>
  • fr-show – to show a specific case. This event shows the given case. The dispatch target is the corresponding <fr:case> element.
    <xforms:trigger appearance="minimal">
        <xforms:label>Show one</xforms:label>
        <xforms:dispatch ev:event="DOMActivate" target="my-second-case" name="fr-show"/>
    </xforms:trigger>
  • fr-hide – to hide a specific case. This event hides the given case. The dispatch target is the corresponding <fr:case> element.
    <xforms:trigger appearance="minimal">
        <xforms:label>Hide one</xforms:label>
        <xforms:dispatch ev:event="DOMActivate" target="my-second-case" name="fr-hide"/>
    </xforms:trigger>
  • fr-show-all – to open or close all the cases at once. The dispatch target is the corresponding <fr:accordion> element.
    <xforms:trigger appearance="minimal">
        <xforms:label>Show all</xforms:label>
        <xforms:dispatch ev:event="DOMActivate" target="my-accordion" name="fr-show-all"/>
    </xforms:trigger>
  • fr-hide-all – to open or close all the cases at once. The dispatch target is the corresponding <fr:accordion> element.
    <xforms:trigger appearance="minimal">
        <xforms:label>Hide all</xforms:label>
        <xforms:dispatch ev:event="DOMActivate" target="my-accordion" name="fr-hide-all"/>
    </xforms:trigger>

Deprecated events:
  • Deprecated: fr-accordion-toggle-all – to open or close all the cases at once. This event takes a context parameters selected which value must be either true (to open all cases) or false (to close all cases). For instance:
<xforms:trigger appearance="minimal">
    <xforms:label>Open all</xforms:label>
    <xforms:dispatch ev:event="DOMActivate" target="my-accordion" name="fr-accordion-toggle-all">
        <xxforms:context name="selected" select="true()"/>
    </xforms:dispatch>
</xforms:trigger>
  • Deprecated: fr-accordion-toggle – to open or close a specific case. This events supports the selected context parameter (as fr-accordion-toggle-all described above). It also supports the case-id which must be the ID of an <fr:case>. For instance:
<xforms:trigger appearance="minimal">
    <xforms:label>Open second case</xforms:label>
    <xforms:dispatch ev:event="DOMActivate" target="my-accordion" name="fr-accordion-toggle">
        <xxforms:context name="case-id" select="'my-second-case'"/>
        <xxforms:context name="selected" select="true()"/>
    </xforms:dispatch>
</xforms:trigger>

Keeping only one case open

In certain cases, you don't want users to have multiple cases of a given accordion open at the same time. For instance, if a case A is open, and they click on the title of another case B, instead opening B and keeping A open, you would like this action to close A and open B. You can instruct the accordion to behave in this way by setting the open-closes-others property to true (it is false by default). You can do this either globally in your properties-local.xml:

<property as="xs:boolean" name="oxf.xforms.xbl.fr.accordion.open-closes-others" value="true"/>

Or you can set this property on a specific accordion by setting the corresponding attribute:

<fr:accordion open-closes-others="true">

Note that cases will close automatically only if the user opens a case by clicking on the title of that case. This option has no effect on events you send to the accordion. Using events you send to the accordion, you can still have more than case open, if this is indeed what you decide want to do.

Repeats

You can use an <xforms:repeat> inside the <fr:accordion> to dynamically generate cases. For instance:

<fr:accordion class="fr-accordion-lnf" id="my-accordion">
    <xforms:repeat nodeset="path/to/nodes">
        <fr:case id="my-case-repeat">
            ...
        </fr:case>
    </xforms:repeat>
</fr:accordion>

When you have a repeat around cases, and use the fr-accordion-toggle event specifying the ID of the case (my-case-repeat in the example above), the current case in the repeat is opened.

In-place Input

This component is deprecated as of Orbeon Forms 4.5.

Like <xforms:input>, this control allows entering a single line of text.

The value of this control initially appears as if shown with <xforms:output>: it is read-only and does not appear like a regular input field.

When the user clicks on the text, the control morphs into an input field, allowing editing the value.

After entering a value, the user has the choice of applying the change or canceling.

The control supports the usual label, hint, alert, and help nested elements.

<fr:inplace-input ref="name">
    <xforms:label>Name:</xforms:label>
    <xforms:hint>Click here to enter your name</xforms:hint>
    <xforms:alert>Invalid name</xforms:alert>
    <xforms:help>
        This control is an in-place input: when you click on the text,
        it morphs into an input field which allows you to edit the value.
    </xforms:help>
</fr:inplace-input>

If the control's value is empty, the control shows inline the value provided by a nested <xforms:hint>, if any. It is recommended to provide such a hint so that there is a clear area to click on and make the input field appear.