The XForms Function Library Module

From W3C XForms Group Wiki (Public)

__NUMBEREDHEADINGS__



Document title:
The XForms Function Library Module
Editors
Nick Van den Bleeken, Inventive Designers
Abstract
This document, developed by the Forms Working Group, defines the XForms Function Library. The XForms Function Library includes besides the entire [XPath 1.0] Core Function Library, also additional required functions for use within XForms : #Boolean Functions, #Number Functions, #String Functions, #Date and Time Functions, #Node-set Functions , and #Object Functions. Currently this spec only contains changes relative to XForms 1.1, i.e. it only contains new functions or functions that have enhanced functionality.
Status of this Document
This is a live wiki document. Although it often reflects the best understanding of the editors and members of the Working Group, it may be inaccurate and has not necessarily been reviewed. If you need a stable copy, use the most recent official version: http://www.w3.org/TR/xformfunctions.


Copyright © 2010 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.

Overview

The XForms Function Library includes the entire [XPath 1.0] Core Function Library, including operations on node-sets, strings, numbers, and booleans.

The following sections define additional required functions for use within XForms : #Boolean Functions, #Number Functions, #String Functions, #Date and Time Functions, #Node-set Functions , and #Object Functions.

The function library provided by an XForms processor may also contain other extension functions as described in #Extension Functions.

If an error occurs in an XPath function, then an #The xforms-compute-exception Event or #The xforms-binding-exception Event occurs.


Boolean Functions

Number Functions

String Functions

Date and Time Functions

Node-set Functions

The xf:element() function

element() xf:element($qname as xs:anyAtomicType, $content as item()*)

This function returns a new XML element with the qualified name provided. If the qualified name is not of type xs:QName the namespace of the element is resolved using the in-scope namespaces (the in-scope default namespace is used for qualified names that are unprefixed). The second, optional argument can take a sequense of items specifying attributes and content for the new element (all literals are added as child text nodes).

The resulting element, and all of its descendants, will behave like they have a readonly model item property with value true() attached to them. The read-onlyness of the returned result can't be removed. The returned result will behave like an implicitly created instance with the root node having a readonly model item property set to true(), additionally there will be no way to remove the read-onlyness, not even with an explicit override using a bind element.

Note:

When an XPath 1.0 processor is used the first argument is always a string

Note:

When an XPath 1.0 processor is used the second argument will be a node-set


Examples:

Insert an element called "value" as a child of element "section"
<xforms:insert context="section" origin="xf:element('value')"/>
Insert an element called "value" as a child of element "section", with an attribute and text from an instance
<xforms:insert context="section" origin="xf:element('value', xf:attribute('id', 'my-value') | ../name/text())"/>
Insert an element called "value" as a child of element "section", with an attribute and text content (requires an XPath 2.0 enabled XForms implementation)
<xforms:insert context="section" origin="xf:element('value', (xf:attribute('id', 'my-value'), 'John'))"/>

The xf:attribute() function

attribute() xf:attribute($qname as xs:anyAtomicType, $value as xs:anyAtomicType?)

This function returns a new XML attribute with the qualified name provided as first argument. If the qualified name is not of type xs:QName the namespace of the element is resolved using the in-scope namespaces (the in-scope default namespace is used for qualified names that are unprefixed). The second argument is an optional value for the attribute with the empty string as default

The resulting attribute will behave like it has a readonly model item property with value true() attached to it. The read-onlyness of the returned result can't be removed.


Note:

When an XPath 1.0 processor is used the arguments are of type string

Example:

Add an attribute called "id" with a value of "first-name" to element "section"
<xforms:insert context="section" origin="xf:attribute('id', 'first-name')"/>

Object Functions

Extension Functions