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
  • Running the Hello application
  • The source code
  • Page Flow
  • Orbeon Forms resources
  • A look into the resources directory structure
  • Playing with the hello application source code
  1. XForms
  2. XForms tutorial

The Hello application

PreviousInstallationNextThe Bookcast application

Last updated 1 year ago

Running the Hello application

The Hello application is about the simplest Orbeon Forms application you can think of. It asks for your name and displays it back. Here is a direct link for running XForms Hello .

Simply enter your first name in the input field, for example "Joe". You should promptly see a message underneath saying "Hello, Joe!".

  • view.xhtml: this is the XHTML and XForms code for the Hello application.

  • page-flow.xml: this is the page flow for the Hello application. The main task of a page flow is mapping external URLs (as typed in a web browser) to Orbeon Forms pages.

The source code

You are now ready to look at the source code of the Hello application. This will give you an idea of what an Orbeon Forms application looks like. First, select view.xhtml to make the source code for that file appear on the right:

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:xf="http://www.w3.org/2002/xforms">
    <head>
        <title>XForms Hello</title>
        <xf:model>
            <xf:instance>
                <first-name xmlns=""/>
            </xf:instance>
        </xf:model>
    </head>
    <body>
        <p>
            <xf:input ref="/first-name" incremental="true">
                <xf:label>Please enter your first name:</xf:label>
            </xf:input>
        </p>
        <p>
            <xf:output
              value="if (normalize-space(/first-name) = '') then ''
                     else concat('Hello, ', /first-name, '!')"/>
        </p>
    </body>
</html>

The first thing you notice is that this looks very much like HTML (notice the <html> tag). But in fact, this is XHTML, the XML-compatible version of HTML. There are only a few differences that matter between HTML and XHTML, in particular you must close all your tags and use quotes around attributes. Also, you must place your tags in a namespace, which is why the <html> tag features the xmlns="http://www.w3.org/1999/xhtml" namespace declaration.

Using XForms in Orbeon Forms means that you don't have to use HTML forms at all. The benefit is that XForms is much more powerful than HTML forms, as you will see in this tutorial.

You notice a tag called <xf:model>. Because XForms follows a Model-View-Controller (MVC) approach, most XForms pages contain one or more models that usually encapsulate other XForms markup. You place these models under the XHTML <head> tag.

Note that from now on, we prefer the term element to the term tag. An element is an XML term that includes the start tag and end tag, and can have content such as other elements and text.

With XForms, you store the data captured by controls such as input fields, combo boxes, etc. as text contained within XML elements or attributes. Consider the following XML document containing a single element called first-name.

<first-name/>

The first-name element is empty. Contrast with:

<first-name>Joe</first-name>

The element now contains the string "Joe". Notice how in view.xhtml the XML document is encapsulated within an <xf:instance> element:

<html>
    <xf:instance>
        <first-name xmlns=""/>
    </xf:instance>
</html>

Also notice the special xmlns="" namespace attribute on <first-name>: this is necessary because the root element of the XHTML document defines a default namespace with xmlns="http://www.w3.org/1999/xhtml". Because we want to make it clear that the element <first-name> is not an XHTML element, but an element in no namespace, we add xmlns="" to that element. If your instance document must be in no particular namespace, you are always safe to add xmlns="" on the root element of that instance.

This element defines an XForms instance, which is just XForms' way of calling an XML document used to store data.

Now consider the remaining XForms elements in the source file: <xf:input> and <xf:output>. These two elements are not located under the XHTML <head>, but under <body>. They are part of the view of your page, in other words these elements directly help define visible controls on the page. Consider <xf:input>:

<xf:input ref="/first-name" incremental="true">

You guessed that this element allows the user to input information. <xf:input> is usually displayed to the user as an input field. The ref attribute is the magic that connects the input field to the XForms instance. It contains an XPath expression, which in this case just looks like a file path. In this case, /first-name points to the element called first-name, which happens to be the only element we have in the XForms instance. Using the ref attribute this way is called a binding and means two things:

  • When the user enters text in the input field, the text is saved into the element called first-name.

  • It also goes the other way: if somehow the text content of first-name in the XForms instance changes, this is automatically reflected in the input field.

Now consider <xf:output>. As you guess from the name of the element, this simply displays a value on screen. If you have tried running the Hello application, you have probably guessed the logic that is being implemented: if the first name entered by the user is not a blank string, then we display the "Hello" message followed by the first name and then an exclamation mark. Otherwise if the first name consists only of spaces, we just display a blank string. The idea is to avoid displaying things like "Hello !" without an actual first name.

With many client-side libraries, you express this type of logic with JavaScript. With XForms, you use XPath instead. This means that you need to learn at least a few bits of the XPath syntax. While XPath may be different from what you already know (it is based on expressions and definitely targeted at XML), it is in fact a smaller language than JavaScript.

So how do you hook-up the logic within <xf:output>? Here, instead of a ref attribute, we use a value attribute. Like ref, value takes an XPath expression, but it doesn't actually create a binding to instance data: it just returns a string. The XPath is as follows:

if (normalize-space(/first-name) = '') then
    ''
else
    concat('Hello, ', /first-name, '!')

