Orbeon Forms
  • Getting started
  • Installation
    • Logging
    • Configuration banner
    • Docker
    • Azure
    • Tomcat
    • WildFly
    • WebSphere
    • WebLogic
    • GlassFish
    • Caches
    • Replication
    • Upgrading
  • Configuration
    • Properties
      • General
        • HTTP client
      • Form Runner
        • Detail page
          • Attachments
          • Email properties
          • PDF
          • Table of contents
        • Persistence
        • Summary page
      • Form Builder
      • XForms
    • Advanced
      • Workflows
      • Session management
      • State handling
      • Client-side error handling
      • Clustering and High Availability
      • Configuring a Form Runner eXist database
      • Creating a production WAR
      • Environments
      • JavaScript and CSS assets
      • Limiter filter
      • Run modes
      • Security
        • Content-Security-Policy header
      • SAP Hybris Module
      • XForms logging
    • Troubleshooting
      • Troubleshooting with the orbeon.log
      • Memory and threads
      • Relational database logging
      • Misc
  • Form Builder
    • Form settings
      • Time window
    • Form editor
      • Form area
      • Toolbox
      • Buttons bar
      • Control settings
      • Dependent fields and sections
      • Validation
      • Choices editor
      • Publishing
      • Cut, copy and paste
      • Section and grid settings
      • Section settings
      • Grid settings
      • Quick control search
      • Repeat settings
      • Repeated grids
      • Undo and redo
      • Keyboard shortcuts
    • Formulas
      • Examples of formulas
      • Formulas inspector
      • Formulas console
    • Summary page
    • Form localization
    • Advanced
      • Edit source
      • Services and actions
        • HTTP services
        • Database services
        • Simple Actions
        • Action Syntax
        • Action Syntax examples
        • Synchronizing repeated content
      • Testing a form in web mode
      • Testing PDF production
      • Testing offline functionality
      • Email Settings dialog
      • Field-level encryption
      • Messages
      • Section templates
      • Template syntax
      • XML Schemas support
      • Extensibility
        • Extension API
        • Integration
        • Toolbox component metadata
  • Form Runner
    • Overview
      • Terminology
    • Pages
      • Landing page
      • Published Forms page
      • Forms Admin page
      • Summary page
    • Components
      • Alert dialog
      • Attachment
      • Autocomplete
      • Captcha
      • Character counter
      • Checkbox input
      • Currency
      • Date
      • Dropdown date
      • Static and dynamic dropdown
      • Error summary
      • Grid
      • Handwritten signature
      • Hidden field
      • Image
      • Image annotation
      • Image attachment
      • Number
      • Open selection
      • Repeater
      • Formatted Text / Rich Text Editor
      • Section
      • Single-selection tree
      • Source code editor
      • Time
      • US phone
      • US state
      • Video
      • Video attachment
      • Wizard
      • XForms inspector
      • Yes/No answer
    • Features
      • Automatic calculations dependencies
      • Datasets
      • Excel and XML import
      • Excel and XML export
      • Summary page Excel Export
      • Form definitions and form data Zip Export
      • Purging historical data
      • Lease
      • Localization
      • Supported languages
      • Mobile support
      • Multitenancy
      • Form Runner navigation bar
      • PDF production
        • Automatic PDF
        • Automatic PDF header and footer configuration
        • PDF templates
      • Responsive design
      • Revision history
      • S3 storage
      • Simple data migration
      • TIFF production
      • Versioning
      • Wizard view
      • Workflow stage
    • Persistence
      • Using a relational database
      • Relational database schema
      • Purging old data using SQL
      • Auditing
      • Autosave
      • Database support
      • Flat view
    • Linking and embedding
      • Linking
      • Java Embedding API
      • JavaScript Embedding API
      • Liferay full portlet
      • Liferay proxy portlet
      • Securing Form Runner access
      • Form Runner offline embedding API
      • Angular component
      • React component
    • Access control and permissions
      • Users
      • Login & Logout
      • Deployed forms
      • Form fields
      • Editing forms
      • Owner and group member
      • Organizations
      • Scenarios
      • Token-based permissions
    • Styling
      • CSS
      • Grids CSS
      • Automatic PDF styling and CSS
    • APIs
      • Authentication of server-side service APIs
      • Persistence API
        • CRUD API
        • Search API
        • List form data attachments API
        • Form Metadata API
        • Lease API
        • Reindexing API
        • Caching
        • Versioning
        • Revision History API
        • Zip Export API
        • Custom persistence providers
      • Other APIs
        • Connection context API
        • Duplicate form data API
        • File scan API
        • Form Runner JavaScript API
        • Generate XML Schema API
        • PDF API
        • Publish form definition API
        • Run form in the background API
      • Data formats
        • Form data
        • Date and time
        • Form definition
    • Architecture and integration
      • Architecture
      • Access form data
      • Integration
    • Advanced
      • Buttons and processes
        • Simple process syntax
        • Core actions
        • Form Runner actions
          • Save action
          • Send action
          • Email action
        • XForms actions
        • Predefined buttons, processes and dialogs
        • Summary page buttons and processes
      • Custom dialogs/model logic
      • Services
      • Singleton form
      • Monitoring HTTP requests
  • XForms
    • Core
      • Attribute Value Templates (AVTs)
      • Binds
      • Validation
      • Variables
      • Keyboard focus
      • XForms JavaScript API
      • Error handling
        • Detailed behavior
      • Model-Bind variables
      • XForms 2.0 support
    • Events
      • Standard support
      • UI refresh events
      • Keyboard events
      • Extension events
      • Extension context information
      • Other event extensions
    • Actions
      • Repeat, insert and delete
      • Scripting actions
      • Extensions
    • Controls
      • Label, hint, help
      • Input
      • Output
      • Text area
      • Button
      • Upload
      • Dialog
    • Submission
      • Standard support
      • JSON support
      • Asynchronous submissions
      • Caching extension
      • Other submission extensions
    • XPath
      • Type annotations
      • Expression analysis
      • Tips
      • Compatibility
      • Standard functions
      • Maps and arrays Functions
      • Extension functions
        • Core functions
        • Utility functions
        • Model functions
        • Controls functions
        • XML functions
        • JSON functions
        • HTTP functions
        • Form Runner functions
        • Other functions
        • Deprecated functions
    • XBL components
      • FAQ
      • Guide
        • XBL Tutorial
        • Bindings
        • XForms models
        • Including content
        • Event handling
        • Conventions
        • Map XBL example
        • Learning from existing components
      • Advanced topics
        • XBL Modes
        • JavaScript companion classes
        • XBL library
        • Extensions
        • Attachment controls
    • XForms tutorial
      • Introduction
      • Installation
      • The Hello application
      • The Bookcast application
        • The basic app
        • Database access
        • Polishing the app
        • Adding a feed
    • Using XForms from Java apps
  • XML Platform
    • Page Flow Controller
      • Basics
      • XML submission
      • Navigating between pages
      • Paths and matchers
      • Other configuration elements
      • Typical combinations of page model and page view
      • Examples
      • Authorizing pages and services
    • Processors
      • URL generator
      • Request generator
      • PDF to image converter
    • Resources
      • Resource managers
      • Setting up an external resources directory
    • Other
      • Binary and text documents
  • FAQ
    • Licensing
    • PE and Dev Support
    • Form Builder and Form Runner
    • Resources and support
    • Other technical questions
  • Contributors
    • Automated tests
    • Building Orbeon Forms
    • Localizing Orbeon Forms
    • Validation functions
    • Contributor License Agreement
  • Release notes
    • Orbeon Forms 2022.1.9
    • Orbeon Forms 2024.1.1
    • Orbeon Forms 2023.1.7
    • Orbeon Forms 2024.1
    • Orbeon Forms 2023.1.6
    • Orbeon Forms 2023.1.5
    • Orbeon Forms 2021.1.11
    • Orbeon Forms 2022.1.8
    • Orbeon Forms 2023.1.4
    • Orbeon Forms 2023.1.3
    • Orbeon Forms 2023.1.2
    • Orbeon Forms 2022.1.7
    • Orbeon Forms 2023.1.1
    • Orbeon Forms 2023.1
    • Orbeon Forms 2022.1.6
    • Orbeon Forms 2021.1.10
    • Orbeon Forms 2022.1.5
    • Orbeon Forms 2021.1.9
    • Orbeon Forms 2022.1.4
    • Orbeon Forms 2022.1.3
    • Orbeon Forms 2021.1.8
    • Orbeon Forms 2022.1.2
    • Orbeon Forms 2022.1.1
    • Orbeon Forms 2022.1
    • Orbeon Forms 2021.1.7
    • Orbeon Forms 2021.1.6
    • Orbeon Forms 2021.1.5
    • Orbeon Forms 2021.1.4
    • Orbeon Forms 2021.1.3
    • Orbeon Forms 2021.1.2
    • Orbeon Forms 2021.1.1
    • Orbeon Forms 2021.1
    • Orbeon Forms 2020.1.6
    • Orbeon Forms 2019.2.4
    • Orbeon Forms 2019.1.2
    • Orbeon Forms 2018.2.5
    • Orbeon Forms 2018.1.4
    • Orbeon Forms 2020.1.5
    • Orbeon Forms 2020.1.4
    • Orbeon Forms 2020.1.3
    • Orbeon Forms 2020.1.2
    • Orbeon Forms 2019.2.3
    • Orbeon Forms 2020.1.1
    • Orbeon Forms 2020.1
    • Orbeon Forms 2019.2.2
    • Orbeon Forms 2019.2.1
    • Orbeon Forms 2019.1.1
    • Orbeon Forms 2019.2
    • Orbeon Forms 2019.1
    • Orbeon Forms 2018.2.4
  • Release history
  • Use cases
  • Product roadmap
  • Index of features
