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 XForms engine properties.
XForms Reference: XPath Functions
1. Introduction
This part of the XForms reference documentation focuses on extension XPath functions.
Please be sure to visit:
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: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: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" select="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" select="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:valid($node as node(), $recurse as xs:boolean, $check-required-empty 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()
. It takes into account nodes which are required but empty if the optional third 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.However, Orbeon Forms allows you to switch the computation of the
required
,readonly
MIPs to after validation to cover this use case, with thexxforms:computed-binds
property set torevalidate
:<xforms:model xxforms:computed-binds="revalidate"><xforms:instance id="my-instance"><form>...</form></xforms:instance><xforms:instance id="triggers"><triggers><save-trigger/></triggers></xforms:instance><xforms:bind nodeset="instance('triggers')/save-trigger" readonly="not(xxforms:valid(instance('my-instance'), true(), true()))"/></xforms:model>...<xforms:trigger ref="instance('triggers')/save-trigger"><xforms:label>Save</xforms:label></xforms:trigger>The
xxforms:repeat-current()
function must be called from within anxforms:repeat
element. -
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: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()
eXForms functions live in the http://www.exforms.org/exf/1-0
namespace, usually
bound to the prefix exf
or exforms
.