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 xforms: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 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:
• 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

• local-date()
• local-dateTime()
• now()
• days-from-date()
• days-to-date()
• seconds-from-dateTime()
• available as xforms: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:

• id()
• adjust-dateTime-to-timezone()
NOTE: prefer the XPath 2.0 Timezone Adjustment Functions on Dates and Time Values functions.

Orbeon extension functions

Model binds functions

xxforms:evaluate-bind-property()

The xxforms:evaluate-bind-property() function evaluates a property of a given bind. Depending on the property, it returns:

• xs:string
• calculate
• xxforms: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.


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

xxforms:type()

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:valid()

xxforms:valid() as xs:boolean

xxforms:valid($item as xs:item*) as xs:boolean

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

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

The xxforms: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 no item is available, or if the item is an atomic value, the function returns true().

It recurses into attributes and descendant nodes if the optional second argument is 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 xforms:submission.

Because of the way the XForms processing model is defined, the evaluation of calculate, required, readonly 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 xxforms:valid() to control, for example, whether a button is read-only or relevant will not work.

xxforms:custom-mip

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

xxforms:invalid-binds()

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 ref="age" constraint=". ge 21" id="age-limit"/>...<xforms:action if="xxforms:invalid-binds(event('xxforms:binding')) = 'age-limit'">...</xforms:action>

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

<xforms:alert value="if (xxforms: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

xxforms:evaluate-avt()

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

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

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

xforms:if() / xxforms:if()

xforms:if()
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:event()

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.

xxforms:instance()

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:

• independently from the current in-scope model specified by the model attribute
• across ancestor XBL scopes

<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')/title"/>

</xforms:group>

xxforms:property()

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 ref="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:document-id()

xxforms:document-id() as xs:string

Controls functions

xxforms:context()

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:index()

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 ref="employee" id="employee-repeat"><div><xforms:trigger><xforms:label>Add One</xforms:label><xforms:insert ev:event="DOMActivate" ref="../employee" at="xxforms:index()"/></xforms:trigger></div></xforms:repeat>

xxforms:case()

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:repeat-nodeset()

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

<xforms:repeat id="employee-repeat" ref="employee"><xhtml:div><xforms:output value="count(xxforms:repeat-nodeset('employee-repeat'))"/></xhtml:div></xforms:repeat>

xxforms:repeat-current()

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

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 ref="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.

xxforms:repeat-position()

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

The xxforms:repeat-position() function returns an enclosing xforms:repeat's current iteration position. 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 ref="employee" id="employee-repeat">

    <div>

        <xforms:output value="xxforms:repeat-position()"/>

    </div>

</xforms:repeat>

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

xxforms:pending-uploads()

xxforms:itemset()

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

<xforms: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>

</xforms:instance>

...

<xforms:select1 id="my-select1">

    <xforms:itemset ref="instance('itemset')/fruit">

        <xforms:label ref="description"/>

        <xforms:value ref="@id"/>

    </xforms:itemset>

</xforms:select1>

<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>

[

   [

      "Apple","1"

   ],

   [

      "Banana","2"

   ],

   [

      "Orange","3",true

   ],

   [

      "Kiwi","4"

   ]

]

<xforms: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>

</xforms:instance>

...

<xforms:select1 id="my-select1">

    <xforms:itemset ref="instance('itemset')//item">

        <xforms:label ref="@id"/>

        <xforms:value ref="@id"/>

    </xforms:itemset>

</xforms:select1>

<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>

[
   [
      "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"
            ]
         ]
      ]
   ]
]

xxforms:label, xxforms:help, xxforms:hint, xxforms:alert

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

<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>

XML manipulation

xxforms:create-document()

xxforms:create-document() as document-node()

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

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

xxforms:mutable-document()

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" value="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:sort()

xxforms: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 ref="xxforms:sort(instance('samples-instance')/file, @name, 'text', 'ascending')">...</xforms:itemset>

HTTP request functions

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

<xforms:setvalue ref="request-path" value="xxforms:get-request-path()"/>

Other functions

xxforms:call-xpl()

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')

xxforms:encode-iso9075-14()

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()

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()

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()

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:lang()

[SINCE: 2010-07-27]

xxforms:lang() as xs:string?

The xxforms: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 xxforms:lang() function has an xml:lang attribute, that attribute is used
• otherwise, the first ancestor element of the element containing the xxforms: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 <xhtml:html> element 
• for a dynamic xml:lang value (using an AVT)
• only on the top-level <xhtml:html> element 

NOTE: xml:lang attributes on HTML elements other than the top-level <xhtml:html> are ignored for the purpose of the xxforms: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:

<xforms:group xml:lang="it">

    <!-- This output produces the value "it" -->

    <xforms:output value="xxforms:lang()"/>

    <!-- This output produces the value "zh" -->

    <xforms:output value="xxforms:lang()" xml:lang="zh"/>

</xforms:group>

Example with AVT:

<xhtml:html xml:lang="{instance()}">

    <xhtml:head>

        <xforms:model id="model">

            <xforms:instance id="instance">

                <lang>it</lang>

            </xforms:instance>

        </xforms:model>

    </xhtml:head>

    <xhtml:body>

        <xforms:group>

            <!-- This output produces "it" based on the top-level AVT, which contains the value stored in the instance -->

            <xforms:output value="xxforms:lang()"/>

            <!-- This output produces "zh" -->

            <xforms:output value="xxforms:lang()" xml:lang="zh"/>

        </xforms:group>

    </xhtml:body>

</xhtml:html>

When calling the xxforms: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>

            <xforms:group>

                <!-- The xml:lang value of the bound element is used -->

                <xforms:output value="xxforms:lang()"/>

                <!-- The xml:lang value is "zh" -->

                <xforms:output value="xxforms:lang()" xml:lang="zh"/>

            </xforms:group>

        </xbl:template>

    </xbl:binding>

</xbl:xbl>

xxforms:format-message()

[SINCE: 2010-07-27]

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

The xxforms: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 xxforms:lang() function to determine a locale.

Example with number, date, time, and string:

<xforms:output
  value="xxforms: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:

<xforms:output
  value="xxforms: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.

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

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

xxforms:rewrite-resource-uri($uri as xs:string) as xs:string

Rewrite a URI as an Orbeon Forms resource URI.

XSLT 2.0 functions

eXforms functions