Powered by GitBook
On this page
  • Live examples
  • Sum of values in a repeat
  • Constrain a number between two values
  • Constrain the length of a string between two values
  • Validating with a regular expression for an optional value
  • Make a control read-only based on the value of another control
  • Setting a dynamic initial value
  • Simple calculated values
  • Access a control in a particular repeat iteration
  • Check the role(s) of the current user
  • Check the Form Runner mode
  • Modes
  • With Orbeon Forms 2016.2 and newer
  • With Orbeon Forms 2016.1.x and earlier
  • Access HTTP request parameters and HTTP headers
  • Check the type of an attachment
  • Set the value of a field from a URL parameter
  • Converting a date/time to a named timezone
  • See also
  1. Form Builder
  2. Formulas

Examples of formulas

PreviousFormulasNextFormulas inspector

Last updated 3 months ago

Live examples

For live examples of , see .

Sum of values in a repeat

[SINCE Orbeon Forms 4.5]

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 closest price and quantity 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, all row-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:

Constrain a number between two values

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

  • >= or ge means "greater than or equals to"

  • <= or le 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

Constrain the length of a string between two values

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

  • >= or ge means "greater than or equals to"

  • <= or le 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)

Validating with a regular expression for an optional value

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

Make a control read-only based on the value of another control

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 returns true() if the value passed is blank

