XForms - XPath Function Library

Contents

  1. 1 Standard XForms 1.1 functions
    1. 1.1 Boolean functions
    2. 1.2 Number functions
    3. 1.3 String functions
    4. 1.4 Date and time functions
    5. 1.5 Node-set functions
    6. 1.6 Object functions
    7. 1.7 Functions not yet implemented
  2. 2 Orbeon extension functions
    1. 2.1 Model binds functions
      1. 2.1.1 xxf:bind()
      2. 2.1.2 xxf:evaluate-bind-property()
      3. 2.1.3 xxf:type()
      4. 2.1.4 xxf:valid()
      5. 2.1.5 xxf:custom-mip
      6. 2.1.6 xxf:invalid-binds()
    2. 2.2 Core functions
      1. 2.2.1 xxf:evaluate-avt()
      2. 2.2.2 xf:if() / xxf:if()
      3. 2.2.3 xxf:instance()
      4. 2.2.4 xxf:property()
      5. 2.2.5 xxf:document-id()
      6. 2.2.6 xxf:event()
    3. 2.3 Controls functions
      1. 2.3.1 xxf:binding()
      2. 2.3.2 xxf:context()
      3. 2.3.3 xxf:value()
      4. 2.3.4 xxf:index()
      5. 2.3.5 xxf:case()
      6. 2.3.6 xxf:cases()
      7. 2.3.7 xxf:repeat-items()
      8. 2.3.8 xxf:repeat-current()
      9. 2.3.9 xxf:repeat-position()
      10. 2.3.10 xxf:pending-uploads()
      11. 2.3.11 xxf:itemset()
      12. 2.3.12 xxf:label, xxf:help, xxf:hint, xxf:alert
      13. 2.3.13 xxf:visited
    4. 2.4 XML manipulation
      1. 2.4.1 xxf:evaluate()
      2. 2.4.2 xxf:serialize()
      3. 2.4.3 xf:element() / xxf:element()
      4. 2.4.4 xf:attribute() / xxf:attribute()
      5. 2.4.5 xxf:create-document()
      6. 2.4.6 xxf:mutable-document()
      7. 2.4.7 xxf:extract-document()
      8. 2.4.8 xxf:sort()
    5. 2.5 HTTP request functions
      1. 2.5.1 xxf:get-request-path()
      2. 2.5.2 xxf:get-request-header()
      3. 2.5.3 xxf:get-request-parameter()
      4. 2.5.4 xxf:get-request-attribute()
      5. 2.5.5 xxf:get-session-attribute()
      6. 2.5.6 xxf:set-request-attribute()
      7. 2.5.7 xxf:set-session-attribute()
      8. 2.5.8 xxf:get-remote-user()
      9. 2.5.9 xxf:is-user-in-role()
    6. 2.6 Other functions
      1. 2.6.1 xxf:call-xpl()
      2. 2.6.2 xxf:encode-iso9075-14()
      3. 2.6.3 xxf:decode-iso9075-14()
      4. 2.6.4 xxf:doc-base64()
      5. 2.6.5 xxf:doc-base64-available()
      6. 2.6.6 xxf:lang()
      7. 2.6.7 xxf:format-message()
      8. 2.6.8 xxf:form-urlencode()
      9. 2.6.9 xxf:rewrite-resource-uri()
      10. 2.6.10 xxf:has-class()
      11. 2.6.11 xxf:classes()
  3. 3 eXforms functions

Standard XForms 1.1 functions

The following XForms 1.1 functions are supported:

Boolean functions

  • boolean-from-string()
  • is-card-number()

Number functions

  • avg(), min(), max()
    • available from XPath 2.0
  • count-non-empty()
  • index()
  • power()
  • random()

String functions

  • if()
    • available as xf:if()
    • using a plain if() triggers the native XPath 2.0 if (...) then ... else ... construct
  • property()
    • This function supports extension property names in the http://orbeon.org/oxf/xml/xforms namespace (usually mapped to the xxf prefix). Any such property name will return the value of an XForms engine property. Example:

      <xf:output value="property('xxf:noscript')"/>
    • NOTE: The standard XForms function returns an XPath 1.0 string. The Orbeon Forms implementation returns the following:
      • empty sequence (if the property is not found)
      • xs:string, xs:integer, xs:boolean or xs:anyURI depending on the type of the property
  • digest()
  • hmac()

Date and time functions

NOTE: Prefer the XPath 2.0 date and time functions when possible.
  • local-date()
  • local-dateTime()
  • now()
  • days-from-date()
  • days-to-date()
  • seconds-from-dateTime()
    • available as xf:seconds-from-dateTime() [SINCE: 2011-02-24, was previously in no namespace]
  • seconds-to-dateTime()
  • seconds()
  • months()

