Introduction
This page and its subpages describe the standard Orbeon Forms XForms form controls.
Some Orbeon Forms controls
XForms controls vs. HTML controls
XForms controls are similar to HTML form elements: they include text fields, drop down lists, checkboxes, etc. These are some differences between HTML forms elements and XForms controls:
- The value displayed by an XForms control comes from a data model represented by an XML document (called an "XForms instance"). When you declare a control, you bind it to an element or attribute of your XForms instance with an XPath expression in the
ref attribute (or with a bind attribute). For instance this text field a text field is bound to the <number> element, which a child of <credit-card>:
<xf:input ref="/credit-card/number"/>
- The way a control is rendered can depend on properties of the element or attribute the control is bound to:
- if it is bound to an invalid node then an error can be displayed;
- if the control is bound to a read-only node the value is displayed in read-only mode;
- if the node is not relevant the control isn't displayed at all;
- if the control is bound to a non-existing node, the control is considered non-relevant and is not displayed.
Standard controls vs. extension XBL components
Orbeon Forms has two types of controls:
- Standard controls. These are built into the XForms engine, and implement the XForms 1.1 specification, with some extensions for new appearances (such as trees).
- XBL components. These are extension controls, built with XBL technology. These include a tab view, datatable, and more, and you can also build your own! See Existing XBL Components for more information.
Label, help, hint and alert elements (LHHA elements)
Nested inside each XForms control element, you can specify additional elements that can alter
the way the control is displayed:
Label
[TODO: screenshot]
The <label> element is recommended for all controls.
Alert[TODO: screenshot]
In each control you can specify an error message that can be displayed if the value
entered by the user triggers a validation error.
<xf:secret ref="secret">
<xf:alert>Invalid password</xf:alert>
</xf:secret>
By default, alerts appear as red icons. When hovering over the icon, the alert message appears as a tooltip. You can disable this behavior by adding the xforms-disable-alert-as-tooltip class to your document body, for example:
<xh:body class="xforms-disable-alert-as-tooltip">
NOTE: Since 2012-05-10, you can place the class on any ancestor element of an XForms control. All controls under that tree will not enable the tooltip behavior.
Hint
[TODO: screenshot]
You can specify a hint on each control, which shows up as a hint when users mouse
over the control, or shows as inline text if formatted that way. [TODO: explain how]
<xf:textarea ref="textarea">
<xf:hint>Enter at least 11 characters</xf:hint>
</xf:textarea>
By default, hints appear as a tooltip when hovering over the control. You can disable this behavior by adding the xforms-disable-hint-as-tooltip class to your document body, for example:
<xh:body class="xforms-disable-hint-as-tooltip">
NOTE: Since 2012-05-10, you can place the class on any ancestor element of an XForms control. All controls under that tree will not enable the tooltip behavior.
Help
[TODO: screenshot]
If you specify a help message for a control, an icon with a question mark is
displayed next to the control. When users click on the help icon, a dialog is
displayed with the help message. The <xf:help> can contain
XHTML, or if you bind it to a node, the node can contain escaped XHTML.
<xf:input ref="date" class="xforms-date">
<xf:label class="fixed-width">Birth date:</xf:label>
<xf:help>
<div>
<p>
This field must contain:
</p>
<ul>
<li>a valid date</li>
<li>which is at most one day in the future</li>
</ul>
</div>
</xf:help>
</xf:input>
The help dialog has a default with of 300px defined in xforms.js. To
use a different width, override this default with:
.xforms-help-panel { width: 600px; }
By default, the help dialog will stretch vertically as needed so all the text in
your help is visible. Then users can use the browser vertical scrollbar to
navigate through the text. If instead you want the dialog to have a fixed height and
scrollbars inside the dialog when the text doesn't fit that height, use CSS as in:
.xforms-help-panel .bd { height: 300px; overflow: auto; }
In the examples above, the text displayed is directly in the <xf:label>,
<xf:alert>, <xf:help>, or <xf:hint>
element. Alternatively that text can come from an XForms instance by using a ref
attribute on any one of those elements. The ref references a node in the instant
that contains the text to use. This is useful to externalize resources:
<xf:secret ref="secret">
<xf:alert ref="@alert"/>
</xf:secret>
Alternatively, you can nest xf:output elements:
<xf:secret ref="secret">
<xf:hint>
<xf:output value="instance('resources')/help/secret"/>
</xf:hint>
</xf:secret>
Using HTML in LHHA elements
You can also produce HTML, in two
different ways:
-
By using literal XHTML under xf:help or xf:hint:
<xf:input ref="number">
<xf:label>Number</xf:label>
<xf:help>
<div>
<p>This field must contain one of the following values:</p>
<ul>
<li>One</li>
<li>Two</li>
<li>Three</li>
</ul>
</div>
</xf:help>
</xf:input>
NOTE: Elements in the XHTML namespace and in no namespace are supported.
-
By using a nested xf:output with a text/html mediatype:
<xf:input ref="number">
<xf:label>Number</xf:label>
<xf:help>
<xf:output mediatype="text/html" ref="instance('resources')/help/number"/>
</xf:help>
</xf:input>
In this case, the node pointed to by the ref attribute must contain escaped HTML:
<xf:instance id="resources">
<resources>
<help>
<number><div><p>This field must contain one of the following values:</p>
<ul><li>One</li> <li>Two</li>
<li>Three</li></ul></div></number>
</help>
</resources>
</xf:instance>
If you want to have literal XHTML instead of escaped HTML in your resources, you can use
the value attribute on xf:output and the
xxf:serialize extension function:
<xf:input ref="number">
<xf:label>Number</xf:label>
<xf:help><xf:output mediatype="text/html" value="xxf:serialize(instance('resources')/help/number/*, 'html')"/
</xf:help>
</xf:input>
In this case, the resources instance contains:
<xf:instance id="resources">
<resources>
<help>
<number>
<div>
<p>This field must contain one of the following values:</p>
<ul>
<li>One</li>
<li>Two</li>
<li>Three</li>
</ul>
</div>
</number>
</help>
</resources>
</xf:instance>
You can mix and match literal XHTML and xf:output.
[SINCE 2013-03-13 / Orbeon Forms 4.0.1]
You can also specify that a label, hint, help or alert is in HTML by placing a text/html mediatype directly on the element:
<xf:input ref="number">
<xf:label>Number</xf:label>
<xf:help mediatype="text/html" ref="instance('resources')/help/number"/>
</xf:input>
Standalone label, hint, help and alert elements
|
