Orbeon Search

Comments? Feedback?

This wiki does not yet support public comments (a limitation of Google Sites), so we encourage you to post your comments either:

On Twitter by responding to @orbeon.

On our community mailing list: subscribe sending an email to ops-users-subscribe@ow2.org (content of subject/body doesn't matter), you'll get a response with the email to use to send your message to the community mailing list.

Recent site activity

Form Runner/Form Builder Integration

Contents

  1. 1 Installation
  2. 2 Overall architecture
  3. 3 Integration points
    1. 3.1 Form Runner and Form Builder URLs 
    2. 3.2 Persistence API
    3. 3.3 XML representation of form data
    4. 3.4 Basics
    5. 3.5 Attachments

Installation

Form Builder is distributed as a Java WAR file. You install it into a Servlet container, preferably Tomcat 5.5 or later.

Installation notes are availabe online as part of the Orbeon Forms tutorial:


We recommend, for testing, that:

  • you deploy the WAR file under the "orbeon" context
  • you deploy as an "exploded WAR" file, that is an unzipped WAR file

Once the WAR file is deployed, restart your container and access the following URL, assuming a default port of 8080 for your container:

This is the Summary page of Form Builder. The page should look like the following (most likely without any content in the summary table):

Then select "New Form". This takes you to a new empty form, in which you can enter an application and form name:
If you get to this point, the installation has succeeded and you can proceed to edit your form:
Form types and form data
We make a distinction between:
  • Form types, for example an "address" form vs. a "claim" form
  • Form data, for example a given instance of the "address" form filled out by a particular user.
In Form Builder, a form type is identified by a two-level hierarchy of names:
  • An application name, which could be a company name such as example "orbeon", "acme", or an actual project name such as "mercury", "foobar", etc.
  • A form type name, which is local to an application name, for example "address" or "claim".
This two-level hierarchy allows for easy grouping of forms, and allows using a single instance of Form Builder to host distinct applications.

Form data is identified by a three-level hierarchy which includes:

  • the application name/form type name couple that identifies the form type
  • plus a unique form data id provided by Form Runner for each instance of form data

Overall architecture

Form Builder actually consists of two parts:

  • Form Builder proper, aimed at form authors, allows you to create, edit and manage forms types.
  • Form Runner, aimed at users of the forms, allows you to create, edit and manage form data related to published form types.

Form Builder/Runner are implemented on top of the open source Orbeon Forms platform. They are implemented entirely with the following technologies:

  • XForms for the user interface (along with XHTML and CSS)
  • XPL (XML pipelines), mainly as a glue between XForms and services such as persistence services
  • XSLT, mainly to provide higher-level components for Form Runner

Form Builder is written essentially in XForms, but it also produces, for each form type edited, an XForms file which Form Runner can load and run. In short, Form Builder is an XForms application which is able to produce other XForms applications.

Both Form Builder and Form Runner share a persistence layer, which in turn allows them to talk to databases or external services. Form Builder/Runner comes with a built-in XML database called eXist, which by provides persistence out of the box. However, you can also access an external eXist instance, or implement your entirely custom persistence layer in your own system.

The following figure illustrates the overall architecture:

Integration points

Form Builder/Form Runner integrate with other systems through two main means:
  • Plain URLs, through which you access Form Runner and Form Builder's pages
  • A configurable persistence API based on REST (that is, through HTTP)
The URLs can be accessed simply by using hyperlinks or redirects from another application.

The persistence API can be implemented either within Orbeon Forms (like for example the built-in eXist persistence layer), or within an external system.

Form Runner and Form Builder URLs 

Form Runner/Form builder attempt to use friendly URLs.

The following URL patterns are followed:
  • Summary page for a given form type:
    /fr/[APPLICATION_NAME]/[FORM_NAME]/summary
  • New empty form data:
    /fr/[APPLICATION_NAME]/[FORM_NAME]/new
  • Edit existing form data:
    /fr/[APPLICATION_NAME]/[FORM_NAME]/edit/[DOCUMENT_ID]
  • Read-only HTML view:
    /fr/[APPLICATION_NAME]/[FORM_NAME]/view/[DOCUMENT_ID]
  • Read-only PDF view:
    /fr/[APPLICATION_NAME]/[FORM_NAME]/pdf/[DOCUMENT_ID]
For Form Builder itself:
  • Summary page:
    /fr/orbeon/builder/summary
  • New empty form type:
    /fr/orbeon/builder/new
  • Edit existing form type:
    /fr/orbeon/builder/edit/[FORM_ID]
NOTE: All paths above are relative to the deployment context, e.g the actual URLs start with http://localhost:8080/orbeon/fr/...

NOTE: As of May 2009, the paths have been changed to not include a trailing slash so as to help working around a Firefox bug related to file downloads.

Persistence API

This content has moved to: Form Runner/Form Builder Persistence API.

XML representation of form data

Basics

As you create a form definition with Form Builder, an XML representation for the data to capture is automatically created. It is organized as follows:
  • A root element:
    <form>
  • Within that element, for each section, a sub-element named after the section name:
    <address>
  • Within a section element, a sub-element for each control in the section, named after the control name:
    <first-name>
  • Within each control element, the value of the control is stored:
    <first-name>Alice</first-name>
Example:

<form>
    <details>
        <title/>
        <author/>
        <language/>
        <link/>
        <rating/>
        <publication-year/>
        <review/>
        <image filename="" mediatype="" size=""/>
    </details>
    <notes>
        <note/>
    </notes>
</form>

NOTE: Grids don't create containing elements.

Attachments

For attachments, the control element is slightly different:
  • The text content is a URL pointing to the location of the attachment in the persistence layer:
    • <my-attachment>/fr/service/exist/crud/orbeon/builder/data/5277.../book.png</my-attachment>
  • Attributes are used for storing:
    • the file name
    • the file media type
    • the file size
    • <my-attachment filename="book.png" mediatype="image/png" size="13245">/fr/...</my-attachment>