Node-set functions

  • instance()
  • current() [SINCE: 2010-06-10]
  • context()

Object functions

  • choose()
    NOTE: se the native XPath 2.0 if (...) then ... else ... construct when possible
  • event()

Functions not yet implemented

The following XForms 1.1 functions are NOT supported as of February 2010:

Orbeon extension functions

Model binds functions

xxf:bind()

xxf:bind(bind-id as xs:string) as node()*

The xxf:bind() function returns the node-set of a given bind:

<!-- The following... --><xf:input bind="my-bind">...</xf:input><!-- ...is equivalent to this: --><xf:input ref="xxf:bind('my-bind')">...</xf:input>

xxf:bind() is particularly useful when referring to a bind is subject to a condition:

<xf:hint ref="for $bind in xxf:bind('my-hint') return if (normalize-space($bind) = '') then instance('default-hint') else $bind"/>

xxf:evaluate-bind-property()

xxf:evaluate-bind-property($bind-id as xs:string, $property-qname as xs:string) as xs:anyAtomicType?

The xxf:evaluate-bind-property() function evaluates a property of a given bind. Depending on the property, it returns:
  • xs:string
    • calculate
    • xxf:default
    • custom MIPs
  • xs:boolean
    • relevant
    • readonly
    • required
    • constraint
  • xs:QName
    • type
If the property is not present on the bind, an empty sequence is returned.

<xf:bind id="my-bind" ref="foo"
             xxf:default="count(preceding-sibling::foo) + 42"
             relevant="count(preceding-sibling::foo) mod 2 = 0"
             type="xs:integer"/>
...
<xf:output value="xxf:evaluate-bind-property('my-bind', 'xxf:default')"/>
<xf:output value="xxf:
evaluate-bind-property('my-bind', 'relevant')"/>
<xf:output value="xxf:
evaluate-bind-property('my-bind', 'type')"/>

NOTE: The property is instantly evaluated, which means that it might be different from the value evaluated during the previous model recalculation or revalidation.

xxf:type()

xxf:type($node as node()?) as xs:QName?

The xxf: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.

<xf:output value="for $t in xxf:type(date) return concat('{', namespace-uri-from-QName($t), '}', local-name-from-QName($t))"><xf:label>Type:</xf:label></xf:output>

xxf:valid()

xxf:valid() as xs:boolean
xxf:valid($item as xs:item*) as xs:boolean
xxf:valid($item as xs:item*, $recurse as xs:boolean) as xs:boolean
xxf:valid($item as xs:item*, $recurse as xs:boolean, $relevant) as xs:boolean

The xxf:valid() function returns the validity of an instance data node or of a subtree of instance data specified by the first argument.

If the first argument is specified, its first item is obtained, if any.

If the first argument is not specified, the context item is used, if any

If the second argument is specified and true(), the function recurses into attributes and descendant nodes.

If no item is available, or if the item is an atomic value, the function returns true().

[SINCE: 2011-10-14] If the optional third argument is specified and set to true(), non-relevant nodes are ignored, as in the case of xf:submission.

Because of the way the XForms processing model is defined, the evaluation of calculaterequiredreadonly and relevant takes place during the processing 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 xxf:valid() to control, for example, whether a button is read-only or relevant will not work.

xxf:custom-mip

[SINCE: 2011-10-14]

xxf:custom-mip($item as item()*, $mip-name as xs:string) as xs:string

Return the value of the custom MIP of the first item specified, if any.

The name of the property must match the qualified name used on the xf:bind that sets the property.

xxf:invalid-binds()

xxf:invalid-binds($node as node()?) as xs:string*

The xxf:invalid-binds() function returns a sequence of strings. If the node was made invalid because of an <xf: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:

<xf:bind ref="age" constraint=". ge 21" id="age-limit"/>...<xf:action if="xxf:invalid-binds(event('xxf:binding')) = 'age-limit'">...</xf:action>

You can also use this function to show bind-specific errors:

<xf:alert value="if (xxf:invalid-binds(.) = 'age-limit') then ... else ..."/>

Note however that the function actually only returns the first invalid bind at the moment, not all of them. So this works for scenarios where error messages go from general to specific.

Core functions

xxf:evaluate-avt()

xxf:evaluate-avt($avt-expression as xs:string) as item()*

This function is similar to saxon:evaluate() or xxf:evaluate(), but instead of evaluating an XPath expression, it evaluates a string representing an attribute value template.

<xf:output value="xxf:evalute-avt('/xforms-sandbox/service/zip-zips?state-abbreviation={state}&amp;city={city}')"/>

