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
          • 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
      • 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
  • Introduction
  • Basic Settings
  • Validations and alerts
  • Formulas
  • Explanatory Text
  • Label and Hint
  • Help Message
  • Dynamic labels, hints and help messages
  • Language selector
  • Keyboard shortcuts
  • See also
  1. Form Builder
  2. Form editor

Control settings

PreviousButtons barNextDependent fields and sections

Last updated 29 days ago

Introduction

The Control Settings dialog allows controlling all the aspects the a control besides its label and hint. The dialog has several tabs, detailed below.

Basic Settings

Basic options

  • to refer to the control value from formulas, using the variable notation $foo where foo is the control name

  • to determine an XML element name when the form data is represented as XML

If a control name is not explicitly specified, Form Builder assigns a default name, such as control-42.

A control name can be changed, provided it doesn't collide with another control name (an error will show otherwise).

[SINCE Orbeon Forms 2019.1]

Main options

The following options are available:

  • Show on Summary page:

    • When selected, the control value is visible as a Summary page column and searchable.

  • Allow bulk edit:

    • When selected, the control value can be bulk edited from the Summary page.

  • Index control:

    • SINCE Orbeon Forms 2021.1

  • Encrypt data at rest:

    • SINCE Orbeon Forms 2018.1

    • This is an Orbeon Forms PE feature.

Role restriction

It is possible to restrict the "Show on Summary page" and "Allow bulk edit" options to one or more specific roles (i.e. group of users). When multiple roles are specified, the logic that applies can be chosen as well. If "All" is selected, then all specified roles must be present. If "Any" is selected, just one of the specified roles must be present.

Bulk action

By default, bulk edition of form data on the Summary Page will simply save the updated form data. You can also specify a custom process to run by selecting "Run process" instead of "Save data".

The selected process is responsible for saving the data.

It's possible to specify a list of processes available for selection in the Control Settings dialog. This is done by specifying the following property:

<property
    as="xs:string"
    name="oxf.fr.summary.bulk-processes.*.*"
    value="process1 process2"/>

The value is a space-separated list of process names. By default, this property is empty.

Email options

The following email options are available:

NOTE: SINCE Orbeon Forms 2018.2, these options are in a separate list.

  • Email recipient:

    • When selected, the control is used to determine an email recipient ("To:") when the form data is sent by email.

    • If more than one non-blank email addresses is found, they are all included as email recipients. In addition, the oxf.fr.email.to property is used.

    • A single control value can contain more than one email address, separated by commas (,) or spaces.

  • Email carbon copy recipient:

    • SINCE Orbeon Forms 2017.1

    • When selected, the control is used to determine a carbon copy email recipient ("Cc:") when the form data is sent by email.

    • If more than one non-blank email addresses is found, they are all included as email recipients. In addition, the oxf.fr.email.cc property is used.

    • A single control value can contain more than one email address, separated by commas (,) or spaces.

  • Email blind carbon copy recipient:

    • SINCE Orbeon Forms 2017.1

    • When selected, the control is used to determine a blind carbon copy email recipient ("Bcc:") when the form data is sent by email.

    • If more than one non-blank email addresses is found, they are all included as email recipients. In addition, the oxf.fr.email.bcc property is used.

    • A single control value can contain more than one email address, separated by commas (,) or spaces.

  • Email sender:

    • SINCE Orbeon Forms 2017.1

    • When selected, the control is used to determine an email sender ("From:") when the form data is sent by email.

    • Only one "From:" email address is used, specifically the first non-blank address selected in the form. If no such address is found the oxf.fr.email.from property is used.

  • Email reply-to:

    • SINCE Orbeon Forms 2020.1

    • When selected, the control is used to determine a reply-to address ("Reply-To:") when the form data is sent by email.

    • Only one "Reply-To:" email address is used, specifically the first non-blank address selected in the form. If no such address is found the oxf.fr.email.reply-to property is used.

  • Exclude from email body:

    • SINCE Orbeon Forms 2018.1

  • Include as email attachment:

    • SINCE Orbeon Forms 2016.1

    • this option only shows for file and image attachments

    • when the property oxf.fr.email.attach-files is set to selected, only file and image attachments with this option checked are attached to the email

  • Show in email subject:

    • When selected, the control value is used as part of the subject of the email when the form data is sent by email.

    • If more than one non-blank values are found, they are all included in the email subject, comma-separated.

[SINCE Orbeon Forms 2021.1.4]

Email addresses can now contain a name, following the standard syntax:

John Smith <john@example.org>

Or:

"John Smith" <john@example.org>

When more than one email is present, if you specify names, you must use commas exclusively as a separator (with whitespace allowed around commas):

John Smith <john@example.org>, Alice <alice@acme.org>

Or:

"John Smith" <john@example.org>, "Alice" <alice@acme.org>

Name of the PDF field

[SINCE Orbeon Forms 2018.2]

This informational field shows the name of the field to use when using a PDF template.

Custom CSS classes

For example, you might specify:

my-name-field my-highlight

In this example, the my- prefix is used as a best practice to prevent conflicts with other CSS classes on the page. In your custom CSS file, you can target these classes using a selector, such as:

.orbeon .my-name-field.my-highlight input {
  border-color: blue;
}

Autocomplete attribute

Control appearance

[SINCE Orbeon Forms 4.10]

Some controls support more than one appearance. For example, a single selection control can appear as a dropdown menu, or as radio buttons. When available, the "Control Appearance" selector allows selecting and changing the appearance of the control.

Custom control settings

Some controls have custom settings. For example:

The following controls have custom settings:

  • Date

  • Time

  • Date and Time

  • Dropdown

  • Dropdown with Search

Automatic PDF options

[SINCE Orbeon Forms 2021.1]

When producing a PDF file, single-selection controls like the "Static Dropdown" normally just output the selected value. However, in some cases, it is useful for the user to see all the available options.

You can achieve this with the "Automatic PDF" options in the "Control Settings" dialog for single-selection controls. This option is hierarchical: you can set it at the field level, form level, or globally. They are:

  • Use default: use the form settings, and if they also have "Use default" use the property (see below)

  • Show the selected value only: the label for the selected value shows

  • Show all values as radio buttons: all possible values show as radio buttons and the selected value, if any, shows selected

The supported properties are:

  • oxf.xforms.xbl.fr.dropdown-select1.pdf-appearance.*.*

  • oxf.xforms.xbl.fr.dropdown-select1-search.pdf-appearance.*.*

The possible values for each property are:

  • empty: show the selected value only (default)

  • full: show all values as radio buttons

Example to change the default the "Static Dropdown" control to showing all values in the automatic PDF:

<property 
    as="xs:string" 
    name="oxf.xforms.xbl.fr.dropdown-select1.pdf-appearance.*.*"
    value="full"/>

The global default is "Show the selected value only".

Validations and alerts

Formulas

[SINCE Orbeon Forms 2018.2]

The "Yes" and "No" options have their own radio button. Select "Formula" to enter a dynamic "Visibility" or "Read-Only" formula.

Explanatory Text

[SINCE Orbeon Forms 2019.1]

For the Explanatory Text control only, you can modify the text in this location, including making the text dynamic using templates as is the case for the Label, Hint and Help Message.

Label and Hint

[SINCE Orbeon Forms 2017.2]

In addition to setting a control's label and hint in place in the form area, you can also set and update them in this tab. You can switch between plain text and HTML text as well. The "Previous" and "Next" buttons allow quick navigation between controls.

Automatic hints

For attachment controls, in addition to the hint you provide for the control, Orbeon Forms can add an automatic hint informing the user about the maximum allowed file size and the accepted file types, if you have specified such validations in the Validations and Alerts tab.

Automatic hints are disabled by default, and you can enable them for a specific control in the Control Settings dialog, for all controls in a form in the Form Settings dialog, or globally using the property below. A setting other than "Default" in the Control Settings dialog box overrides a setting other than "Use property" in the Form Settings dialog box, which overrides the value of the property below.

<property 
    as="xs:boolean"
    name="oxf.fr.detail.hint.automatic.*.*"                           
    value="true"/>

Help Message

This allows specifying some help text, which can be plain text or rich text when the "Use HTML" checkbox is selected.

The help message is available at runtime through a help icon positioned next to the control. By default, the icon opens a pop-up containing the help text. In noscript mode (removed since Orbeon Forms 2018.1), the icon links to a help section at the bottom of the form.

The help text is localizable.

Dynamic labels, hints and help messages

[SINCE Orbeon Forms 2018.1]

Controls support dynamic labels, hints, and help messages. This means that, instead of being specified once and for all at form design time, labels, hints and help messages can incorporate dynamic parts such as control values and other custom expressions.

Language selector

When multiple languages are available for the form, a language selector allows selecting the language for which localizable texts are being edited (e.g. Validations and Alerts, Label, Hint, and Help Message) directly from the Control Settings dialog.

Keyboard shortcuts

See also

  • Blog posts

The control name specifies a identifier for the control, unique in the entire form (except ). The identifier is used for the following:

See .

Index the value of this control even if it's not shown or searchable from the Summary page, or bulk editable. This makes the control accessible from the .

See for details.

When using "All Control Values" in an , controls selected with this checkbox will beexcluded and omitted from the email body.

DEPRECATED SINCE Orbeon Forms 2018.1: Use a instead.

See also .

The "Custom CSS Classes" field allows you to add CSS classes that will be applied to the control in the resulting HTML. This is useful for applying custom styling. Note that CSS classes themselves do not directly define styles; instead, they serve as space-separated tokens that you can reference in .

The "Autocomplete attribute" dropdown allows specifying an for controls for which it makes sense to do so. Such a value tells the browser that it can suggest values for the field or, in the case of the off value, that it shouldn't suggest any value.

See also .

[SINCE Orbeon Forms 2022.1]

See also

See for details.

See for details.

See also .

For more, see .

See .

Section Templates
search API
Field-level encryption
[SINCE Orbeon Forms 2023.1]
[SINCE Orbeon Forms 2024.1]
email body template
template for the subject
PDF templates
your own CSS files
[SINCE Orbeon Forms 2023.1]
HTML autocomplete value
How the new Form Builder Appearance Selector Works
Form Builder Validation
Formulas
[SINCE Orbeon Forms 2023.1]
Improving how we show help messages
Template syntax
[SINCE Orbeon Forms 2023.1]
Keyboard shortcuts
Form Builder Validation
Formulas
Template syntax
Enhanced validation in Form Builder and Form Runner
Improving how we show help messages
How the new Form Builder Appearance Selector Works
Improved constraints on attachments uploads
More flexible email senders and recipients
Renaming of controls and formulas
Dropdown Date
Basic Settings tab
Role restriction
Bulk process
Custom Control Settings
Automatic PDF options
Validations and alerts tab
Formulas tab
Explanatory Text tab
Label tab
Help tab
Language selector
Role restriction
Bulk process
Number
File Attachment
Image Attachment
Currency
Automatic PDF options
US Phone Number
Control metadata for the Control Settings dialog
Control metadata for the Control Settings dialog