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):

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:

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.

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:

• format-date() (external documentation)

• format-dateTime() (external documentation)

• format-time() (external documentation)

• format-number() (external documentation)

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?).

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

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:

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].

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:

Orbeon Forms supports the built-in xxforms:xml extension type. This types checks that the value is well-formed 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:

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).

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.

Consider this example:

When <xforms:load> is executed, the resource attribute is evaluated. The results is the concatenation of /forms/detail/ and of the result of the expression within brackets:

If the id element pointed to contains the string C728595E0E43A8BF50D8DED9F196A582, the resource attribute takes the value:

Note the following:

• If you need curly brackets as literal values instead of enclosing an XPath expression, escape them using double brackets ({{ and }}).

• You can use as many XPath expressions as you want within a single attributes, each of them enclosed by curly brackets.

AVTs are currently supported on the following attributes:

• <xforms:submission> attributes:

  • method
  • action and resource
  • serialization
  • mediatype
  • version
  • encoding
  • separator
  • indent
  • omit-xml-declaration
  • standalone
  • validate
  • relevant
  • mode
  • xxforms:target
  • xxforms:username
  • xxforms:password
  • xxforms:readonly
  • xxforms:shared
  • xxforms:xinclude

• <xforms:dispatch> attributes:

  • name
  • target
  • bubbles
  • cancelable
  • delay
  • xxforms:show-progress
  • xxforms:progress-message

• <xforms:load> attributes:

  • resource
  • replace
  • xxforms:target
  • xxforms:show-progress
  • f:url-type

• <xforms:setfocus>: control attribute.

• <xforms:toggle>: case attribute.

• <xxforms:show> attributes:

  • dialog
  • neighbor
  • constrain

• <xxforms:hide>: dialog attribute.

• All controls:

  • style: equivalent to the HTML style attribute

• <xxforms:input> and <xxforms:secret> attributes:

  • xxforms:size: equivalent to the HTML size attribute
  • xxforms:maxlength: equivalent to the HTML maxlength attribute
  • xxforms:autocomplete: equivalent to the HTML autocomplete attribute

• <xxforms:textarea> attributes:

  • xxforms:cols: equivalent to the HTML cols attribute
  • xxforms:rows: equivalent to the HTML rows attribute
  • xxforms:maxlength: equivalent to the HTML 5 rows attribute (NOTE: this HTML 5 attribute is not supported by most browsers as of March 2009)

There are plans to support AVTs in more places in the future. Please send your suggestions!

AVTs are also supported on XHTML elements. You must first enable this feature in properties.xml:

For example:

In the above example, the value of the class attribute on <xhtml:tr> is determined dynamically through XPath and XForms. Even table rows get the class zebra-row-even and odd table rows get the class zebra-row-odd.

The values of XHTML attributes built using AVTs update as you interact with the XForms page. In the example above, inserting or deleting table rows after the page is loaded will still correctly update the class attribute.

It is also possible to use AVTs outside <xhtml:body>, for example:

AVTs are also usable on HTML elements within <xforms:label>, <xforms:hint>, <xforms:help>, <xforms:alert>:

You declare dialogs directly under the <xhtml:body> element with:

• When you have appearance="full" on the dialog, you define the title of the dialog with the embedded <xforms:label> element.
• Inside an <xxforms:dialog> you can use all the XHTML and XForms elements you can normally use elsewhere on the page. You can have other XForms controls, or show anything you would like to with HTML.
• The attributes on the <xxforms:dialog> are as follows:

You open a dialog by using the xxforms:show action:

If the dialog is already open, no action takes place.

xxforms:show supports the following attributes:

You close a dialog by using the xxforms:hide action:

If the dialog is already closed, no action takes place.

xxforms:hide supports the following attributes:

Dispatched in response to: xxforms:show action executed with an existing dialog id.

Target: dialog

Bubbles: Yes

Cancelable: Yes

Context Info: none

Default Action: Open the dialog.

You can respond to this event before the dialog opens, for example to perform initialization of data:

Dispatched in response to: xxforms:hide action executed with an existing dialog id.

Target: dialog

Bubbles: Yes

Cancelable: Yes

Context Info: none

Default Action: Close the dialog.

The <xforms:submission> element supports optional xxforms:username and xxforms:password attributes that allow specifying HTTP authentication credentials. You can specify either both attributes, or only the xxforms:username attribute. The latter case is equivalent to setting the value of xxforms:password to an empty string.