xf:if() / xxf:if()

xf:if()
xxf:if()

This function implements the semantic of the XForms 1.0 if() function. See Note About XPath 2.0 Expressions for more details.

xxf:instance()

xxf:instance($instance-id as xs:string) as element()?

The xxf:instance() function works like the standard instance() function except that it searches for instances:

  • independently from the current in-scope model specified by the model attribute
  • across ancestor XBL scopes
The search works as follows:
  • first, in a given XBL scope, the function searches all models within that scope
  • second, it recursively searches ancestor XBL scopes
For example, if there are no XBL components, and 2 top-level models:

<xf:model id="main-model">
  <xf:instance id="main-instance">
    ...
  </xf:instance>
</xf:model>
<xf:model id="resources-model">
  <xf:instance id="resources-instance">
    ...
  </xf:instance>
</xf:model>
...
<xf:group model="main-model">
  <xf:output value="xxf:instance('resources-instance')/title"/>
</xf:group>

[SINCE Orbeon Forms 4.5] The xxf:instance() function can also take an absolute id as parameter.

xxf:property()

xxf:property($property-name as xs:string) as xs:anyAtomicType?

The xxf: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:stringxs:integerxs:boolean or xs:anyURI depending on the actual type of the property.

<xf:repeat ref="employee" id="employee-repeat"><div><xf:trigger><xf:label>Read Property</xf:label><xf:setvalue ev:event="DOMActivate" ref="my-property" value="xxf:property('my.property.name')"/></xf:trigger></div></xf:repeat>

xxf:document-id()

[SINCE: 2011-02-28]

xxf:document-id() as xs:string

Each time an XForms document is created, typically when a user requests a page, it is assigned a unique id.

This function returns the current XForms document (or page)'s unique id.

xxf:event()

NOTE: This function is deprecated since 2012-06-08 and Orbeon Forms 4.
xxf:event($attribute-name as xs:string) as item()*

xxf:event() works like the XForms 1.1 event() function, except that when using XBL components, xxf:event() returns event information from the original event instead of the retargeted event.

Starting 2012-06-08 builds and Orbeon Forms 4, this function is just an alias for the event() function.

Controls functions

xxf:binding()

xxf:binding($control-id as xs:string) as item()*

The xxf: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 xxf:binding() is in response to UI events.


<!-- Store the value of the element to which the first-name control is bound -->
<xf:setvalue ref="my-value" value="xxf:binding('first-name')"/>

NOTE: This function can return not only nodes, but also atomic items.

xxf:context()

xxf:context($element-id as xs:string) as node()

The xxf:context() function allows you to obtain the single-node binding for an enclosing xf:groupxf:repeat, or xf:switch. It takes one mandatory string parameter containing the id of an enclosing grouping XForms control. For xf:repeat, the context returned is the context of the current iteration.

<xf:group ref="employee" id="employee-group"><!-- The context is being set to another instance that controls the visibility of the group. --><xf:group ref="instance('control-instance')/input"><!-- Using xxf:context() allows reclaiming the context of the enclosing group. --><xf:input ref="xxf:context('employee-group')/name"><xf:label>Employee Name</xf:label></xf:input></xf:group></xf:group>
Note

See also the XForms 1.1 context() function, which returns the current evaluation context:

<xf:group ref="employee"><xf:setvalue ref="instance('foo')/name" value="context()/name"/></xf:group>

xxf:value()

[SINCE 2012-11-20]

xxf:value($control-id as xs:string) as xs:string?

The xxf:value() function returns a control's value, it is has any. If the control is non-relevant or cannot hold a value (like xf:group or xf:repeat), the function returns the empty sequence.

NOTE: You must be careful when using this function as a control's value might be out of date. Keep in mind that control values are updated during refresh.

xxf:index()

xxf:index($repeat-id as xs:string?) as xs:integer

The xxf: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 <xf:repeat> element. This function must always be used within <xf:repeat> otherwise an error is raised.

<xf:repeat ref="employee" id="employee-repeat"><div><xf:trigger><xf:label>Add One</xf:label><xf:insert ev:event="DOMActivate" ref="../employee" at="xxf:index()"/></xf:trigger></div></xf:repeat>

xxf:case()

xxf:case($switch-id as xs:string) as xs:string?

The xxf:case() function returns the id of the currently selected <xf:case> within the given <xf:switch>. It is recommended to use this function from XForms actions only.

<xf:switch id="my-switch"><xf:case id="my-case-1">...</xf:case><xf:case id="my-case-2">...</xf:case></xf:switch>...<xf:trigger><xf:label>Add One</xf:label><xf:setvalue if="xxf:case('my-switch')" ref="foobar" value="12"/></xf:trigger>