A few things to point out:

  • The main expression has the form if () then ... else .... (This is actually an XPath 2.0 expression, which supports the if construct.)

  • The normalize-space() function removes all leading and trailing space (and simplifies internal spaces as well). This is a little trick to not only test whether the first name is empty, but also to test whether it is an all-blank string.

  • Contrary to JavaScript, the equality test is expressed with a single = instead of ==.

  • The concat function concatenates all its parameters into a resulting string. It is like the JavaScript + operator on strings.

  • Note the use of the single quote ' around strings. This is needed because the XPath expression is put within double quotes " in the value attribute.

Page Flow

If you look at your browser's URL bar when showing the example, you notice that it looks like this:

http://localhost:8080/orbeon/xforms-hello/
  • The first part of the URL, http://localhost:8080/, is self-explanatory: it depends on what host and port your server is running.

  • The next part, orbeon, depends on what context you install Orbeon Forms into. By default, because the WAR file is called orbeon.war, the context is orbeon. (You could as well configure your container to use a different context, or an empty (default) context.)

  • The last part, /xforms-hello/, automatically matches the name of the directory you store your application into (more on this later when you look at the source code). This causes the application's page flow (page-flow.xml) to run.

So now look at page-flow.xml for the Hello application. It is very simple:

<controller xmlns="http://www.orbeon.com/oxf/controller">
    <page path="*" view="view.xhtml"/>
    <epilogue url="oxf:/config/epilogue.xpl"/>
</controller>

The important line in this page flow is this one:

<page path="*" view="view.xhtml">

It tells Orbeon Forms that any path (notice the wildcard *) sent by the web browser to this application causes the page view stored in view.xhtml to be processed. You can check this by entering the following path in your browser:

http://localhost:8080/orbeon/xforms-hello/my-page

The exact same result shows! Of course, page flows make the most sense when you have more than one page in your application, which translates into more than one <page> element.

Orbeon Forms resources

Under TOMCAT_HOME/webapps/orbeon, you find a WEB-INF directory. That directory, in turn, contains a resources directory. We refer to that resources directory as RESOURCES below.

The RESOURCES directory is very important: this is where your application lives. This directory is called "resources" because it contains all the files (or resources) such as XHTML documents, XML schemas, images, CSS, etc. needed by your Orbeon Forms application.

NOTE: Orbeon Forms supports storing your resources pretty much anywhere you want. For convenience, by default they are available under the WAR file's WEB-INF/resources so you can get up and running without configuration.

A look into the resources directory structure

Under RESOURCES, you see the following files and directories:

  • apps directory: contains one sub-directory for each application currently running in Orbeon Forms. By default, it contains a series of sample applications - the ones that you see on the left side of your screen when you start Orbeon Forms. Notice a directory called xforms-hello: this is the directory that contains the Hello application.

  • config directory: contains several configuration files that you can modify if needed. For now, you don't need to worry about this directory.

  • page-flow.xml file: the top-level page flow file. You should not worry about this file just yet. Just know that by default, it is in charge of deciding which application to run depending on the application name in the URL that you enter in your web browser.

  • apps-list.xml file: contains the list of sample applications to display on the left side of the screen. This is not needed by your own application.

Playing with the hello application source code

You find the application under RESOURCES/apps/xforms-hello. That directory contains the two files that you have seen earlier through the Source Code Viewer in your web browser. Again, the name xforms-hello is important and matches the xforms-hello part of the URL in your web browser: http://localhost:8080/orbeon/xforms-hello/.

NOTE: In this tutorial, you will often have to "reload" pages in your web browser to see the effects of your changes to XHTML or XForms markup. Because of the way Orbeon Forms handles page reloads with XForms, for consistent results we recommend that you don't simply use your browser's reload button, but instead use one of the following two ways to reload a page:

  • Position your text cursor on your browser's URL bar and press the "Enter" key. Browsers often have keyboard shortcuts such as CTRL-L or CMD-L to reach the URL bar.

  • Use your browser's "force reload" feature. This is often enabled by pressing the SHIFT key and pressing the "reload" button at the same time. Browsers often have keyboard shortcuts such as CTRL-F5, CTRL-SHIFT-R, or CMD-SHIFT-R to perform this operation.

Now, modify view.xhtml:

  • Open view.xhtml in a text editor.

  • Modify the string "Please enter your first name:" with "Your name here:".

  • Save view.xhtml.

  • Go back to the Hello application in your web browser and reload the page. You should see the new text appear:

  • Repeat the experience but add some XForms. For example, add a second <xf:input> right after the first one:

    <xf:input ref="/first-name" incremental="true">
    <xf:input ref="/first-name" incremental="true">

Reload the page, and notice, as you type in an input field, how the other one updates as you type. This happens because the two fields are bound to the same instance data. The incremental="true" attribute allows the changes to occur as you type, instead of occurring when you focus in and out of fields:

You notice that you get instant gratification with Orbeon forms: just change files on disk, reload your page, and your changes are taken into account with no compilation or other complex deployment.

Another difference with plain HTML is that there are tags that start with the string xf:. Those are defined by the from W3C. They are at the heart of Orbeon Forms and enable all the cool forms features that you see in Orbeon Forms demos. (In order to use XForms tags that start with xf:, you must add another namespace declaration on the <html> tag: xmlns:xf="http://www.w3.org/2002/xforms".)

XForms specification
online on the Orbeon website