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
  • Rationale
  • Namespace
  • Group metadata for the toolbox
  • Control metadata for the toolbox
  • Introduction
  • Icons
  • Control metadata for the markup to insert in the form
  • Control metadata for the Control Settings dialog
  • Introduction
  • With Orbeon Forms 2016.1 and newer
  • With Orbeon Forms 4.10 and earlier
  • Internationalization of labels and other elements
  • See also
  1. Form Builder
  2. Advanced
  3. Extensibility

Toolbox component metadata

PreviousIntegrationNextForm Runner

Last updated 5 years ago

Rationale

XBL components can be loaded by the Form Builder toolbox. In order for Form Builder to have information about those components, metadata can be added to each XBL binding.

Namespace

The Form Builder specific extensions are in an namespace::

  • URI: http://orbeon.org/oxf/xml/form-builder

  • Usual prefix: fb

  • Example: xmlns:fb="xmlns="http://orbeon.org/oxf/xml/form-builder"

Group metadata for the toolbox

<fb:metadata>
    <fb:display-name lang="en">Text Controls</fb:display-name>
    <fb:display-name lang="fr">Contrôles texte</fb:display-name>
</metadata>

Control metadata for the toolbox

Introduction

<fb:metadata>
    <fb:display-name lang="en">Explanatory Text</fb:display-name>
    <fb:display-name lang="es">Explicación</fb:display-name>
    <fb:display-name lang="fi" todo="true">[Explanation]</fb:display-name>
    <fb:display-name lang="fr">Text explicatif</fb:display-name>
    <fb:display-name lang="ru" todo="true">[Explanation]</fb:display-name>
    <fb:display-name lang="de">Erklärung</fb:display-name>
    <fb:display-name lang="it">Spiegazione</fb:display-name>
    <fb:display-name lang="nl">Uitleg</fb:display-name>
    <fb:display-name lang="sv">Förklaring</fb:display-name>
    <fb:icon>
        <fb:icon-class>fa fa-fw fa-comment</fb:icon-class>
    </fb:icon>
    <fb:templates>
        <fb:resources>
            <text/>
        </fb:resources>
        <fb:view>
            <fr:explanation>
                <fr:text ref=""/>
            </fr:explanation>
        </fb:view>
    </fb:templates>
</fb:metadata>

Prior to Orbeon Forms 2018.1, you would use <fb:small-icon> to point to an image file:

<fb:icon>
    <fb:small-icon>/apps/fr/style/images/silk/layout.png</fb:small-icon>
</fb:icon>

NOTE: <fb:large-icon> was present in a number of XBL components but never used by Form Builder. We recommend, starting with Orbeon Forms 2018.1, using <fb:icon-class> which allows for scalable icons.

Icons

[SINCE Orbeon Forms 2018.1]

<fb:metadata>
    <fb:display-name lang="en">Explanatory Text</fb:display-name>
    <fb:display-name lang="fr">Text explicatif</fb:display-name>
    ...
    <fb:icon>
        <fb:icon-class>fa fa-fw fa-comment</fb:icon-class>
    </fb:icon>
    ...
</fb:metadata>

Control metadata for the markup to insert in the form

When form authors add an instance of your component from Form Builder, Form Builder needs to… well, add the component to the form. For this, inside the <fb:templates> for your component you declare:

  • Inside <fb:view>, the markup that goes in the view, e.g. <xf:input> for a plain XForms input.

  • Optionally, on <fb:bind>, attributes you might want to add to the <xf:bind> Form Builder adds for your component.

<fb:templates>
    <fb:view>
        <my:component>
            <xf:label ref=""/>
            <xf:hint ref=""/>
            <xf:help ref=""/>
            <xf:alert ref=""/>
        </my:component>
    </fb:view>
    <fb:bind type="xf:decimal"/>
    <fb:resources>
        <text/>
    </fb:resources>
</fb:templates>

If your component only needs a template for the view, which is maybe the most frequent use case, instead of nesting an <fb:view> inside an <fb:templates>, you can just use an <fb:template> element, as in:

<fb:template>
    <my:component>
        <xf:label ref=""/>
        <xf:hint ref=""/>
        <xf:help ref=""/>
        <xf:alert ref=""/>
    </my:component>
</fb:template>

Control metadata for the Control Settings dialog

Introduction

  • the HTTP URI of a service returning an XML document with the items shown in the drop-down,

  • an XPath expression extracting the items from the XML document,

  • and two XPath expressions returning the label and value for each item.

You can create a custom user interface within Form Builder for XBL component that require such additional properties by adding XForms controls under the the <fb:control-details> element, which you add under <fb:metadata>.

With Orbeon Forms 2016.1 and newer

<fb:control-details> can contain any XForms control. This allows for more flexible layouts:

In addition, you can place an <xf:model>, which can be used for:

  • additional local instances

  • validation

  • event handlers

The content of <xf:model> is available to the control specified.

Example:

<fb:control-details>
    <xf:model>
        <xf:bind ref="@resource"/>
        <xf:bind ref="xf:itemset">
            <xf:bind
                ref="@ref | xf:label/@ref | xf:value/@ref"
                type="xxf:xpath2"
                required="true()"/>
        </xf:bind>
    </xf:model>
    <fr:grid>
        <xh:tr>
            <xh:td colspan="2">
                <xf:input ref="@resource">
                    <xf:label lang="en">Resource URL</xf:label>
                    <xf:label lang="fr">URL de la ressource</xf:label>
                    <xf:hint  lang="en">HTTP URL returning data used to populate the dropdown</xf:hint>
                    <xf:hint  lang="fr">URL HTTP auquel réside le service</xf:hint>
                </xf:input>
            </xh:td>
        </xh:tr>
        <xh:tr>
            <xh:td colspan="2">
                <xf:input ref="xf:itemset/@ref">
                    <xf:label ref="$resources/dialog-actions/items/label"/>
                    <xf:hint ref="$resources/dialog-actions/items/hint"/>
                </xf:input>
            </xh:td>
        </xh:tr>
        <xh:tr>
            <xh:td>
                <xf:input ref="xf:itemset/xf:label/@ref">
                    <xf:label ref="$resources/dialog-actions/item-label/label"/>
                    <xf:hint ref="$resources/dialog-actions/item-label/hint"/>
                </xf:input>
            </xh:td>
            <xh:td>
                <xf:input ref="xf:itemset/xf:value/@ref">
                    <xf:label ref="$resources/dialog-actions/item-value/label"/>
                    <xf:hint ref="$resources/dialog-actions/item-value/hint"/>
                </xf:input>
            </xh:td>
        </xh:tr>
    </fr:grid>
</fb:control-details>

Implicitly, there is always a default instance accessible with instance(), which contains the control being edited.

With Orbeon Forms 4.10 and earlier

The <fb:control-details> only supports <xf:input> controls. These are bound to attributes or elements inside the template you provided inside <fb:template>.

Example:

<fb:control-details>
    <xf:input ref="@resource">
        <xf:label lang="en">Resource URL</xf:label>
        <xf:label lang="fr">URL de la ressource</xf:label>
        <xf:hint  lang="en">HTTP URL returning data used to populate the dropdown</xf:hint>
        <xf:hint  lang="fr">URL HTTP auquel réside le service</xf:hint>
    </xf:input>
    <xf:input ref="xf:itemset/@ref">
        <xf:label ref="$resources/dialog-actions/items/label"/>
        <xf:hint ref="$resources/dialog-actions/items/hint"/>
    </xf:input>
    <xf:input ref="xf:itemset/xf:label/@ref">
        <xf:label ref="$resources/dialog-actions/item-label/label"/>
        <xf:hint ref="$resources/dialog-actions/item-label/hint"/>
    </xf:input>
    <xf:input ref="xf:itemset/xf:value/@ref">
        <xf:label ref="$resources/dialog-actions/item-value/label"/>
        <xf:hint ref="$resources/dialog-actions/item-value/hint"/>
    </xf:input>
</fb:control-details>

Internationalization of labels and other elements

The text for control <xf:label>, <xf:hint>, <xf:help>, and <xf:alert>, can either be:

  • Inline, with a lang attribute indicating the language. This is what the author of the Dynamic Data Dropdown control did for the first <xf:input> above.

See also

In XBL, each component is defined in an <xbl:binding> element and multiple <xbl:binding> can be grouped under an <xbl:xbl> element. The Form Builder toolbox shows components, grouped by "types of components", e.g. "Text Controls", as shown at the right of this text. To instruct Form Builder that multiple component should be grouped together in the toolbar, place then inside the same <xbl:xbl>. Then, as a child element of <xbl:xbl>, you provide the title for the group inside an <fb:metadata>, as in (see the as of Orbeon Forms 2018.1):

To be used in Form Builder, your XBL component must have an additional <fb:metadata> section inside the <xbl:binding> of your component. That <fb:metadata> provides to Form Builder the localized display name for the component, an icon, and the markup to be inserted by Form Builder into the form when the component is used. For instance, the <metadata> section for the Explanatory Text component look like (see the as of Orbeon Forms 2018.1):

The new <fb:icon-class> element allows you to specify a set of CSS classes used in the toolbox to show a scalable font icon. This is useful with icons from and similar. In that case, don't use <fb:small-icon>. For example:

Optionally, and this is rare, inside <fb:resources>, additional resource elements the component might use, in addition to the label, help, hint, and alert. E.g. this is used in .

All the controls share certain properties, like the control name. However, some XBL components take additional properties, set at design time in Form Builder. For instance the takes:

See also .

Taken from the , which is typically useful when your control uses resources that already exists elsewhere in Form Builder. In this case, you don't need to worry about what the current language is: Form Builder will automatically select the subset of the resource file that applies for the current language. This is what the author of the Dynamic Data Dropdown control did for the second <xf:input> above.

full source
full source
Font Awesome
explanation.xbl
Dynamic Data Dropdown
Form Builder resource file
Custom Control Settings
Form Builder toolbox properties
Custom control settings
Custom control settings