xxf:cases()

[SINCE: 2012-10-04]
xxf:cases($switch-id as xs:string) as xs:string*

The xxf:cases() function returns a sequence of ids of <xf:case> elements within the given <xf:switch>. It is recommended to use this function from XForms actions only.

xxf:repeat-items()

[SINCE: Orbeon Forms 4.5]

NOTE: This function is also available in previous versions of Orbeon Forms as xxf:repeat-nodeset().
xxf:repeat-nodeset($repeat-id as xs:string?) as node()*

The xxf:repeat-nodeset() function returns the node-set of an enclosing xf:repeat. It takes a string parameter containing the id of an enclosing repeat XForms control. When the argument is omitted, the function returns the index of the closest enclosing <xf:repeat> element. This function must always be used within <xf:repeat> otherwise an error is raised.

<xf:repeat id="employee-repeat" ref="employee">
    <xh:div>
        <xf:output value="count(xxf:repeat-nodeset('employee-repeat'))"/>
    </xh:div>
</xf:repeat>

xxf:repeat-current()

NOTE: You can often use xxf:context() or the XForms 1.1 context() function instead.

xxf:repeat-current($repeat-id as xs:string?) as node()

The xxf:repeat-current() function allows you to obtain a reference to an enclosing xf:repeat's current iteration node. It takes one optional string parameter. If present, the id of the enclosing xf:repeat is searched. If absent, the function looks for the closest enclosing xf:repeat.


<xf:repeat ref="employee" id="employee-repeat">
    <tr>
        <td>
            <!-- The context is being set to another instance that controls the
                 visibility of the group. -->
            <xf:group ref="instance('control-instance')/input">
                <!-- Using xxf:repeat-current() allows reclaiming the context of
                     the repeat iteration. -->
                <xf:input ref="xxf:repeat-current('employee-repeat')/name">
                    <xf:label>Employee Name</xf:label>
                </xf:input>
            </xf:group>
        </td>
    </tr>
</xf:repeat>

The xxf:repeat-current() function must be called from within an xf:repeat element.

xxf:repeat-position()

[SINCE: 2011-08-11]

xxf:repeat-position($repeat-id as xs:string?) as xs:integer

The xxf:repeat-position() function returns an enclosing xf:repeat's current iteration position. It takes one optional string parameter. If present, the id of the enclosing xf:repeat is searched. If absent, the function looks for the closest enclosing xf:repeat.


<xf:repeat ref="employee" id="employee-repeat">
    <div>
        <xf:output value="xxf:repeat-position()"/>
    </div>
</xf:repeat>

The xxf:repeat-current() function must be called from within an xf:repeat element.

xxf:pending-uploads()

xxf:pending-uploads() as xs:integer

The xxf:pending-uploads() function returns the number of known pending uploads in the page.

If there is no pending upload, the function returns 0.

A pending upload is an upload started but not completed yet.

NOTE: The XForms engine is informed of uploads start and completion in an asynchronous way. This function only indicates the best knowledge the server has of the status of uploads at any given time.

See also: Upload control.

xxf:itemset()

xxf:itemset($control-id as xs:string, $format as xs:string, $selected-items as xs:boolean?) as item()?

The xxf:itemset() function returns the current value of a given control's itemset.

  • The first parameter is the id of a selection control (<xf:select> or <xf:select1>).
  • The second parameter is the format to return:
    • xml: an XML document, useful when the result is handled directly in XForms; specifically, the document is returned
    • json: a JSON tree, useful when the result is handled from JavaScript
  • The third, optional parameter determines whether information about selected items is returned [SINCE: 2010-06-11]
The resulting tree represents the itemset hierarchy as seen by the control, with the following information:
  • relevant items
  • hierarchy of the itemset
  • item label
  • item value
  • item help and hint if present [SINCE: Orbeon Forms 4.5]
  • which are the currently selected items, if $selected-items is true()
NOTE: Because itemsets re-evaluate during refresh, it is recommended that this function be used only within action handlers responding to refresh events to ensure consistency.

With the following flat instance and itemset:

<xf:instance id="itemset">
    <fruits>
        <fruit id="1">
            <description>Apple</description>
            <color>Green</color>
        </fruit>
        <fruit id="2">
            <description>Banana</description>
            <color>Yellow</color>
        </fruit>    
        <fruit id="3">
            <description>Orange</description>
            <color>Orange</color>
        </fruit>
        <fruit id="4">
            <description>Kiwi</description>
            <color>Green</color>
        </fruit>
    </fruits>