The <xforms:submission> automatically forwards current HTTP headers specified by the oxf.xforms.forward-submission-headers property. This property contains a space-separated list of header names to forward:

It can also be set on a per-page basis on your first model element:

Whenever <xforms:submission> performs an HTTP request, it looks at this list of header names and it forwards the header value if the following conditions are met:

• There is an incoming header with that name, i.e. either the HTTP request causing the XForms page to load or the XForms Ajax request to run contains that header.
• There is no author-specifed header with the same name in an <xforms:header> element within <xforms:submission>.

Forwarding the Authorization or other authentication-related headers can be useful to propagate authentication credentials to other services.

When an <xforms:submission> with replace="all" is executed, in general, the browser will load another page. While this happens, the loading indicator, by default shown in red at the top right of the window, is displayed. However, when the browser is served not a web page but say a ZIP file, the browser might ask you in you want to download it, and then stay in the current page. When this happens, the loading indicator does not go away.

In those cases where you know that the target page does not replace the current page, you can prevent the loading indicator from being displayed by adding the xxforms:show-progress="false" attribute:

Similarly the xxforms:show-progress="false" attribute can be used with the xforms:load action:

You can use the xxforms:target attribute on both <xforms:submission> and xforms:load. It behaves just like the HTML target attribute. When used on <xforms:submission>, it makes sense to use this attribute only when you have a replace="all", as the replace="instance" doesn't load another page.

On an <xforms:submission> element with replace="instance", the optional instance attribute specifies a destination instance for the result. That attribute is processed like the instance() function, which means that the instance specified must be in the current model.

The xxforms:instance extension attribute can be use instead of the standard instance attribute. It works like instance, except that the instance is searched globally among all models. xxforms:instance is to the instance attribute what the xxforms:instance() function is to the standard instance() function.

On an <xforms:submission> element with replace="instance", the optional xxforms:xinclude attribute specifies whether XInclude processing should be performed on the XML document returned, before storing it into the destination instance. The default is false.

Orbeon Forms supports sending the text content of an XML document as per XSLT 2.0 and XQuery 1.0 Serialization. To perform a text submission:

• The post or put method is required.

• You must use a the text/plain value for the serialization attribute.

Orbeon Forms supports sending an XML document as HTML or XHTML as per XSLT 2.0 and XQuery 1.0 Serialization. To perform a HTML or XHTML submission:

• The post or put method is required.

• You must use a the text/html or the application/xhtml+xml value for the serialization attribute.

XForms 1.1 does not explicitly support submitting binary content, but does not prohibit it either. Orbeon Forms supports sending the content of a binary resource specified by a URI. Such resources are easily obtained with <xforms:upload>, for example. To perform a binary submission:

• The post or put method is required.