Setting a dynamic initial value

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.

Simple calculated values

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

Access a control in a particular repeat iteration

  • $name[2]: return the value of the control in the second iteration

  • string-join($name, ', '): join all values with commas

  • count($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.

Check the role(s) of the current user

Check the Form Runner mode

Modes

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)

With Orbeon Forms 2016.2 and newer

fr:mode() = 'edit'

With Orbeon Forms 2016.1.x and earlier

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'

Access HTTP request parameters and HTTP headers

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.

Check the type of an attachment

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'

Set the value of a field from a URL parameter

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

Converting a date/time to a named timezone

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

See also

  • Blog posts

see this for the use of string() within the predicate

.

Given and a control called name within a repeat:

See also and this .

See .

You can use the exposed by Form Runner to all XPath expressions.

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 .

NOTE: See for availability of a fix that impacts this example.

blog post
Formulas for summing values, done right
Unexpected result with variable inside an <xf:bind> iteration #152
this form
Model bind variables
StackOverflow question
Form Fields
#1838
issue #4981
Formulas
Form Builder Validation
Formulas inspector
Better formulas with XPath type annotations
Formulas for summing values, done right
Control required values with formulas in Orbeon Forms 4.7
Improvements to variables in formulas
XForms Validation
Formulas
Orbeon Demo: Examples of Formulas
When the internal data format matters
Resolution of repeated controls
Orbeon Demo: Examples of Formulas
fr:mode() XPath function