</xf:instance>
...
<xf:select1 id="my-select1">
    <xf:itemset ref="instance('itemset')/fruit">
        <xf:label ref="description"/>
        <xf:value ref="@id"/>
    </xf:itemset>
</xf:select1>

Example of XML result with xxf:itemset('my-select1', 'xml', true()) (formatted for readability)

<itemset>
    <choices>
        <item>
            <label>Apple</label>
            <value>1</value>
        </item>
        <items>
            <label>Banana</label>
            <value>2</value>
        </item>
        <item selected="true">
            <label>Orange</label>
            <value>3</value>
        </item>
        <item>
            <label>Kiwi</label>
            <value>4</value>
        </item>
    </choices>
</itemset>

In this example, you can access the label of the selected item with xxf:itemset('my-select1', 'xml', true())/itemset/choices/item[@selected = 'true']/value. The following is an example of JSON result with xxf:itemset('my-select1', 'json', true()) (formatted for readability):

[
   [
      "Apple","1"
   ],
   [
      "Banana","2"
   ],
   [
      "Orange","3",true
   ],
   [
      "Kiwi","4"
   ]
]

With the following hierarchical instance and itemset:

<xf:instance id="itemset">
    <items>
        <item id="1"/>
        <item id="2">
            <item id="2.1"/>
            <item id="2.2">
                <item id="2.2.1"/>
                <item id="2.2.2">
                    <item id="2.2.2.1"/>
                    <item id="2.2.2.2"/>
                </item>
            </item>
        </item>
    </items>
</xf:instance>
...
<xf:select1 id="my-select1">
    <xf:itemset ref="instance('itemset')//item">
        <xf:label ref="@id"/>
        <xf:value ref="@id"/>
    </xf:itemset>
</xf:select1>

Example of XML result with xxf:itemset('my-select1', 'xml', true()) (formatted for readability):

<itemset>
    <choices>
        <item>
            <label>1</label>
            <value>1</value>
        </item>
        <item>
            <label>2</label>
            <value>2</value>
            <choices>
                <item selected="true">
                    <label>2.1</label>
                    <value>2.1</value>
                </item>
                <item>
                    <label>2.2</label>
                    <value>2.2</value>
                    <choices>
                        <item>
                            <label>2.2.1</label>
                            <value>2.2.1</value>
                        </item>
                        <item>
                            <label>2.2.2</label>
                            <value>2.2.2</value>
                            <choices>
                                <item>
                                    <label>2.2.2.1</label>
                                    <value>2.2.2.1</value>
                                </item>
                                <item>
                                    <label>2.2.2.2</label>
                                    <value>2.2.2.2</value>
                                </item>
                            </choices>
                        </item>
                    </choices>
                </item>
            </choices>
        </item>
    </choices>
</itemset>

Example of JSON result with xxf:itemset('my-select1', 'json', true()) (formatted for readability):

[
   [
      "1","1"
   ],
   [
      "2","2",
      [
         "2.1","2.1",true
      ],
      [
         "2.2","2.2",
         [
            "2.2.1","2.2.1"
         ],
         [
            "2.2.2","2.2.2",
            [
               "2.2.2.1","2.2.2.1"
            ],
            [
               "2.2.2.2","2.2.2.2"
            ]
         ]
      ]
   ]
]

xxf:label, xxf:help, xxf:hint, xxf:alert

xxf:label($control-id as xs:string) as xs:string?
xxf:help($control-id as xs:string) as xs:string?
xxf:hint($control-id as xs:string) as xs:string?
xxf:alert($control-id as xs:string) as xs:string?

These functions return a control's current label, help, hint, or alert, given a control id.

<xf:input id="my-input" ref="foo">
    <xf:label>Label</xf:label>
</xf:input>

<xf:trigger>
   <xf:label>Get label</xf:label>
    <xf:message ev:event="DOMActivate" value="xxf:label('my-input')"/>
</xf:trigger>

If the control is not  relevant, or does not have an associated label, help, hint, or alert, the empty sequence is returned.

xxf:visited

[SINCE 2012-08-03]

xxf:visited($control-id as xs:string) as xs:boolean?

Whether the given control has been visited, either by losing focus or via the <xxf:setvisited> action.

If the control is not found or not relevant, the function returns the empty sequence.

XML manipulation

xxf:evaluate()

xxf:evaluate($xpath as xs:string) as item()*

The xxf:evaluate() function allows you to evaluate XPath expressions dynamically. For example:

<xf:input ref="xxf:evaluate(concat('instance(''my-instance'')/document', my-xpath))"><xf:label>...</xf:label></xf:input>

xxf:serialize()

xxf:serialize($item as node(), $format as xs:string?) as xs:string