• You must use a binary serialization attribute. This includes all mediatypes which are not XML or text, including application/octet-stream, image/*, etc.

• The node referred to by the submission must be of type xs:anyURI.

Alternatively, you can set the type information using the xsi:type attribute:

The <xxforms:script> action allows you to call client-side JavaScript as a result of XForms events:

Scripts run with <xxforms:script> have access to the following JavaScript variables:

• this. The element observing the event causing <xxforms:script> to run.

• event. Object containing a "target" propeterty. event.target returns the element which is the target of the event causing <xxforms:script> to run.

Orbeon Forms supports an extension attribute, xxforms:readonly, on the <xforms:instance> and <xforms:submission> elements. When set to true, this attribute signals that once loaded, the instance is read-only, with the following consequences:

• The instance is loaded into a smaller, more efficient, read-only data structure in memory.

• Instance values cannot be updated, and no Model Item Properties (MIPs) can be assigned with <xforms:bind> to the instance. But a read-only instance can be replaced entirely by an <xforms:submission replace="instance">

• When using client-side state handling, less data might be transmitted between server and client.

Read-only instances are particularly appropriate for loading internationalization resources, which can be large but don't change. Example:

The xxforms:readonly attribute on <xforms:instance> determines if the instance is read-only until that instance is being replaced. After an instance is replaced, it can be read-only or not irrelevant of the of xxforms:readonly on <xforms:instance>. When the instance is replaced, the replaced instance is read-only if and only if the <xforms:submission> that does the replacement has a attribute xxforms:readonly="true".

When this attribute is set to true on <xforms:submission> and if the targetref attribute is specifed, the replacement target must be an instance's root element.

Orbeon Forms supports a boolean extension attribute, xxforms:cache, on the <xforms:instance> and <xforms:submission> elements. This attribute can be used with instances that are read-only or read-write. When set to true:

• The instance can be shared at the application level. It is identified by its source URL and, in the case of a submission with POST or PUT method, by the body of the request sent.

• The instance is not stored into the XForms document's state, but in a global cache, therefore potentially saving memory. If, upon loading an XForms instance or running a submission, the instance is found in the cache, it is directly retrieved from the cache. This can save time especially if the URL can take significant time to load.

• The instance stored in cache is read-only. If the xxforms:readonly attribute is set to true (on <xforms:instance> or <xforms:submission>), a single copy of the instance is used in memory. Otherwise, a read-write copy is made.

• In general, the URL should refer to a constant or rarely-changing XML document, and authorization credentials such as username and password should not cause different data to be loaded.

Here is how you use the attribute on <xforms:instance>:

When used on <xforms:submission>, the submission has to use method="get", method="post" or method="put" method and replace="instance":

You set the size of the shared instances cache using a property in properties.xml:

You can force the XForms engine to remove a shared instance from the cache by dispatching the xxforms-instance-invalidate event to it. The next time an XForms document requires this instance, it will not be found in the cache and therefore reloaded. Example:

The xxforms:invalidate-instance action allows invalidating a shared instance by resource URI, for example:

This action also supports the xinclude attribute, which if present will only invalidate the instance with the given resource if it was loaded with a matching xxforms:xinclude attribute:

If the xinclude attribute is not specified, any shared instance matching the resource URI is invalidated.

It is also possible to remove all shared instances from the cache by using the xxforms:invalidate-instances action, for example:

The xxforms:ttl attribute can be used to set a time to live for the instance in cache. This duration is expressed in milliseconds and has to be greater than zero. When a shared instance if found in cache but has an associated time to live, if it was put in the cache more than time to live milliseconds in the past, then the instance is discarded from the cache and retrieved again by URI as if it had not been found in cache at all. The following example expires the shared instance after one hour:

XForms specifies that items and itemsets are re-evaluated when processing xforms-refresh. This may happen quite often, and may lead to time-consuming re-evaluations especially when there are many or large itemsets.

Orbeon Forms supports an extension attribute, xxforms:refresh-items, on the <xforms:select> and <xforms:select1> elements. When set to true (the default), items and itemsets are re-computed upon xforms-refresh event processing. When set to false, this attribute signals that once computed, the set of items for the control will not be recomputed upon xforms-refresh event processing.

If you know that itemsets do not change over time, setting xxforms:refresh-items to false disables refreshing of the items during xforms-refresh and may yield significant performance improvements. For example:

<xforms:group> supports the xxforms:internal appearance, which causes the group to have no representation at all on the client:

In general you won't have a need for this appearance, but it is useful as an optimization, as it leads to less HTML sent to the client. You may use it when a group is used only to change the in-scope evaluation context for nested controls and when you don't need changes to relevance which apply directly to the group to be reflected in the client.

[TODO: describe the Orbeon Forms xxforms:tree appearance on xforms:select and xforms:select1]

[TODO: describe the Orbeon Forms xxforms:tree appearance on xforms:select1]

[TODO: describe the Orbeon Forms xxforms:autocomplete appearance on xforms:select and xforms:select1]

This section has migrated to the wiki.

<xforms:output> supports the xxforms:download appearance, which causes the the resource identified by the single-node binding to be downloadable through a link.

Like <xforms:upload>, when using this appearance, <xforms:mediatype> and <xforms:filename> children elements are allowed (but not the <xxforms:size> element). When serving the file, if these elements are present, they are passed to the resulting HTTP response to provide mediatype and file name hints to the browser. Example:

The data type for the resource must be xs:anyURI or xs:base64Binary.

<xforms:select1> supports an extension attribute called xxforms:group which allows grouping a series of radio buttons together in a way similar to the name attribute in HTML.

In general, this attribute is not necessary. It is useful in the following case:

• Multiple <xforms:select1 appearance="full"> point to the same node.

• You enable deferred event handling on the client.

The xxforms:group attribute must contain an identifier unique between groups of radio controls. Example: