Examples
Say you have a Yes/No Answer field (before 2016.1 called Boolean Input), named
yes-no
, and if the answer is Yes, you would like to show another field. In the Visibility expression for this other field, you should write:$yes-no/string() = 'true'
- Why not just write
$yes-no
? If you do, the expression will always evaluate to true, because Orbeon Forms evaluatesboolean($yes-no)
: since$yes-no
points to a node, theboolean
function always returns true. - Why not write
$yes-no = true()
? In this case, since$yes-no
compared to boolean value, it is atomized. The node pointed to by$yes-no
is of type boolean, so the atomization process takes the node typed value. When the node contains the stringtrue
orfalse
, this expression works as expected. However, if it contains an empty string, which up to Orbeon Forms 2017.2 is the default value for that field, then the expression fails. For the purpose of determining whether a field is valid, read-only, or visible, when the expression fails the result will be considered to befalse
, so it will work if the expression is used on its own. However, if the expression is used in anor
clause ($yes-no = true() or something
), if the$yes-no = true()
part is evaluated first, the expression as a whole will fail and return false, which is incorrect in case the other part of theor
clause is true. Also, in the case of a calculated value, the result will be the empty string, instead offalse
.
Scenario: compute the sum of values in multiple repeat repetitions. Say you have:
- a repeated grid
- a decimal field called
price
on each row - an integer field called
quantity
on each row - a decimal text output field called
row-total
on each row - a decimal text output field called
total
below the grid
You want to compute the row totals and athe general total.
Calculated value expression for
row-total
:$price * $quantity
Calculated value expression for
total
:sum($row-total[string() castable as xs:decimal], 0.0)
Explanation:
- when accessing control values with variables, the "closest" variables are found
- this means that the
row-total
control calculation applies to the closestprice
andquantity
controls, that is, those on the same row, and each row gets its own total - the
total
calculation is outside the repeat, and when it refers to$row-total
, allrow-total
values are returned sum()
is a standard XPath function to compute the sum of a sequence of items- the predicate
[string() castable as xs:decimal]
excludes values that are blank or not a decimal number sum()
supports a second argument which is the value to return in case no value satisfies the predicate (this makes sure that we return a decimal value, as we are using a literal decimal 0.0)
See also:
Scenario: compute the sum of values in multiple repeat repetitions.
Say you have:
- a repeat called
my-repeat
- with a decimal field called
number
on each row
Calculated value expression:
sum($my-repeat/number[string() castable as xs:decimal])
Explanation:
$my-repeat
points to the repeat data's enclosing XML elements- the nested
/number
path points to thenumber
field within each iteration [string() castable as xs:decimal]
excludes values that are blank or not a decimal numbersum()
is a standard XPath function to compute the sum of a sequence of items-
Scenario: Make the current integer number field valid only if its value is between two values, say 12 and 17 included.
Expression:
. >= 12 and . <= 17
Explanation:
.
refers to the current value of the control>=
orge
means "greater than or equals to"<=
orle
means "less than or equals to"and
is the logical "and" operator
If you want to refer to a specific control by name, you can use:
$my-control >= 12 and $my-control <= 17
Scenario: Make the current field valid only if its length is between two values, say 2 and 140.
Expression:
string-length(.) >= 2 and string-length(.) <= 140
Explanation:
.
refers to the current value of the control- The standard
string-length()
function returns the length of its argument >=
orge
means "greater than or equals to"<=
orle
means "less than or equals to"and
is the logical "and" operator
If you want to refer to a specific control by name, you can use:
string-length($message) >= 2 and string-length($message) <= 140
[SINCE Orbeon Forms 4.10]
The same can be expressed, for the current control, as:
xxf:min-length(2) and xxf:max-length(140)
Scenario: check that a given value matches a regular expression, for example "only ASCII letters and digits, the dash, and underscore character".
matches(., '^[A-Za-z0-9\-_]+$')
Explanation:
- the standard
matches()
function applies the regular expression passed as second argument to the first argument, and returns true if it does match
Scenario: check that a given number value is either blank or has exactly 5 digits.
matches(string(.), '\d{5}') or xxf:is-blank(string(.))
Explanation:
- the standard
matches()
function applies the regular expression passed as second argument to the first argument, and returns true if it does match - the built-in
xxf:is-blank()
function returnstrue()
if the value passed is blank - since the data is a number, we use the
string(.)
function to convert the value to a string before passing it to functions
Scenario: Make a control read-only if the value of the
first-name
control is blank:Expression:
xxf:is-blank($first-name)
Explanation:
$first-name
returns the value of the control with name "first-name"- the built-in
xxf:is-blank()
function returnstrue()
if the value passed is blank
Scenario: As a form author, you can set a static initial value for a control simply by setting that value at design time. For example:
- Enter a value in an input field
- Select an item in a dropdown list
But not all initial values can be static. For example, you might want a date selection control to contain the current date until the user changes it. In this case, you can use an "Initial Value" expression.
Initial Value expression:
current-date()
Explanation:
current-date()
is a standard XPath function returning the current date.
Scenario: compute the sum of two numbers entered by the user in two fields, "quantity1" and "quantity2".
Calculated Value expression:
if ($quantity1 castable as xs:integer and $quantity2 castable as xs:integer)
then $quantity1 + $quantity2
else ''
Explanation:
if (...) then ... else ...
evaluates a condition and then returns one of two alternatives- the condition
quantity1 castable as xs:integer
checks that the value from the field "quantity1" is an integer quantity1 + $quantity2
simply adds the two values- the value
''
represents an empty string This can be specified for example on a Text Output control.
NOTE: If the value of a control is calculated, by default it is also marked as read-only. If you want a calculated control to be still editable by the user, set its Read-Only property explicitly to
false()
.$name[2]
: return the value of the control in the second iterationstring-join($name, ', ')
: join all values with commascount($name)
: return the number of values
NOTE: This works when the expression is outside repeat repetitions. For expressions within the same repeat,
$name
returns the closest control.The Form Runner detail page can have the following modes:
new
edit
view
pdf
email
test
(when you are testing a form within Form Builder)
fr:mode() = 'edit'
A special XPath variable named
$fr-mode
is exposed by Form Runner to all XPath expressions.You can test the mode as follows, for example in a Visibility expression:
$fr-mode = 'edit'
It can be useful to access HTTP headers to set default values upon form initialization, for example when single sign-on systems use HTTP headers as a way of communicating information to an application.
XPath expressions have access to a special function,
xxf:request-header()
, which allows retrieving a header by name. Example of setting the default value of a field using an initial value:xxf:get-request-header('full-name')
NOTE: With Orbeon Forms 3.8 and 3.9, headers cannot be reliably accessed after the form is initialized, so this function should be used for setting initial values on controls only. See the next scenario for a workaround.
Scenario: field
my-attachment
must be a PDF file.Constraint expression:
ends-with(lower-case($my-attachment/@filename), '.pdf')
Explanation:
- Form Runner stores information about a file into XML attributes:
@filename
accesses the file name as sent by the user's browser@mediatype
accesses the file type as sent by the user's browser@size
accesses the file size
$my-attachment/@filename
returns the file name associated with attachment "my-attachment"- The
lower-case()
function converts that name to a lower case value - The
ends-with()
function checks whether its first argument ends with the second argument
Similarly, you can test the file type:
$my-attachment/@mediatype = 'application/pdf'
NOTE: Because the file name and file type are sent by the client's browser, they cannot be trusted. This should only be considered a first level of data validation, and further validation based on the content must be performed at a later time if needed. See also issue #1838.
Scenario: We want to set the value of a field from a URL parameter, but only if that parameter exists. If it doesn't, we want to leave the value of the field as it is.
(xxf:get-request-parameter('my-parameter'), .)[1]
Explanation:
- If the parameter exists
xxf:get-request-parameter()
returns a single string- so you get a sequence containing that string following by the current value of the field
- we take the first value of the sequence, so the value of the parameter is used
- if the parameter doesn't exist
xxf:get-request-parameter()
returns an empty XPath sequence- so you get a sequence containing only the current value of the field
- we take the first value of that sequence, so we get the current value of the control
Scenario: For a given set of checkboxes, make sure the number of selected checkboxes is at most 3.
count(xxf:split(.)) le 3
Explanation:
xxf:split(.)
tokenizes the space-separated values selected by the checkbox- the number of tokens obtained with
count()
corresponds to the number of selected checkboxes - then this makes sure the number of tokens is lower than or equal to 3
You can use the following formula, in Control Settings, Validation and Alerts, Formula, to validate the relevant LEI field. Should you need to assess the validity of a LEI field that is somewhere else in the form, just replace
.
on the first line with the appropriate expression. An examples of valid LEI are:F50EOCWSQFAUVO9Q8Z97
(examples in ISO/DIS 17442)549300Y7W34DK0WBPY51
(Google)98450054NFCE7A67C172
(ManagedLEI)
let $lei := .
return
string-length($lei) = 20 and
xs:decimal(
string-join(
for $code in string-to-codepoints($lei)
return
if ($code >= string-to-codepoints('A') and string-to-codepoints('Z') >= $code) then
(: Letters A-Z :)
xs:string($code - string-to-codepoints('A') + 10)
else if ($code >= string-to-codepoints('0') and string-to-codepoints('9') >= $code) then
(: Digits 0-9 :)
xs:string($code - string-to-codepoints('0'))
(: Unrecognized characters :)
else
'',
''
)
) mod 97 = 1
You can use the following formula, in Control Settings, Validation and Alerts, Formula, to validate the relevant ISIN field. Should you need to assess the validity of a ISIN field that is somewhere else in the form, just replace
.
on the first line with the appropriate expression. Examples of valid ISIN are:US0378331005
(Apple, Inc.)AU0000XVGZA3
(Treasury Corporation of Victoria)GB0002634946
(BAE Systems)
let $isin := .
return
(
let
$without-checksum := substring($isin, 1, 11),
$letter-as-numbers-string :=
string-join(
for $code in string-to-codepoints($without-checksum)
return
if ($code >= string-to-codepoints('A') and string-to-codepoints('Z') >= $code) then
(: Letters A-Z :)
xs:string($code - string-to-codepoints('A') + 10)
else if ($code >= string-to-codepoints('0') and string-to-codepoints('9') >= $code) then
(: Digits 0-9 :)
xs:string($code - string-to-codepoints('0'))
(: Unrecognized characters :)
else
'',
''
),
$letter-as-numbers-digits :=
for $code in string-to-codepoints($letter-as-numbers-string)
return xs:decimal(codepoints-to-string($code)),
$reversed-digits := reverse($letter-as-numbers-digits),
$group-1-digits := $reversed-digits[position() mod 2 = 1],
$group-2-digits := $reversed-digits[position() mod 2 = 0],
$group-1-x2-decimals := for $d in $group-1-digits return $d * 2,
$group-1-x2-string := string-join(for $d in $group-1-x2-decimals return string($d), ''),
$group-1-x2-digits := for $code in string-to-codepoints($group-1-x2-string)
return xs:decimal(codepoints-to-string($code)),
$sum-digits := sum(($group-1-x2-digits, $group-2-digits)),
$checksum-computed := string((10 - ($sum-digits mod 10)) mod 10),
$checksum-provided := substring($isin, 12, 1),
$proper-checksum := $checksum-computed = $checksum-provided,
$proper-length := string-length($isin) = 12
return
$proper-checksum and $proper-length
)
- Input – In the following XPath expression, the start and end dates are inline, so you'll most likely want to modify it to refer to, say, dates entered by users in a form fields.
- Weekends – The expression takes Saturday and Sunday to be part of the weekend.
- First day of the week – The expression assumes Monday is the first day of the week. For instance check that on your system
format-date(xs:date('2018-12-10'), '[F1]')
returns 1. If not, you'll need to change the expressions for$startW
and$endW
.
for
$start in xs:date('2018-12-15'),
$end in xs:date('2018-12-26'),
$startW in xs:integer(format-date($start, '[F1]')),
$endW in xs:integer(format-date($end, '[F1]')),
$days in days-from-duration($end - $start),
$daysNoWeekends in $days - (floor($days div 7) * 2)
return
if ($days mod 7 != 0 and ($startW = 7 or $endW = 7)) then $daysNoWeekends - 1
else if ($endW < $startW) then $daysNoWeekends - 2
else $daysNoWeekends
The following formula formats the current date/time to an ISO date/time in a specific named timezone:
format-dateTime(
current-dateTime(),
'[Y0001]-[M01]-[D01]T[H01]:[m01]:[s01]',
'en',
(),
'Europe/Paris'
)
Last modified 1mo ago