The xxf:serialize() function allows you to serialize an XML node to XML, HTML, XHTML or text. For example:

<xf:bind ref="my-html" calculate="xxf:serialize(instance('my-instance'), 'html')"/>

xf:element() / xxf:element()

NOTE: Since 2012-05-21, this function is also allowed in the XForms namespace, as it is being standardized in XForms 2.0. Prior to this date, it must be in the Orbeon xxf extension namespace.

xf:element($element-name as xs:anyAtomicType) as element()

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

The xf:element() function returns a new XML element with the qualified name provided. If the qualified name is not of type xs:QName, its string value is used. If it has a prefix, it is resolved using in-scope namespaces.

<!-- Insert an element called "value" as a child of element "section" --><xf:insert context="section" origin="xf: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 --><xf:insert context="section" origin="xf:element('value', (xf: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 --><xf:insert context="section" origin="xf:element(resolve-QName('foo:bar', $element))"/>

xf:attribute() / xxf:attribute()

NOTE: Since 2012-05-21, this function is also allowed in the XForms namespace, as it is being standardized in XForms 2.0. Prior to this date, it must be in the Orbeon xxf extension namespace.
xf:attribute($qname as xs:anyAtomicType) as attribute()

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

The xf: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, its string value is used. If it has a prefix, it is resolved using in-scope namespaces. The second argument is an optional value for the attribute. It defaults to the empty string.

<!-- Add an attribute called "id" with a value of "first-name" to element "section" --><xf:insert context="section" origin="xf: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 --><xf:insert context="section" origin="xf:attribute(resolve-QName('foo:bar', $element), 'first-name')"/>

xxf:create-document()

[SINCE: 2011-03-31]
xxf:create-document() as document-node()

The xxf:create-document() creates a new empty XML document. You can then insert new data into that document with the xf:insert action.

<xf:var name="new" value="xxf:create-document()"/>
<xf:insert context="$new" origin="instance('my-data')"/>

xxf:mutable-document()

xxf:mutable-document($node as node()) as document-node()

The xxf:mutable-document() function takes a document as input and returns a mutable document, i.e. a document on which you can for example use xf:setvalue.

<xf:action ev:event="xforms-submit-serialize">
  <!-- Get initial document to submit -->
  <xf:var
    name="request-document"
    value="xxf:mutable-document(saxon:parse(/my/request))"/>

  <!-- Set value -->
  <xf:setvalue
    ref="$request-document/my/first-name">Joe</xf:setvalue>

  <!-- Serialize request document -->
  <xf:setvalue
    ref="event('submission-body')"
    value="saxon:serialize($request-document, instance('my-output-instance'))"/>

</xf:action>

Note that by compatibility with the XSLT document() and XPath 2.0 doc() functions, and unlike the instance() function, xxf:mutable-document() returns a document node, not a document element.

xxf:extract-document()

xxf:extract-document(
  $element as element()
) as document-node()

xxf:extract-document(
  $element as element(),
  $
excludeResultPrefixes as xs:boolean
) as document-node()

xxf:extract-document(
  $element as element(),
  $
excludeResultPrefixes as xs:boolean,
  $
readonly as xs:boolean
) as document-node()

The xxf:extract-document() function extracts a new XML document from a document fragment under an enclosing element. For example with the following instance:

<xf:instance id="my-instance">
    <library>
        <book>
            <title>Jacques le fataliste et son maître</title>
            <author>Denis Diderot</author>
        </book>
    </library>
</xf:instance>

The expression:

xxf:extract-document(instance('my-instance')/book, '', false())

returns a new XML document rooted at the <book> element:

<book>
    <title>Jacques le fataliste et son maître</title>
    <author>Denis Diderot</author>
</book>
  • $excludeResultPrefixes: optional parameter; contains a list of space-separated namespace prefixes to exclude. Defaults to the empty string.
  • $readonly: optional parameter; when set to true(), return a readonly instance. Defaults to false().

xxf:sort()

xxf: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 exf:sort() function: it does not take a plain string but a literal expression, for example:

<xf:itemset
  ref="xxf:sort(instance('samples-instance')/file, @name, 'text', 'ascending')">

  ...
</xf:itemset>

HTTP request functions

xxf:get-request-path()

[SINCE: 2010-09-06]

xxf:get-request-path() as xs:string

The xxf:get-request-path() function returns the path of the incoming HTTP request (without the Java servlet context if any).

<xf:setvalue
  ref="request-path"
  value="xxf:get-request-path()"/>

For builds after 2012-08-16 (including Orbeon Forms 4.0), this function can be used even after page initialization, and can be used everywhere other XPath functions are supported.

For builds before 2012-08-16, 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, or from the xxf:default MIP.

xxf:get-request-header()

xxf:get-request-header($header-name as xs:string) as xs:string*

The xxf:get-request-header() function returns the value(s) of the given request HTTP header.

<!-- Remember the User-Agent header -->
<xf:setvalue
  ref="user-agent"
  value="xxf:get-request-header('User-Agent')"/>

For builds after 2012-08-20 (including Orbeon Forms 4.0), this function can be used even after page initialization, and can be used everywhere other XPath functions are supported.

For builds before 2012-08-20 (including Orbeon Forms 3,8 and 3.9), 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, or from the xxf:default MIP.

xxf:get-request-parameter()

xxf:get-request-parameter($parameter-name as xs:string) as xs:string*

The xxf:get-request-parameter() function returns the value(s) of the given request parameter.

<!-- Remember the "columns" parameter -->
<xf:setvalue
  ref="columns"
  value="xxf:get-request-parameter('columns')"/>

For builds after 2012-08-20 (including Orbeon Forms 4.0), this function can be used even after page initialization, and can be used everywhere other XPath functions are supported.

For builds before 2012-08-20 (including Orbeon Forms 3,8 and 3.9), 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, or from the xxf:default MIP.

NOTE: By default, most if not all servlet containers do not use the UTF-8 encoding but use ISO-8859-1 instead to decode URL parameters. You can configure your servlet container to support UTF-8 instead. See the following resources:

xxf:get-request-attribute()

xxf:get-request-attribute($name as xs:string, $content-type as xs:string?)
  as item()?

The xxf: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 xxf:set-request-attribute(), for example.

The types of attribute objects supported are the same types supported by the Scope generator, plus types stored with xxf:set-request-attribute().

If present, the second parameter can specify the 'text/plain' content type. In that case, if a String object is retrieved, it is return as an xs:string instead of being parsed as XML.

<!-- Get the "document" attribute and use it to replace instance "my-instance" -->
<xf:insert
  ref="instance('my-instance')"
  origin="xxf: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, or from the xxf:default MIP.

xxf:get-session-attribute()

xxf:get-session-attribute($name as xs:string, $content-type as xs:string?)
  as item()?

The xxf: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 xxf:set-session-attribute().

If present, the second parameter can specify the 'text/plain' content type. In that case, if a String object is retrieved, it is return as an xs:string instead of being parsed as XML.

<!-- Get the "document" attribute and use it to replace instance "my-instance" -->
<xf:insert
  ref="instance('my-instance')"
  origin="xxf:get-session-attribute('document')"/>

xxf:set-request-attribute()

xxf:set-request-attribute($name as xs:string, $value item())

The xxf:set-request-attribute() function stores the given value as a request attribute.

<!-- Set the "document" attribute into the request -->
<xf:insert
  context="."
  origin="xxf:set-request-attribute('document', instance('my-instance'))"/>

xxf:set-session-attribute()

xxf:set-session-attribute($name as xs:string, $value item())

The xxf:set-session-attribute() function stores the given value as a session attribute.

<!-- Set the "document" attribute into the session -->
<xf:insert
  context="."
  origin="xxf:set-session-attribute('document', instance('my-instance'))"/>

xxf:get-remote-user()

xxf:get-remote-user() as 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.

xxf:is-user-in-role()

xxf: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.

Other functions

xxf:call-xpl()

xxf: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 xxf:call-xpl function:

xxf:call-xpl(
  'oxf:/examples/sandbox/xpath/run-xpath.xpl',
  ('input', 'xpath'),
  (instance('instance')/input, instance('instance')/xpath),
  'formatted-output')/*,
  'html')

xxf:encode-iso9075-14()

xxf:encode-iso9075-14($value as xs:string) as xs:string

The xxf: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.

xxf:decode-iso9075-14()

xxf:decode-iso9075-14($value as xs:string) as xs:string

The xxf:decode-iso9075-14() function decodes a string according to ISO 9075-14:2003.

xxf:doc-base64()

xxf:doc-base64($href as xs:string) as xs:string

The xxf: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.

xxf:doc-base64-available()

xxf:doc-base64-available($href as xs:string) as xs:boolean

The xxf:doc-base64-available() function reads a resource identified by the given URL. It returns true() if the file can be read, false() otherwise.

xxf:lang()

[SINCE: 2010-07-27]

xxf:lang() as xs:string?

The xxf:lang() function returns the current language as specified with the xml:lang attribute.

The xml:lang value to use is determined this way:

  • if the element containing the xxf:lang() function has an xml:lang attribute, that attribute is used
  • otherwise, the first ancestor element of the element containing the xxf:lang() function that has an xml:lang attribute is used

xml:lang is supported in the following locations:

  • for a static xml:lang value
    • on any XForms element
    • on the top-level <xh:html> element 
  • for a dynamic xml:lang value (using an AVT)
    • only on the top-level <xh:html> element 
NOTE: xml:lang attributes on HTML elements other than the top-level <xh:html> are ignored for the purpose of the xxf:lang() function.

NOTE: Format of the locale is currently restricted to the form "en" or "en-GB". Support for BCP 47 would be desirable.

Example of static values:

<xf:group xml:lang="it">
    <!-- This output produces the value "it" -->
    <xf:output value="xxf:lang()"/>
    <!-- This output produces the value "zh" -->
    <xf:output value="xxf:lang()" xml:lang="zh"/>
</xf:group>


Example with AVT:

<xh:html xml:lang="{instance()}">
    <xh:head>
        <xf:model id="model">
            <xf:instance id="instance">
                <lang>it</lang>
            </xf:instance>
        </xf:model>
    </xh:head>
    <xh:body>
        <xf:group>
            <!-- This output produces "it" based on the top-level AVT, which contains the value stored in the instance -->
            <xf:output value="xxf:lang()"/>
            <!-- This output produces "zh" -->
            <xf:output value="xxf:lang()" xml:lang="zh"/>
        </xf:group>
    </xh:body>
</xh:html>

When calling the xxf:lang() function from an XBL component:

  • xml:lang is first searched as described above
  • if no xml:lang value is found in the XBL component, then the xml:lang value of the XBL bound element is searched
Example:

<xbl:xbl>
    <xbl:binding id="fr-foo" element="fr|foo">
        <xbl:template>
            <xf:group>
                <!-- The xml:lang value of the bound element is used -->
                <xf:output value="xxf:lang()"/>
                <!-- The xml:lang value is "zh" -->
                <xf:output value="xxf:lang()" xml:lang="zh"/>
            </xf:group>
        </xbl:template>
    </xbl:binding>
</xbl:xbl>

xxf:format-message()

[SINCE: 2010-07-27]

xxf:format-message($template as xs:string, $parameters as item()*) as xs:string

The xxf:format-message() function allows you to format a localized message based on a template and parameters.

  • the first parameter is a template string following the syntax of the Java MessageFormat class
  • the second parameter is a sequence of parameters that can be referenced from the template string
The following types are supported:
  • string (the default)
  • number (including currency and percent)
  • date
  • time
The function uses the current language as would be obtained by the xxf:lang() function to determine a locale.

Example with number, date, time, and string:

<xf:output
  value="xxf:format-message('At {2,time,short} on {2,date,long}, we detected {1,number,integer} spaceships on the planet {0}.',
           ('Mars', 3, xs:dateTime('2010-07-23T19:25:13-07:00')))"/>

This produces the following output with an en-US locale:

At 7:25 PM on July 23, 2010, we detected 3 spaceships on the planet Mars.

Example including a choice:

<xf:output
  value="xxf:format-message('There {0,choice,0#are no files|1#is one file|1&lt;are {0,number,integer} files}.', xs:integer(.))"/>

This produces the following outputs, depending on the value provided:

There are no files.

There is one file.

There are 1,273 files.

NOTE: It is important to pass dates and times as typed values. Use xs:dateTime(), xs:date(), or xs:time() if needed to convert from a string.

xxf:form-urlencode()

xxf:form-urlencode($document as node()) as xs:string

Performs application/x-www-form-urlencoded encoding on an XML document.

xxf:rewrite-resource-uri()

[SINCE: 2011-10-09]
xxf:rewrite-resource-uri($uri as xs:string) as xs:string

Rewrite a URI as an Orbeon Forms resource URI.

xxf:has-class()

[SINCE: 2012-10-25]

xxf:has-class($class-name as xs:string) as xs:boolean
xxf:has-class($class-name as xs:string, $el as node()) as xs:boolean

Returns whether the context element, or the given element, has a class attribute containing the specified class name.

xxf:classes()

[SINCE: 2012-10-25]

xxf:classes() as xs:boolean
xxf:classes($el as node()) as xs:string*

Returns for the context element or the given element if provided, all the classes on the class attribute.

XSLT 2.0 functions

The following functions from XSLT 2.0 are  available:

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 xxf:sort():

    <xf:itemset ref="exf:sort(instance('samples-instance')/file, '@name', 'text', 'ascending')">
        ...
    </xf:itemset>

eXForms functions live in the http://www.exforms.org/exf/1-0 namespace, usually bound to the prefix exf or exforms.