Orbeon Forms User Guide

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 the xxforms prefix). Any such property name will return the value of an XForms engine property. Example:

    <xforms:output value="property('xxforms:noscript')"/>
    Note

    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.

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:

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.

    1. The first argument, $XPLurl, is the URL of the pipeline. It must be an absolute URL.
    2. 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.
    3. 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.
    4. The fourth argument, $outputNames, is a sequence of output names to read.
    5. 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')
  • 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 enclosing xforms:group, xforms:repeat, or xforms: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>
    Note

    See 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 enclosing xforms: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 standard instance() function except that it searches for instances in all the models of the XForms document (the standard instance() 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 XForms index() 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 in properties.xml.

    This function returns the following types: empty sequence (if the property is not found), xs:string, xs:integer, xs:boolean or xs: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 type xs: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 type xs: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 of xxforms: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')"/>
    Note

    This 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 or xforms-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')"/>
    Note

    This 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 or xforms-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 using xxforms: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')"/>
    Note

    This 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 or xforms-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 is true().

    Because of the way the XForms processing model is defined, the evaluation of calculate, required, readonly and relevant takes place during the procesing of the xforms-recalculate event, which generally takes place before the processing of vaidation with the xforms-revalidate event. This means that by default using xxforms: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 returns true() 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 use xforms: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.0 doc() functions, and unlike the instance() 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.1 event() 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()

    Note

    This function is deprecated. Use xxforms:context() or the XForms 1.1 context() function instead.

    The xxforms:repeat-current() function allows you to obtain a reference to an enclosing xforms:repeat's current iteration node. It takes one optional string parameter. If present, the id of the enclosing xforms:repeat is searched. If absent, the function looks for the closest enclosing xforms: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 an xforms: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.