The standard XForms function returns an XPath 1.0 string
. The Orbeon Forms
implementation returns the following types: empty sequence (if the property is not found),
xs:string
, xs:integer
, xs:boolean
or
xs:anyURI
depending on the type of the property.
XForms Reference: XPath Functions
1. Introduction
This part of the XForms reference documentation focuses on extension XPath functions supported by the XForms engine.
2. Standard XForms Functions
Orbeon Forms supports the following standard XForms functions:
- [TODO: most other functions are supported, provide exact list]
-
property($property-name as xs:string) as xs:anyAtomicType?
This function supports extension property names in the
http://orbeon.org/oxf/xml/xforms
namespace (usually mapped to thexxforms
prefix). Any such property name will return the value of an XForms engine property. Example:<xforms:output value="property('xxforms:noscript')"/>Note
3. XPath Extension Functions
Orbeon Forms implements some extension functions which can be used from XPath expressions in XForms documents.
3.1. XSLT 2.0 Functions
When using XPath 2.0, the following functions from XSLT 2.0 are also available:
-
format-date()
(external documentation) -
format-dateTime()
(external documentation) -
format-time()
(external documentation) -
format-number()
(external documentation)
3.2. Orbeon Forms Functions
The following functions are implemented:
-
xxforms:if()
This function implements the semantic of the XForms 1.0
if()
function. See Note About XPath 2.0 Expressions for more details. -
xxforms:call-xpl($xplURL as xs:string, $inputNames as xs:string*, $inputElements as element()*, $outputNames as xs:string+) as document-node()*
This function lets you call an XPL pipeline.
-
The first argument,
$XPLurl
, is the URL of the pipeline. It must be an absolute URL. -
The second argument,
$inputNames
, is a sequence of strings, each one representing the name of an input of the pipeline that you want to connect. -
The third argument,
$inputElements
, is a sequence of elements to be used as input for the pipeline. The$inputNames
and$inputElements
sequences must have the same length. For each element in$inputElements
, a document is created and connected to an input of the pipeline. Elements are matched to input name by position, for instance the element at position 3 of$inputElements
is connected to the input with the name specified at position 3 in$inputNames
. -
The fourth argument,
$outputNames
, is a sequence of output names to read. -
The function returns a sequence of document nodes corresponding the output of the
pipeline. The returned sequence will have the same length as
$outputNames
and will correspond to the pipeline output with the name specified on$outputNames
based on position.
The example below shows a call to the
xxforms:call-xpl
function:xxforms:call-xpl ('oxf:/examples/sandbox/xpath/run-xpath.xpl', ('input', 'xpath'), (instance('instance')/input, instance('instance')/xpath), 'formatted-output')/*, 'html') -
The first argument,
-
xxforms:evaluate($xpath as xs:string) as item()*
The
xxforms:evaluate()
function allows you to evaluate XPath expressions dynamically. For example:<xforms:input ref="xxforms:evaluate(concat('instance(''my-instance'')/document', my-xpath))"><xforms:label>...</xforms:label></xforms:input> -
xxforms:serialize($item as node(), $format as xs:string?) as xs:string
The
xxforms:serialize()
function allows you to serialize an XML node to XML, HTML, XHTML or text. For example:<xforms:bind nodeset="my-html" calculate="xxforms:serialize(instance('my-instance'), 'html')"/> -
xxforms:context($element-id as xs:string) as node()
The
xxforms:context()
function allows you to obtain the single-node binding for an enclosingxforms:group
,xforms:repeat
, orxforms:switch
. It takes one mandatory string parameter containing the id of an enclosing grouping XForms control. For xforms:repeat, the context returned is the context of the current iteration.<xforms:group ref="employee" id="employee-group"><!-- The context is being set to another instance that controls the visibility of the group. --><xforms:group ref="instance('control-instance')/input"><!-- Using xxforms:context() allows reclaiming the context of the enclosing group. --><xforms:input ref="xxforms:context('employee-group')/name"><xforms:label>Employee Name</xforms:label></xforms:input></xforms:group></xforms:group>NoteSee also the XForms 1.1
context()
function, which returns the current evaluation context:<xforms:group ref="employee"><xforms:setvalue ref="instance('foo')/name" value="context()/name"/></xforms:group> -
xxforms:bind(bind-id as xs:string) as node()*
The
xxforms:bind()
function returns the node-set of a given<xforms:bind>
:<!-- The following... --><xforms:input bind="my-bind">...</xforms:input><!-- ...is equivalent to this: --><xforms:input ref="xxforms:bind('my-bind')">...</xforms:input>xxforms:bind()
is particularly useful when referring to a bind is subject to a condition:<xforms:hint ref="for $bind in xxforms:bind('my-hint') return if (normalize-space($bind) = '') then instance('default-hint') else $bind"/> -
xxforms:repeat-nodeset($repeat-id as xs:string) as node()*
The
xxforms:repeat-nodeset()
function returns the node-set of an enclosingxforms:repeat
. It takes one mandatory string parameter containing the id of an enclosing repeat XForms control.<xforms:repeat id="employee-repeat" nodeset="employee"><xhtml:div><xforms:output value="count(xxforms:repeat-nodeset('book-repeat'))"/></xhtml:div></xforms:repeat> -
xxforms:instance($instance-id as xs:string) as element()?
The
xxforms:instance()
function works like the standardinstance()
function except that it searches for instances in all the models of the XForms document (the standardinstance()
function only searches within the current XForms model).<xforms:model id="main-model"><xforms:instance id="main-instance">...</xforms:instance></xforms:model><xforms:model id="resources-model"><xforms:instance id="resources-instance">...</xforms:instance></xforms:model>...<xforms:group model="main-model"><xforms:output value="xxforms:instance('resources-instance')/titles/company-information"/></xforms:group> -
xxforms:index($repeat-id as xs:string?) as xs:integer
The
xxforms:index()
function behaves like the standard XFormsindex()
function, except that its argument is optional. When the argument is omitted, the function returns the index of the closest enclosing<xforms:repeat>
element. This function must always be used within<xforms:repeat>
otherwise an error is raised.<xforms:repeat nodeset="employee" id="employee-repeat"><div><xforms:trigger><xforms:label>Add One</xforms:label><xforms:insert ev:event="DOMActivate" nodeset="../employee" at="xxforms:index()"/></xforms:trigger></div></xforms:repeat> -
xxforms:case($switch-id as xs:string) as xs:string?
The
xxforms:case()
function returns the id of the currently selected<xforms:case>
within the given<xforms:switch>
. It is recommended to use this function from XForms actions only.<xforms:switch id="my-switch"><xforms:case id="my-case-1">...</xforms:case><xforms:case id="my-case-2">...</xforms:case></xforms:switch>...<xforms:trigger><xforms:label>Add One</xforms:label><xforms:setvalue if="xxforms:case('my-switch')" ref="foobar" value="12"/></xforms:trigger> -
xxforms:property($property-name as xs:string) as xs:anyAtomicType?
The
xxforms:property()
function retrieves the value of a property defined inproperties.xml
.This function returns the following types: empty sequence (if the property is not found),
xs:string
,xs:integer
,xs:boolean
orxs:anyURI
depending on the actual type of the property.<xforms:repeat nodeset="employee" id="employee-repeat"><div><xforms:trigger><xforms:label>Read Property</xforms:label><xforms:setvalue ev:event="DOMActivate" ref="my-property" value="xxforms:property('my.property.name')"/></xforms:trigger></div></xforms:repeat> -
xxforms:element($element-name as xs:anyAtomicType?) as element()
xxforms:element($element-name as xs:anyAtomicType?, $content as item()*) as element()
The
xxforms:element()
function returns a new XML element with the qualified name provided. If the qualified name is not of typexs:QName
and if it has a prefix, it is resolved using in-scope namespaces.<!-- Insert an element called "value" as a child of element "section" --><xforms:insert context="section" origin="xxforms:element('value')"/>The second, optional argument can take a sequence of items specifying attributes and content for the new element:
<!-- Insert an element called "value" as a child of element "section", with an attribute and text content --><xforms:insert context="section" origin="xxforms:element('value', (xxforms:attribute('id', 'my-value'), 'John'))"/>The first argument can be of type
xs:QName
:<!-- Insert an element called "foo:bar" as a child of element "section" and resolve the namespaces on element $element --><xforms:insert context="section" origin="xxforms:element(resolve-QName('foo:bar', $element))"/> -
xxforms:attribute($qname as xs:anyAtomicType?, $value as xs:anyAtomicType?) as attribute()
The
xxforms:attribute()
function returns a new XML attribute with the qualified name provided as first argument. If the qualified name is not of typexs:QName
and if it has a prefix, it is resolved using in-scope namespaces. The second argument is an optional value for the attribute. It default to the empty string.<!-- Add an attribute called "id" with a value of "first-name" to element "section" --><xforms:insert context="section" origin="xxforms:attribute('id', 'first-name')"/>The first argument can be of type
xs:QName
:<!-- Add an attribute called "id" with a value of "foo:bar" to element "section" and resolve the namespaces on element $element --><xforms:insert context="section" origin="xxforms:attribute(resolve-QName('foo:bar', $element), 'first-name')"/> -
xxforms:binding($control-id as xs:string) as node()*
The
xxforms:binding()
function returns a control's binding, that is the node or nodes to which the control is bound. Use this function carefully, as depending on when this function is called during XForms processing, it may refer to stale nodes. Likely the safest use ofxxforms:binding()
is in response to UI events.<!-- Store the value of the element to which the first-name control is bound --><xforms:setvalue ref="my-value" value="xxforms:binding('first-name')"/> -
xxforms:get-request-header($header-name as xs:string) as xs:string*
The
xxforms:get-request-header()
function returns the value(s) of the given request HTTP header.<!-- Remember the User-Agent header --><xforms:setvalue ref="user-agent" value="xxforms:get-request-header('User-Agent')"/>NoteThis function can only be called during page initialization, otherwise it will throw an error. We recommend you use it only within event handlers called as a result of processing
xforms-model-construct-done
orxforms-ready
. -
xxforms:get-request-parameter($parameter-name as xs:string) xs:string*
The
xxforms:get-request-parameter()
function returns the value(s) of the given request parameter.<!-- Remember the "columns" parameter --><xforms:setvalue ref="columns" value="xxforms:get-request-parameter('columns')"/>NoteThis function can only be called during page initialization, otherwise it will throw an error. We recommend you use it only within event handlers called as a result of processing
xforms-model-construct-done
orxforms-ready
. -
xxforms:get-request-attribute($name as xs:string) document-node()?
The
xxforms:get-request-attribute()
function returns the value of the given request attribute. The attribute may have been previously placed in the request through Java code, or usingxxforms:set-request-attribute()
, for example.The types of attribute objects supported are the same types supported by the Scope generator, plus types stored with
xxforms:set-request-attribute()
.<!-- Get the "document" attribute and use it to replace instance "my-instance" --><xforms:insert nodeset="instance('my-instance')" origin="xxforms:get-request-attribute('document')"/>NoteThis function can only be called during page initialization, otherwise it will throw an error. We recommend you use it only within event handlers called as a result of processing
xforms-model-construct-done
orxforms-ready
. -
xxforms:get-session-attribute($name as xs:string) document-node()?
The
xxforms:get-session-attribute()
function returns the value of the given session attribute.The types of attribute objects supported are the same types supported by the Scope generator, plus types stored with
xxforms:set-session-attribute()
.<!-- Get the "document" attribute and use it to replace instance "my-instance" --><xforms:insert nodeset="instance('my-instance')" origin="xxforms:get-session-attribute('document')"/> -
xxforms:set-request-attribute($name as xs:string, $value item()) ()
The
xxforms:set-request-attribute()
function stores the given value as a request attribute.<!-- Set the "document" attribute into the request --><xforms:insert context="." origin="xxforms:set-request-attribute('document', instance('my-instance'))"/> -
xxforms:set-session-attribute($name as xs:string, $value item()) ()
The
xxforms:set-session-attribute()
function stores the given value as a session attribute.<!-- Set the "document" attribute into the session --><xforms:insert context="." origin="xxforms:set-session-attribute('document', instance('my-instance'))"/> -
xxforms:get-remote-user() xs:string?
Returns the username for the current user of the application, if known by the container, for instance because users log in with BASIC of FORM-based authentication.
-
xxforms:is-user-in-role(xs:string) as xs:boolean
Returns true if and only if the container recognizes that the current user of the application has the specified role. Roles will be typically known by the container when users are logged in using either BASIC or FORM-based authentication.
-
xxforms:valid($node as node()?, $recurse as xs:boolean) as xs:boolean
The
xxforms:valid()
function returns the validity of a instance data node or of a subtree of instance data. It recurses into attribute and descendant nodes if the optional second argument istrue()
.Because of the way the XForms processing model is defined, the evaluation of
calculate
,required
,readonly
andrelevant
takes place during the procesing of thexforms-recalculate
event, which generally takes place before the processing of vaidation with thexforms-revalidate
event. This means that by default usingxxforms:valid()
to control, for example, whether a button is read-only or relevant will not work. -
xxforms:type($node as node()?) as xs:QName?
The
xxforms:type()
function returns the type of the instance data node passed as parameter. If an empty sequence is passed, the function returns an empty sequence. Otherwise, the type of the instance data node is searched. If no type information is available, the function returns an empty sequence. Otherwise, a QName associated with the type is returned.<xforms:output value="for $t in xxforms:type(date) return concat('{', namespace-uri-from-QName($t), '}', local-name-from-QName($t))"><xforms:label>Type:</xforms:label></xforms:output> -
xxforms:invalid-binds($node as node()?) as xs:string*
The
xxforms:invalid-binds()
function returns a sequence of strings. If the node was made invalid because of an<xforms:bind>
element, then the id of that bind element is present in the list.This function is useful to help determine the reason why a node is invalid:
<xforms:bind nodeset="age" constraint=". ge 21" id="age-limit"/>...<xforms:action if="xxforms:invalid-binds(event('xxforms:binding')) = 'age-limit'">...</xforms:action> -
xxforms:encode-iso9075-14($value as xs:string) as xs:string
The
xxforms:encode-iso9075-14()
function encodes a string according to ISO 9075-14:2003. The purpose is to escape any character which is not valid in an XML name. -
xxforms:decode-iso9075-14($value as xs:string) as xs:string
The
xxforms:decode-iso9075-14()
function decodes a string according to ISO 9075-14:2003. -
xxforms:doc-base64($href as xs:string) as xs:string
The
xxforms:doc-base64()
function reads a resource identified by the given URL, and returns the content of the file as a Base64-encoded string. It is a dynamic XPath error if the resource cannot be read. -
xxforms:doc-base64-available($href as xs:string) as xs:boolean
The
xxforms:doc-base64-available()
function reads a resource identified by the given URL. It returnstrue()
if the file can be read,false()
otherwise. -
xxforms:mutable-document($node as node()) as document-node()
The
xxforms:mutable-document()
function takes a document as input and returns a mutable document, i.e. a document on which you can for example usexforms:setvalue
.<xforms:action ev:event="xforms-submit-serialize"><!-- Get initial document to submit --><xxforms:variable name="request-document" select="xxforms:mutable-document(saxon:parse(/my/request))"/><!-- Set value --><xforms:setvalue ref="$request-document/my/first-name">Joe</xforms:setvalue><!-- Serialize request document --><xforms:setvalue ref="event('submission-body')" value="saxon:serialize($request-document, instance('my-output-instance'))"/></xforms:action>Note that by compatibility with the XSLT
document()
and XPath 2.0doc()
functions, and unlike theinstance()
function,xxforms:mutable-document()
returns a document node, not a document element -
xxforms:event($attribute-name as xs:string) as item()*
xxforms:event()
works like the XForms 1.1event()
function, except that when using XBL components,xxforms:event()
returns event information from the original event instead of the retargetted event. -
exf:sort($sequence as item()*, $sort-key as item(), $datatype as xs:string?, $order as xs:string?, $case-order as xs:string?) as item()*
Note that the second argument differs from the
exforms:sort()
function: it does not take a plain string but a literal expression, for example:<xforms:itemset nodeset="xxforms:sort(instance('samples-instance')/file, @name, 'text', 'ascending')">...</xforms:itemset> -
xxforms:repeat-current($repeat-id as xs:string?) as node()
NoteThis function is deprecated. Use
xxforms:context()
or the XForms 1.1context()
function instead.The
xxforms:repeat-current()
function allows you to obtain a reference to an enclosingxforms:repeat
's current iteration node. It takes one optional string parameter. If present, the id of the enclosingxforms:repeat
is searched. If absent, the function looks for the closest enclosingxforms:repeat
.<xforms:repeat nodeset="employee" id="employee-repeat"><tr><td><!-- The context is being set to another instance that controls the visibility of the group. --><xforms:group ref="instance('control-instance')/input"><!-- Using xxforms:repeat-current() allows reclaiming the context of the repeat iteration. --><xforms:input ref="xxforms:repeat-current('employee-repeat')/name"><xforms:label>Employee Name</xforms:label></xforms:input></xforms:group></td></tr></xforms:repeat>The
xxforms:repeat-current()
function must be called from within anxforms:repeat
element.
3.3. eXForms Functions
eXForms is a suggested set of extensions to XForms 1.0,
grouped into different modules. Orbeon Forms supports the exf:mip
module, which includes the
following functions:
-
exf:relevant()
-
exf:readonly()
-
exf:required()
Orbeon Forms also supports the following from the sorting module:
-
exf:sort($sequence as item()*, $sort-key as xs:string, $datatype as xs:string?, $order as xs:string?, $case-order as xs:string?) as item()*
Note that the second argument is interpreted as a string, unlike with
xxforms:sort()
:<xforms:itemset nodeset="exforms:sort(instance('samples-instance')/file, '@name', 'text', 'ascending')">...</xforms:itemset>
eXForms functions live in the http://www.exforms.org/exf/1-0
namespace, usually
bound to the prefix exf
or exforms
.