Forms produced by Form Builder also run on IE 6 and older browsers.
Lifecycle of a form
Overview
Deployment use cases for Form Builder and Form Runner can vary depending on configuration, but here is a typical life for a form:
- Design time — The form author
- Initiates the creation of a new form definition from the Form Builder summary page
- Edits the form definition from the Form Builder editor
- Saves the form definition
- Tests the form definition
- Multiple edit/save/test cycles can take place
- Publishes the form definition
- Runtime — The form user
- Initiates the creation of new form data from the form's summary page
- Enters data into the form
- Reviews, saves, submits, or downloads form data
Form definitions, as well as form data, can also be searched and deleted.
Publishing
The notion of
publishing is central to Form Builder/Form Runner.
- As a form author, you work on a form definition in a special space where the form can be modified, saved, and tested.
- Once the form definition is ready, you publish it to Form Runner.
- After that moment:
- the form becomes available by form users for data entry
- Form Builder is no longer part of the equation
NOTE: As of November 2011, Form Builder has very limited support for versioning of form definitions. While you can publish a form multiple times, the new version overwrites the older version, therefore caution must be applied.
Form Builder summary page
Purpose
The Form Builder summary page is your starting point when you work with Form Builder. It allows:
- Listing, searching and navigating form definitions
- Creating new form definitions
- Editing form definitions
- Deleting form definitions
- Testing form definitions
NOTE: Form definitions are usually stored in a database on the server. You do not usually keep them on your own computer.
Accessing the summary page
You access the summary page from your web browser through a URL (or web address) of the form:
http://[SERVER NAME]/orbeon/fr/orbeon/builder/summary/
NOTE: The exact URL might be provided by your IT organization.
Once you reach the summary page, you will either see an empty list, or a list containing existing form definitions, as shown in this screenshot.
For each form definition, the list shows:
- Creation date
- Last modification date
- Application name
- Form name
- Form title
- Form description if any
If the list doesn't fit entirely on one page, you can
navigate to further pages of results using the navigation arrows at the
bottom of the results list.
If the list is too wide, a horizontal scrollbar appears at the bottom of the list and allows you to navigate horizontally.
By default, the summary page lists all the form definitions which you have access to.
NOTE: Depending on your permissions, the Application Name field
and/or Form Name field might be input fields or dropdown menus that
restrict your choices.
Searching and navigating form definitions
The top of the summary page features search fields. There are two types of searches:
- Free text search. This searches any text within the form definition.
- Structured search. This searches on Application Name, Form Name, Form Title, or Form Description.
To search: enter a search term and press the "Search" button or the "enter" key.
Tip: to clear the search and list all the form definitions again, clear all search fields and press the "Search" button or the "enter" key.
Creating a new form definition
To create a new form
definition, press the "New" button at the bottom of the page. This
opens the Form Builder editor in a separate browser window or tab.
Deleting a form definition
Using the checkboxes that appear on each row, select the form definitions you wish to delete, then press the "Delete" button.
Testing a form definition
Using the checkboxes that appear on each row, select a
single form definition and press the "Test" button.
A new browser window or tab opens with the form in test mode. Note that you can also test forms directly from the editor.
The form editor
Creating your first form definition
After pressing the "New" button on the summary page, you reach the form editor proper. Form Builder requires that you provide two small pieces of information before starting:
-
Application Name. Each form definition has an application name which identifies a group of forms that belong together. In practice, an application name might correspond to a project, or a department, or a company. For example, all forms built by Orbeon have the "orbeon" application name.
NOTE: Depending on your permissions, the application name might have been picked for you already, or you might have the choice of a restricted set of application names.
- Form Name. Each form definition also has a form name, which identifies a unique form name within a particular application.
Both application name and form name must respect a certain format:
- Use letters and optionally numbers and separators like "-" and "_"
- Start with a letter
- Do not use spaces
NOTE: One reason for these restrictions is that the names will eventually appear in your browser's URL bar when the form is deployed and it is better to have clean-looking URLs.
For your first form, don't worry too much about those: just enter any name! You can always change these settings later!
General Form Builder layout
Form Builder's form editor is organized in 4 areas:
- Top: title area with status information and selection of the Form Builder user interface language.
- Left: the toolbox, which might scroll vertically depending on your browser or monitor size.
- Bottom: status icons and buttons.
- Center: WYSIWYG area where you actually edit your form definition. This area might scroll vertically depending on your browser or monitor size or the size of the form you are editing.
The top bar
On the top right corner of the top bar, you can change the Form Builder user interface language by clicking on one of the languages available. Currently, English and French are available. More languages may be added in the future.
Changing the language immediately updates the Form Builder user interface: you do not even need to save your form prior to using this feature.
NOTE: This feature controls the language of the Form Builder user interface only. For localization of the form definition you are currently editing, see documentation below.
In addition, the top bar will display status information, such as whether the current form definition was successfully saved.
The bottom bar
The bottom bar of Form Builder shows two types of elements:
- Status icons
- Errors on Form icon. This red icon indicates whether there are errors in the form, such as a missing title or missing section titles. If this icon appears, you cannot save your form definition.
- Unsaved Changes icon. This icon indicates whether there are some unsaved changes.
- Buttons
- Close button. Close the browser window/tab in which Form Builder is open.
- If the form has unsaved changes, a warning dialog shows first.
- Otherwise, the window/tab closes and takes you back to the Form Builder summary page.
- Test button. Test the current form. If the form contains errors, this button is disabled.
- Publish button. Publish the current form. If the form contains errors or has unsaved changes, this button is disabled. You must fix errors and save the form before you can publish it.
- Save button. Save the form to the database.
The Form Builder toolbox
The toolbox contains several categories:
- Controls
- Global cut/copy/paste and "reload controls" icons
- New Section and New Grid buttons
- User interface controls you can insert into your form
- Metadata. Allows you to modify the application name and form name.
- Advanced. Includes advanced features like XML Schema, PDF and source code view.
- Services & Actions. Editor for simple services and actions.
Depending on your monitor or browser size, you can use the scrollbar to the right of the toolbox to see more toolbox content. Each toolbox category can be expanded or collapsed by clicking on the category title.
These categories are detailed below.
Cut, copy and paste
The Cut, Copy and Paste icons are located at the top of the toolbox:
They allow performing the usual cut/copy/paste operations on form controls.
- Copy: copies the control in the currently selected table cell to the Form Builder clipboard. If the cell is empty, nothing happens.
- Cut: same as Copy, but removes the control from the current grid cell. If the cell is empty, nothing happens.
- Paste: pastes the control in the Form Builder clipboard to the next available grid cell. If there is no control in the clipboard, nothing happens.
NOTE: These operations are restricted to the currently running instance of Form Builder. They do not apply between different Form Builder windows or tabs, or between edition sessions.
The following control information is copied and pasted:
- Control type
- Name
- Label, hint, and help
- Itemset
- Validation settings including data type and constraints
- All associated localized resources
When the control is pasted, if the control name of the clipboard control is currently not in use in the form, it is used. Otherwise, a new name is chosen by Form Builder.
User interface controls
The toolbox contains the user interface controls you can insert into your form, grouped by category:
- Text controls. Controls that just capture or show text.
- Typed controls. Controls that have type information associated, like email, phone number, attachments, etc.
- Selection controls. Controls that allow selecting one or more values, like dropdown menus, radio buttons, etc.
- Other controls. Currently this only includes buttons.
- Section templates. Custom controls representing a complete section.
To add a control to your form, simply click on the control. The following insertion logic is implemented:
- If the currently selected grid cell is empty, the control is inserted there.
- Otherwise, if the cell to the right of the currently selected grid cell is empty, the control is inserted there.
- Otherwise, if the control is the last control of the grid, a new grid row is inserted and the control is inserted in the first cell of the new row.
- Otherwise, the controls in the toolbox are disabled and you cannot insert a new control.
Controls appear in the grid in two ways:
- Most of the controls appear in a WYSIWYG manner.
- Some controls are represented just with an icon. This is the case of some controls such as phone number, currency fields, etc.
Orbeon is expecting feedback from users on the controls marked
experimental below.
New section button
Pressing this button inserts a new section into the form. The section is inserted after the currently selected section, that is the section containing the currently selected control.
After insertion, the new section has an empty title. You can change the section title by clicking on it.
New grid button
Pressing this button inserts a new grid into the form. The grid
is inserted after the currently selected grid within the currently selected section, that is the section and grid
containing the currently selected control.
After insertion, the new grid has one column and one cell. You can change the dimensions of the grid using the grid icons.
Text controls
The following text controls are available from the toolbox:
- Standard
- Single-Line Text: simple input field.
- Multi-Line Text: simple multi-line input area.
- HTML Text: rich text input area.
- NOTE: At design time, currently shows as a regular multi-line input area.
- NOTE: At runtime, does not work in accessible mode.
- Text Output: simple text output. This control does not allow data entry at runtime: instead, it just shows the text captured at design time.
- Experimental
- Inplace Input: like the standard input field, but requires clicking on the text to switch to a mode where the text can be changed.
- NOTE: At runtime, does not work in accessible mode.
Controls appear as follows in Form Builder:
At runtime, with data captured:
At runtime, in preview mode:
Typed controls
The following text controls are available from the toolbox:
- Standard
- Date: date field with date picker.
- Time: time field.
- Date and Time: date and time field.
- Email Address: input field which validates that the content is an email address.
- Static Image: image displayed on the form at design time. It is not possible to change the image at runtime.
- Image Attachment: image which can be attached to the form at design time, but which can also be changed at runtime.
- File Attachment: file which can be attached to the form at design time or at runtime. The file can also be replaced or downloaded once attached.
- Experimental
- Dropdown Date: date chooser which uses dropdown menus.
- Fields Date: date chooser which uses separate text fields.
- Date Picker: date chooser which just uses a date picker.
- US Phone Number: US phone number showing area code and number in separate fields.
- Dollars (Thousand): field to capture dollars as thousands.
Controls appear as follows in Form Builder:
At runtime, with data captured:
At runtime, in preview mode:
Selection controls
The following selection controls are available from the toolbox:
- Standard
- Dropdown (single selection)
- Radio Buttons (single selection)
- Checkboxes (multiple selection)
- Single List Box (single selection)
- Multi List Box (multiple selection)
- Experimental
- Data Dropdown (single selection dropdown bound to a service)
- Autocomplete (single section with completion)
- Link Selector (single selection with items shown as clickable links)
Controls appear as follows in Form Builder:
At runtime, with data captured:
At runtime, in preview mode:
Data dropdown
[SINCE 2011-05-10]From the perspective of people who will be filling out your form, the data dropdown works just like a regular dropdown. However, the data in the dropdown comes from a service. For instance, imagine you have a list to select a state and that you don't want to hard code the list of states in the form, either for convenience, or because the subset of selectable states is dynamic:
- Insert a data dropdown field.
- Click on cogwheel to bring up a Edit Control Details dialog, similar to the one shown to the right.
- In the Resource URI, enter the address of an HTTP service that returns the data you want to use to populate the dropdown. In most cases, the URL will look like
http://your-host/your-service. If the address you specify start with a /, it is relative to the Orbeon Forms web app, which allows you to access a service you might have implemented in Orbeon Forms with XPL. For this example, let's assuming your service returns a list of states that looks like:
<states>
<state abbreviation="AK" name="Alaska"/>
<state abbreviation="AL" name="Alabama"/>
<state abbreviation="AR" name="Arkansas"/>
...
</states>
- In the Items field, enter an XPath expression that returns one node per state. In this case, it will be:
/states/state. - For each state (item), specify an expression relative to the node returning the label (shown to users in the dropdown) and the value (stored in the data). In this case, those expressions will be, respectively:
@name and @abbreviation.
If the data in the dropdown depends on a value entered by users in another form field, you can pass that value to the service as a request parameter. For instance, let's say that in addition to the
State dropdown, you have a
City dropdown where you want to list all the cities in the currently selected state. If the service is at
/xforms-sandbox/service/zip-cities and takes a request parameter
state-abbreviation, assuming you named your
State field
state, in the
Resource URI enter:
/xforms-sandbox/service/zip-cities?state-abbreviation={$state}
[AS OF 2011-05-10] Limitation: you can't yet use a variable, as shown in the above example, to refer to another fields value. Instead, if the control is in the same section use
{state}; if in a different section with name other-section, use
{../other-section/state}.
Autocomplete
[SINCE 2011-05-10] The autocomplete control is a single item selection control that loads a list of suggestions from a service. It takes the same
Resource URI,
Items,
Label, and
Value configuration parameters as the
Data dropdown control. You may want to pass the value of other controls to the service, but you'll always want to pass the currently typed value, as the suggestions should depend on what users typed so far. You access to the currently typed by value with
$fr-search-value, as in the following example:
/xforms-controls/services/countries?country-name={$fr-search-value}
Other controls
The following miscellaneous controls are available from the toolbox:
- Button: standard browser button.
- YUI Button: more stylish button with cross-browser appearance (based on the YUI library).
Controls appear as follows in Form Builder:
At runtime:
NOTE: Buttons do not appear at all in preview mode.
Buttons do not allow entering data, and by default do nothing significant, but they can be used to trigger actions with the Action Editor.
Section templates
The Form Builder WYSIWYG area
Introduction
The WYSIWYG area is meant to looks as much as possible like the published form.
Form Builder is built around as simple layout concept:
sections and
grids. This is thought to be a good alternative to:
- absolute positioning, which is rarely appropriate for web forms
- complex layouts, which often confuse form authors
In the future, Form Builder might add extended layout options.
In-place editing
Form Builder allows you to edit certain text information in-place. This just means that text appears as it would in the published form, and is editable when you click on it.
To edit such text:
- Click on the text (or placeholder text)
- An input field appears
- Enter the text
- Press the Apply button
To indicate that the text is editable, it highlights when the mouse hovers over it.
This mechanism is how you edit:
- Form title
- Form description
- Section title
- Field label
- Field hint
Form logo, title, and description
Form Builder allows you to upload an optional logo which appears at the top of your form. Simply use the upload control to upload a logo, and it will appear on the page. It is recommended to use a small, horizontal logo, not unlike the Orbeon logo itself.
The form title is mandatory. The title can be edited in-place: just click on it to make an input field appear.
The form description is optional. You edit it in the same way you edit the title.
This screenshot shows an example with:
- The Orbeon logo
- The title "Video Collection"
- The description "This form allows you to enter data about your video collection"
Sections and grids
Form Builder represents every form as a series of
sections:
- A section is simply a logical grouping of form controls. For example, your form may have an "address" section, and a "personal details" section.
- Sections are presented in order, on top of each other.
- Every form has at least one section.
- There is no maximum number of sections within a form.
You can perform the following operations on sections.
- Set the section's title by clicking on it. The title is localizable.
- Delete the section by clicking on the Trashcan icon. If the section contains controls, a confirmation dialog appears.
- Set an optional help message for the section by clicking on the help icon. The help is localizable.
- Set other section properties.
- Open or collapse the section by clicking on the arrow to the left of the section title.
- Move the section up or down by clicking on the up/down arrows. These appear as needed if there is more than one section.
Each section contains one or more
grids:
- A grid is a logical grouping of form controls organized in rows and columns of cells.
- A grid has between 1 and 4 columns.
- A grid may have any number of rows.
- Each grid cell may contain a single form control, or remain empty.
- A grid cell might span multiple rows.
- Unlike a section, a grid does not have a title or properties.
When your mouse pointer hovers over a grid, the grid boundaries, cells and icons are highlighted.
The following screenshot shows two sections, "Section 1" and "Section 2". The first section contains a 3 columns by 2 rows grid.
You can perform the following operations on grids:
- Add grid columns by clicking on the left and right arrows at the top of each column.
- Add grid rows by clicking on the up and down arrows on the left of each row.
- Delete a column by clicking on the trashcan icon at the top of a column.
- Delete a row by clicking on the trashcan icon on the left of a row.
- Delete the entire grid by clicking on the trashcan icon on the top left corner of the grid.
For delete operations, a warning dialog shows if controls will be deleted as a result.
Grid cells and controls
Each grid cell can contain a single form control, or no control at all. If a control is present, the following actions related to the control are possible:
- Set control label: click on the label (in-place edition)
- A control's label appears on top of the control. It is intended to provide a descriptive label for the form control.
- Examples: "First Name", "Street", "Phone Number".
- Set control help message: click on the "question mark" icon to open the Edit Help dialog
- Set control hint: click on the hint (in-place edition)
- A control's hint usually appears under the control. It is intended to provide a short indication to the form user of how to fill-out the form control.
- Examples: "Your first name", "Date in mm/dd/yyyy format".
- Set control default value: simply enter text or select a value
- Edit the control's items: click on the "Edit Items" icon or test to open the Itemset Editor dialog (selection controls only)
When your mouse pointer hovers over a grid cell containing a control, some icons allowing for further actions appear:
- Delete Control icon: deletes the control.
- This also removes information associated with the control, including validation properties and XML representation.
- Control Details icon: opens the Control Details dialog.
- Validation Settings icon: opens the Validation Settings dialog.
- Expand icon: expands the cell down if possible.
- This allows the control to take two or more rows of space in the grid, for example for taller lists of radio buttons.
- If the control takes more than one grid row, then a Collapse icon performs the opposite operation.
- Switch Appearance icon: Switch between selection control types (selection controls only)
Form buttons placeholder
Currently, this is just an empty area showing where your form buttons such as "Save", "Close", etc. will be located.
Section Details dialog
Each section has:
- a name or identifier, which determines how section data is represented in XML
- XPath expressions that determine the section visibility and readonliness (advanced feature)
The section name specifies a identifier for the section, unique in the entire form.
If no section name is explicitly specified, Form Builder assigns a default name, such as "section-1".
The XPath expressions control:
- Visibility: whether the section is visible or not.
- Read-Only: whether the section is shown as read-only or not.
XPath expressions are described in more details here:
Advanced: XPath expressions in Form Builder.
Control Details dialog
Each control has some general properties:
- a name or identifier, which determines how control data is represented in XML
- options which can be enabled or disabled
The control name specifies a identifier for the control, unique in the entire form. The identifier is used for the following advanced features:
- to refer to the control value from XPath expressions
- to determine how the control value is represented in XML
If no control name is explicitly specified, Form Builder assigns a default name, such as "control-42".
The following options are available:
- Show in Summary: when selected, the control value is visible as a summary page column
- Show in Search: when selected, the control value is searchable in the summary page
- Email Recipient: when selected, the control is used to determine an email recipient in case the form data is sent by email
- Show in Email Subject: when selected, the control value is used as part of the subject of the email in case the form data is sent by email
Control Validation dialog
This dialog allows you to enter help text for a control:
Help is available at runtime through a help icon positioned next to the control:
- By default, the icon opens a help pop-up message.
- In accessible mode, the icon links to a help section at the bottom of the form.
The help text is localizable.
Itemset Editor
The itemset editor allows you to enter items for selection controls.
Each item has:
- A localized label, which appears to the form user.
- A value, which will is stored in the database.
At first, there is only one blank item available for the control. You add items using the "+" button, and remove them using the trashcan icons.
Usability notes:
- When in a label field, pressing the "tab" key into an empty value field automatically creates a default value. For example:
- "Apple" becomes "apple"
- "Wax Apple" becomes "wax-apple"
- When in a value field, pressing the "enter" key automatically adds a new item after the current item.
A value has constraints:
- For single selection controls (e.g. radio buttons), the value can be any string of characters.
- For multiple selection controls (e.g. checkboxes), the value must not contain spaces.
For convenience, the itemset editor allows you to switch between the list of available languages without quitting the editor.
Item values are not localizable: they remain the same for each language. On the other hand, item labels can be localized. For example:
- English
- Name: "Apple"
- Value: "apple"
- French
- Name: "Pomme"
- Value: apple
This ensures that the data captured is machine-readable even if the user interface language changes.
Form localization
Availability
Working with localization
Form Builder has localization support. This means that your form's titles, labels, help messages, etc. can be specified in multiple languages. At runtime, the form user is presented with a default language and can switch the most appropriate language.
By default, only one language is present, typically English. The default language is configurable by the Form Builder system administrator.
By pressing the "+" icon, a dropdown
dialog shows.
The dropdown list allows you to pick a new language to add to the list of languages of the form.
When a new language is added:
- It appears in the list of languages at the top right corner of the WYSIWYG area
- All the resources of the previously selected language are copied into the new language
You switch between languages by clicking on the language to select:
- The currently selected language is recognizable because it does not appear like an underlined link.
- All localizable resources edits impact the currently selected language.
You
can remove the currently selected language by pressing the "-" icon.
This will remove all the resources associated with that language, so
you must be careful before proceeding. A warning dialog will appear
before the deletion is completed.
Here is how you typically proceed to create a form in two languages:
- Create the form in the primary language and add all localizable resources such as labels, help messages, hints, etc.
- Add the secondary language.
- Translate all localizable resources now visible on the form.
- When testing the form, you can switch between the two languages to make sure no resource was missed.
Changing form metadata
The toolbox's "Metadata" section allows you to change the application name and form name associated with the form. Simply click the "Edit Metadata" link to update the fields.
PDF generation
Advanced: XML Schema upload
Working with an XML Schema
The toolbox's "Upload Schema" button under the "Advanced" section allows you to attach an XML Schema to the form. This serves two purposes:
- The schema is used to validate the form data.
- Simple types present in the schema are made available in the Validation Details dialog.
NOTE: As of June 2009, Form Builder cannot yet handle imported/included sub-schemas. If attempt to attach such a schema, a warning message is displayed.
Advanced: XPath expressions
See:
Advanced: XPath expressions in Form Builder.
