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

Programmer's Guide

Contents

  1. 1 What is Form Runner?
  2. 2 Benefits of Form Runner
  3. 3 Mini-FAQ
    1. 3.1 Q: Do I need to use Form Builder in order to use Form Runner?
    2. 3.2 Q: Does Form Runner replace Orbeon Forms / the XForms engine?
    3. 3.3 Q: Does any custom XHTML+XForms document work out of the box with Form Runner?
    4. 3.4 Q: I need support for database XYZ. Do you have support for it?
  4. 4 How to write a form for Form Runner
  5. 5 PDF output
  6. 6 Flexible Persistence Layer

What is Form Runner?

Orbeon Form Runner is the Orbeon Forms runtime environment. Form Runner manages form types and form data, handles search, validation, and takes care of the plumbing necessary to capture, save, import and export form data. 
High-Level View of Orbeon Forms with Form Runner/Form Builder

Benefits of Form Runner

Form Runner has the following benefits:
  • Built-in look and feel
  • Forms management
  • Built-in search
  • As-you-type validation
  • Error summary
  • Printable HTML output
  • PDF output
  • Email support
  • Full internationalization
  • Library of user interface components (see XBL - Existing XBL Components)
  • Offline mode (under development)
[TODO: expand on those, and explain that one benefit is maintaining a common code base rather than reinventing the wheel]

Mini-FAQ

Q: Do I need to use Form Builder in order to use Form Runner?

A: No, you don't. You can use Form Runner without using Form Builder.

Q: Does Form Runner replace Orbeon Forms / the XForms engine?

A: No, Form Runner is part of Orbeon Forms. It is a layer, written itself in XForms/XSLT/XPL, on top of other Orbeon Forms technologies like the XForms and XPL engines.

Q: Does any custom XHTML+XForms document work out of the box with Form Runner?

A: No, Form Runner requires a few conventions related to the structure of the page. See below for details.

Q: I need support for database XYZ. Do you have support for it?

A: As of 2009-12, Form Runner supports out of the box:
  • The open source eXist native XML database.
  • Oracle XML. This means that documents are stored into Oracle as columns of type XMLType according to a database schema chosen by Orbeon.
  • Write-only support for the Alfresco CMS.
For other databases or systems, you can implement the persistence API yourself or ask Orbeon to do the work for you. Either way, you can implement that API using any programming language / technology you want since the API is REST-based.

NOTE: There are several storage options to consider if your target database is a relational database (as opposed to a native XML database):
  • The easiest thing to do is to store Form Runner forms and data as a native XML type (if your database supports one) or CLOB/BLOB.
  • For forms created by Form Builder, which produce a predefined structure for the data, using generic SQL tables could work as well.
  • If you need to do shredding (store all the data into custom relational tables)
    • this is not too difficult if you have only a given, predefined set of forms to work with
    • if you want generic shredding (e.g. handle any form created by Form Builder), then some sort of XML-relational conversion is required, which makes the problem more difficult

How to write a form for Form Runner

If you have an existing XHTML+XForms page, follow these steps to run the form in Form Runner: 
  • Add class fr-form-model to the main XForms model
  • Add class fr-form-instance to the main XForms instance
  • Create a fr-form-metadata instance with form metadata (see Bookshelf example)
  • Use elements fr:view/fr:body in the page view
  • Optional: Use fr:repeat to get a repeater with built-in +/- buttons
  • Place the resulting form (replace APP-NAME/FORM-NAME) as:
    [RESOURCES]/forms/[APP-NAME]/[FORM-NAME]/form/form.xhtml
  • Add this properties (replace APP-NAME) to your [RESOURCES]/config/properties-local.xml
    <property as="xs:anyURI"  name="oxf.fr.persistence.app.uri.[APP-NAME].*.form" value="/fr/service/resource"/>
For an example, look at the Bookshelf example under:

[RESOURCES]/forms/orbeon/bookshelf/form/form.xhtml 

[TODO: more specific details]

PDF output

Orbeon Forms supports producing PDF either automatically by following the layout of the HTML output, or by using PDF templates. In that case you can accurately match the layout of existing PDF or paper forms.

For more information on PDF output, see the Form Builder User Guide.

Flexible Persistence Layer

Out of the box, Orbeon Forms stores data in its embedded eXist XML database. But you can easily customize Orbeon Forms to your needs by hooking into Form Runner's REST-based perstistence API.

[TODO: explain how this works]

For more information on the Form Runner persistence layer, see the Form Runner Integration Notes.