More topics

Managing and using form definitions

Last updated on November 22, 2024

Form definitions are the "code" that represents the form. You can save, restore and share them.

On this page:

 

What form definitions are

Form definitions are a set of X-HTML and X-Forms code that describe how the form is structured, what it collects, and how it interacts. It's an XML file that can be embedded in websites and applications. When you publish the form in the form builder, it's this file that's copied into the form runner.

Viewing a form's definition

You can view a form's definition from the editor screen.

  1. Click Advanced on the toolbox
  2. Click Edit Source

The Source window will display, showing you the code.

Editing a form definition

Editing a definition, especially directly, is discouraged.

  • X-Forms are more complicated than regular HTML and XML
  • Code for a given control can be in 2 or 3 places
  • The Source window's size and wrapping can make editing more difficult
  • Coding errors can have undesirable impacts
  • There's basically nothing you could add or change that can't be done in the form builder interface

If you're comfortable with XML though, a good reason to edit the definition is to quickly add label/value pairs to long pulldown, checkbox or radio button controls. These can be much faster to type (or copy from another resource) than set up through the interface.

In this or similar cases:

  1. Add the controls you need to the form and name them
  2. Save your form
  3. Save your form definition
  4. Use an XML editor (like Notepad++) to edit the file
  5. Save the file
  6. Replace the current definition with the new one
  7. Save your form

Saving a form definition

You can save (export) a form definition to:

To export a form definition:

  1. Click the XHTML Export button. The Save As window is displayed
  2. Edit the file name, if desired. Consider adding the current or edition date
  3. Navigate to the location where your want to save the file
  4. Click Save

Sharing a form definition

You may have a form that someone from another ministry would like to use to build their own.

Simply provide them with:

  • The form definition
  • Any embedded files they'll need, like images
  • Any PDFs or design files used
  • Any other records or supporting information that would be useful to them

Consider just compressing your latest edition records into a zip file and emailing it to them.

Using someone else's definition

If someone from another ministry has shared a form definition and related files with you, you'll import this new form into your environment in 3 basic steps:

  1. Edit the Application name in the form definition
  2. Create a new form and replace the source code
  3. Import any assets needed

To edit the shared definition:

  1. Open the definition using a text or XML editor
  2. Locate the <Application> tag
  3. Change the value to the Application you use
  4. Save the change
  5. Select the content of the file (Control-A)
  6. Copy the content of the file (Control-C)

Editing the tag helps ensure that the form will appear properly in your environment.

To 'import' the form:

  1. Create a new form
    • Give it any Form Name and ignore the other fields
    • These will be replaced by the imported definition
  2. Click Edit Source in the Advance toolbox. The Source window is displayed
  3. Select the contents of the Source window (Control-A)
  4. Replace the contents of the Source window (Control-V)
  5. Click Apply
  6. Click Form settings in the Advanced toolbox
  7. Update the Basic Settings as desired
  8. Click Apply
  9. Click Save

You'll now have a copy of the form in your environment, ready for editing.

Importing assets:

Assets are things like images or PDF templates that have been added to the form.

Orbeon will know these files are supposed to present, but won't have a copy of them in the database. You'll need to 're-import' them to add the files to the database.

  • For images, simply click the "X" to remove them from the control, then upload the replacement image
    • If the image is a program or ministry wordmark, you'll likely want to use the correct one anyway
  • For templates, simply click the "X" next to the template name, then upload the replacement template
    • To access the templates, click PDF Templates in the Advanced toolbox   
    • You may want to edit and revise the template before you upload it or publish the form

These actions will add the images or templates to the database for testing and publishing.

Restoring a form with a saved definition

You may need to restore a form to a previous definition when:

  • A minor revision is cancelled before release
  • An urgent revision to the released form is needed during a minor revision
  • The client wants to "roll-back" a released minor or major revision

To restore a form definition to an earlier version:

  1. Open the saved definition with a text or XML editor
  2. Select the contents of the defninition (Control-A)
  3. Copy the contents of the defninition (Control-C)
  4. Open the form's Source window
  5. Select the contents of the form's source code (Control-A)
  6. Replace the contents of the form's source code (Control-V)
  7. Click Apply
  8. Click Save

Post-restoration steps:

Depending on the differences between editions and the status the form was in, you may need to: