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

Configuration Properties - Form Runner

Contents

  1. 1 Default values
  2. 2 Back-end
    1. 2.1 Application server URI
    2. 2.2 Persistence
  3. 3 Summary page
    1. 3.1 Summary page size
    2. 3.2 Created and Last Modified columns
    3. 3.3 Default language
    4. 3.4 Buttons on the summary page
  4. 4 Detail page
    1. 4.1 Show Table of Contents
    2. 4.2 Position of Error Summary
    3. 4.3 Buttons on the detail page
    4. 4.4 Display hints inline
    5. 4.5 PDF and barcode
    6. 4.6 Font embedding in PDF in "notemplate" mode
    7. 4.7 Captcha
    8. 4.8 Initial instance
      1. 4.8.1 Initial instance posted to the New Form page
      2. 4.8.2 Initial instance from service
  5. 5 View page
    1. 5.1 Buttons on the view page
  6. 6 All pages
    1. 6.1 Buttons configuration
      1. 6.1.1 Submit Button
      2. 6.1.2 Workflow send button
    2. 6.2 Show Orbeon Forms version
    3. 6.3 Default logo
    4. 6.4 Default CSS
    5. 6.5 Overriding resources
    6. 6.6 Email settings
    7. 6.7 Oracle settings
  7. 7 Noscript and Ajax modes
    1. 7.1 Show Noscript link
    2. 7.2 Noscript: use table layout

Default values

For the latest configuration, see properties-form-runner.xml.

Back-end

Application server URI

NOTE: To configure access to the application server, see Configuration Properties - Base and the oxf.url-rewriting.service.base-uri property.

Persistence

<property as="xs:anyURI" name="oxf.fr.persistence.app.uri.*.*.*"
          value="/fr/service/exist"/>
<property as="xs:anyURI" name="oxf.fr.persistence.app.uri.orbeon.builder.form"
          value="/fr/service/resource"/>
<property as="xs:anyURI" name="oxf.fr.persistence.app.uri.orbeon.bookcast.form"
          value="/fr/service/resource"/>
<property as="xs:anyURI" name="oxf.fr.persistence.app.uri.orbeon.bookcast.data"
          value="/fr/service/exist"/>

Configuration of the persistence layer. See this page for more details. The third wildcard matches on either "form" (form type or form definition) or "data" (form data).

NOTE: The configuration has changed between Orbeon Forms 3.9 and later builds.

Summary page

Summary page size

<property as="xs:integer" name="oxf.fr.summary.page-size.*.*" value="10"/>

Number of rows shown in the summary page.

Created and Last Modified columns

By default, the summary page shows a Created and Last Modified columns:


You can remove either one of those columns by setting the value appropriate property to false:

<property as="xs:boolean" name="oxf.fr.summary.show-created.*.*"        value="true"/>
<property as="xs:boolean" name="oxf.fr.summary.show-last-modified.*.*"  value="true"/>

Default language

<property as="xs:string" name="oxf.fr.default-language.*.*" value="en"/>

Form Runner's default language.

Buttons on the summary page

<property as="xs:string"  name="oxf.fr.summary.buttons.*.*"
          value="new edit print pdf delete"/>

The property configures which buttons are included on the summary page, and in what order they are shown. Possible buttons are:
  • new - Create new form data.
  • edit - Opens and edit page for selected form data in a new window or tab. 
  • print - Opens a print view for selected form data in a new window or tab.
  • pdf - Opens a PDF for selected form data.
  • delete - Delete selected form data.

Detail page

Show Table of Contents

<property as="xs:integer" name="oxf.fr.detail.toc.*.*" value="0"/>

If the number of table of contents entries are greater than this value, then show the Table of Contents at the top of the form. Can be omitted or set to -1 to never show the TOC.

Position of Error Summary

<property as="xs:string" name="oxf.fr.detail.error-summary.*.*" value="bottom"/>

Where to place the error summary: top, bottom, both, or none.

Buttons on the detail page

<property as="xs:string"  name="oxf.fr.detail.buttons.*.*" value="close clear print pdf save submit"/>

The property configures which buttons are included on the detail page, and in what order they are shown. Possible buttons are:
  • refresh - Update the form (only makes sense in no-script mode).
  • close - Attempts to close the window. If the browser does not allow Form Runner to close the window, then close the form and loads the summary page in the current window. In most cases, this will:
    • If the detail page was opened from the summary page: close the browser window, and users will be able the view the summary window.
    • If the detail page was opened from a bookmark or similar: keep the current window open, and load the summary page in that window.
  • clear - Sets all the field values to their default value.
  • print - Opens a print view of the form in a new window or tab.
  • pdf - Open a PDF version of the form.
  • save - Saves changes to the form.
  • save-locally - Allows users to save the data in the current form as an HTML file on their local machine. When they open the HTML file, they will be taken to the "new form" page, but the form will be pre-filled with the data they had saved.
  • submit - Saves the form and shows a dialog. See: submit button.
  • workflow-review - Go to a read-only view page with the data filled-out.
  • workflow-send - Go to another page you provide, passing along the data filled out in this form to that other page. See: workflow send button.

Display hints inline

This property set whether the control hints are shown inline, rather than as tool-tips. The default is true.

<property as="xs:boolean" name="oxf.fr.detail.hints.inline.*.*" value="true"/>


PDF and barcode

The following property specifies whether a barcode must be included on PDF files.

<property as="xs:boolean" name="oxf.fr.detail.pdf.barcode.*.*" value="false"/>

Font embedding in PDF in "notemplate" mode

[SINCE: 2011-09-27]

These properties allow specifying fonts to embed in PDF files.

The oxf.fr.pdf.font.path property ends with an identifier for the font (here vera). It specifies the path to the font file.

Example:

<property as="xs:string" name="oxf.fr.pdf.font.path.vera" value="/path/to/DejaVuSans.ttf"/>

Optionally, the oxf.fr.pdf.font.family property ending with the same identifier (here vera) allows overriding the font family.

Example:

<property as="xs:string" name="oxf.fr.pdf.font.family.vera" value="Arial"/>


NOTE: This works only when the PDF is produced automatically. Support for PDF templates might be added at a later time.

Captcha

[SINCE 2011-06-30]

If you are creating a public form, you might want to add a captcha to avoid spam. You can do so by adding the following 3 properties to your properties-local.xml.

<property as="xs:boolean" name="oxf.fr.detail.captcha.*.*" value="true"/>
<property as="xs:string"  name="oxf.xforms.xbl.fr.recaptcha.public-key"  value="..."/>
<property as="xs:string"  name="oxf.xforms.xbl.fr.recaptcha.private-key" value="..."/>

Instead of stars (*) in the name of the first property, use specific app/form names for the captcha to only show on certain forms. The value of the last 2 properties correspond to your reCAPTCHA public and private keys which you can get by signing up for reCAPTCHA. With those properties in place, your forms will show a captcha as illustrated by the following screenshot.


[LIMITATION] The Form Runner captcha uses the reCAPTCHA XBL component, which doesn't support the noscript mode. Hence,  enabling this feature will have no effect in noscript mode.

Initial instance

When creating a new form (for instance going to the URL http://localhost:8080/orbeon/fr/orbeon/bookshelf/new), the initial form instance can come from 3 different places:
  1. The initial instance provided in the form can be used.
  2. The Base64-encoded XML documented POSTed to the "new form" URI can be used.
  3. A service can be called to get the initial instance.

Initial instance posted to the New Form page

The instance provided in the form is used by default. The POSTed XML document is used if there actually is an XML document being POSTed and if the following property is set to true:

<property as="xs:boolean" name="oxf.fr.detail.new.accept-post.*.*" value="false"/>

For security, this property is set to false by default; this prevents ill-intentioned users from forcing the form to start with an instance of their own creation. You need to enable this property if you are using including the save-locally button in your detail pages.

The document needs to be POSTed as the browser would when submitting an HTML form that looks like:

<form method="post" action="/path/to/new">
    <input type="hidden" name="fr-form-data" value="Base64-encoded XML"/>
</form>

The value of the fr-form-data request parameter is the Base64-encoded XML document.

Initial instance from service

With the following properties, you can configure Form Runner to call a service instead of using the default instance provided as part of the form:

<property as="xs:boolean" name="oxf.fr.detail.new.service.enable.*.*" value="false"/>
<property as="xs:string"  name="oxf.fr.detail.new.service.uri.*.*"   
                          value="/fr/service/custom/my-app/new"/>

Set the first property above to true to enable this behavior and have the second property point to your service.

The following property defines a space-separated list of request parameters to be passed to the service. Say the new page was invoke with request parameters foo=42 and bar=84, if you set the value of this property to foo bar, these two request parameters will be passed along as request parameters to the service. The request parameters can either get to the new page in a POST or GET request. The service is always called with a GET, consequently request parameters will be passed on the URI.

<property as="xs:string"
          name="oxf.fr.detail.new.service.passing-request-parameters.*.*"
          value=""/>

Enabling oxf.fr.detail.new.service.enable doesn't change the behavior with regard to POSTed instance: even if you are calling a service to get the initial instance, if oxf.fr.detail.new.accept-post.*.* is set to true, the POSTed instance will be used when a document is POSTed to the corresponding "new form" page.

View page

Buttons on the view page

You configure which buttons are shown on the view page with the following property:

<property as="xs:string"  name="oxf.fr.detail.buttons.view.*.*" value="back workflow-edit pdf"/>

You can use all the buttons available on the detail page. In addition, the following buttons
  • workflow-edit - Go back to edit mode.
  • workflow-send - Send the form (see properties below).

All pages

Buttons configuration

Submit Button

The submit button saves the data (like the save button) and then shows a configurable dialog. You can customize:
  • The message shown in the dialog, which can either be a static message informing users that the data has been submitted (the default), or a message returned by the persistence layer. In the later case, it is assumed that the persistence layer responds to a CRUD PUT operation with the HTML to display in the dialog. None of the persistence implementations that ship with Orbeon Forms do that, so this property is only relevant if you implement your own persistence layer. Otherwise, you will want to leave this property to its default value:
<property as="xs:boolean" name="oxf.fr.detail.submit.content-from-persistence.*.*"
                          value="false"/>
  • The buttons shows in the submit dialog, which can be:

    • clear - Sets all the fields to their default value and closes the dialog.
    • keep - Keeps the field values as they are and closes the dialog.
    • go - Go to a URL (see below for how the URL can be configured)
    • close-window - Closes the window. For this to work, JavaScript must be enabled, and the window in which the form is shown must have been opened by another page you created.
<property as="xs:string"  name="oxf.fr.detail.submit.buttons.*.*" value="go"/>
  • The go URI, if you have enabled the go button. When the "go" button is pressed, users will be taken to the URI specified by the following property. The value of the property is an XPath expression evaluated in the context of the form instance. This allows you both to have a "dynamic" URI (which depends on the initial data or data entered by users) or a "static" URI in the form of a URI between single quote in the XPath expression.
<property as="xs:string"  name="oxf.fr.detail.submit.go.uri-xpath.*.*"
                          value="/book/details/link"/>

Workflow send button

Use the workflow send button to save the data, and hand off the data entered by users to another page or web site. When users press the button:
  1. Data is saved through the persistence layer, as if users had pressed the save button.
  2. A PDF is generated if either one of the following properties is true: oxf.fr.detail.send.pdf, oxf.fr.email.attach-pdf, or oxf.fr.alfresco.send-pdf.
  3. Data is sent to Alfresco if the following property is true: oxf.fr.detail.send.alfresco. For more on this, see Alfresco integration.
  4. An email is sent if the following property is true: oxf.fr.detail.send.email. To configure how the email is sent, see: email settings.
  5. A success or error page is optionally loaded in the web browser.

[SINCE: 2011-01-24] The following properties configure the success and error pages:


<!-- URL to navigate to in case of success -->
<property as="xs:anyURI" name="oxf.fr.detail.send.success.uri.*.*"
          value="...success URL, blank if unused..."/>
<!-- HTTP method to use to navigate to the success page -->
<property as="xs:string" name="oxf.fr.detail.send.success.method.*.*" value="post"/>
<!-- URL to navigate to in case of error -->
<property as="xs:anyURI" name="oxf.fr.detail.send.error.uri.*.*"
          value="...error URL, blank if unused..."/>
<!-- HTTP method to use to navigate to the error page -->
<property as="xs:string" name="oxf.fr.detail.send.error.method.*.*" value="get"/>

NOTE: The success and error page URLs are literal URLs, not XPath expressions.

NOTE: If the compatibility oxf.fr.detail.send.uri property is set, it takes precedence over the newer oxf.fr.detail.send.success.uri.

When navigating to the success or error page, if the POST (the default) or PUT method is used, the document sent contains either:

  • If no PDF is generated: the XML document with the data entered by the user.
  • If a PDF is generated: a simple document which contains a URI to be used to retrieve the generated PDF. In that case, the document looks like:
<?xml version="1.0" encoding="UTF-8"?>
<url>/xforms-server/dynamic/567f14ee46c6b21640c1a5a7374d5ad8</url>

In both cases the POST or PUT is done from Orbeon Forms (not from the browser), so there is no risk here of the user even being able to access this data. For security reasons, if you setup Orbeon Forms to POST the XML document with the data entered by users to your service, then your page might want to check that the POST is coming from Orbeon Forms, to avoid the possibility of someone tampering with data and posting it to your page.

If the GET method is specified, no document is sent to the success or error page and the browser is simply issued a redirection.

[SINCE: 2011-05-26]

By default, non-visible (non-relevant) controls and sections are pruned (removed) from the data when it is sent to the success page.

This behavior can be changed by setting the following property to false:

<property as="xs:boolean" name="oxf.fr.detail.send.success.prune.*.*" value="false"/>

Show Orbeon Forms version

<property as="xs:boolean" name="oxf.fr.version.*.*" value="true"/>

Whether to show the Orbeon Forms version at the bottom.

Default logo

<property as="xs:anyURI" name="oxf.fr.default-logo.uri.*.*"
                         value="/apps/fr/style/orbeon-logo-trimmed-transparent-42.png"/>

With this property, you can set the default logo URI. This logo appears on the summary and detail pages for a given form if no form-specific logo was uploaded in Form Builder. You can omit (or comment out) this property or set its value to "" (empty string) if you don't want a default logo at all.

Default CSS

<property as="xs:string"  name="oxf.fr.css.uri.*.*"
  value="/ops/yui/reset-fonts-grids/reset-fonts-grids.css
         /ops/yui/datatable/assets/skins/sam/datatable.css
         /apps/fr/style/form-runner-base.css
         /apps/fr/style/form-runner-html.css
         /apps/fr/style/form-runner-orbeon.css"/>

With this property, you can set the CSS stylesheets to be used, as a space-separated list of URIs. The Form Runner CSS stylesheet is split into 4 parts:
  1. YUI base CSS: /ops/css/yui/reset-fonts-grids.css
  2. Base layout: /apps/fr/style/form-runner-base.css
  3. Global rules: /apps/fr/style/form-runner-html.css [SINCE: 2011-05-18]
  4. Presentational aspects (colors, fonts, ...): /apps/fr/style/form-runner-orbeon.css
You can set this to another value, or to the empty string, using this property. This allows customizing presentational aspects globally, per application, or per form. Typically, you'll want to keep the first 2 stylesheets (reset-fonts-grids.css and form-runner-base.css), and either:
  • Replace form-runner-orbeon.css by your own stylesheet. You would typically do this if you want to adopt a presentation which is significantly different than the default style.
  • Add your own CSS file, in addition to the 3 CSS files mentioned earlier. You would typically do this if you want to only override a few of the rules defined in form-runner-orbeon.css.
The global rules can be removed in a portlet environment.

Overriding resources

In some cases, it might make sense to change some of the resources provided out of the box by Form Runner. For instance, the detail page can have a submit button, which in English has a label "Submit". For your application, another label might make more sense, for instance "Send". To override Form Runner resources, you define properties with a name that has the following structure:
  1. The name start with oxf.fr.resource.
  2. Followed by the name of the application and form name for which you want to redefine the resource. You can use * for either if you want the redefinition to apply to all the applications or all the forms. For instance: *.*, or my-app.my-form.
  3. The 2-letter code for the language for which you want to override the resource. For instance: en.
  4. A dot-separated path corresponding to the path of the resource you want to override as defined by Form Runner resources.xml.
  5. Resources are aggressively caches, so you need to restart your application server (or redeploy the web app) after changing a property that overrides resources.
For instance, to change the label of the submit button to be "Send" in English for all applications and forms, write:

<property as="xs:string"  name="oxf.fr.resource.*.*.en.detail.labels.submit-document"
                          value="Send"/>

Email settings

These properties control email sending in Form Runner:

<property as="xs:string"  name="oxf.fr.email.smtp.host.*.*"
                          value="my.outgoing.smtp.server.org"/>
<property as="xs:string"  name="oxf.fr.email.smtp.username.*.*"    value="jdoe"/>
<property as="xs:string"  name="oxf.fr.email.smtp.credentials.*.*" value="secret"/>
<property as="xs:string"  name="oxf.fr.email.from.*.*"             value="john@example.org"/>
<property as="xs:string"  name="oxf.fr.email.to.*.*"
                          value="mary@example.org,nancy@example.org"/>
<property as="xs:boolean" name="oxf.fr.email.attach-pdf.*.*"       value="true"/>
<property as="xs:boolean" name="oxf.fr.email.attach-xml.*.*"       value="true"/>

  • The host, username and credentials properties control the connection to the SMTP server.
  • The from property specifies the sender email address(es) appearing in the email sent.
  • The to property specifies the recipient email address(es) of the email sent.
  • The attach-pdf and attach-xml properties control whether PDF and/or XML versions of the form data are attached to the email.

Oracle settings

For the Oracle persistence configuration, see Oracle Persistence Layer.

Noscript and Ajax modes

Show Noscript link

<property as="xs:boolean" name="oxf.fr.noscript-link.*.*" value="true"/>

Whether to show the link to the noscript/full version. 

Noscript: use table layout

<property as="xs:boolean" name="oxf.fr.detail.noscript.table.*.*" value="true"/>

Whether forms in noscript mode are allowed to use a layout based on tables. If false, no tables are used. WYSIWYG is lost, but the form may be more accessible. Default is true.

Noscript: allow sections to collapse

<property as="xs:boolean" name="oxf.fr.detail.noscript.section.collapse.*.*" value="true"/>

Whether sections in noscript mode are allowed to collapse. A value of false may make sections more accessible and less confusing to screen reader users. Default is true.

Ajax mode: allow sections to collapse

<property as="xs:boolean" name="oxf.fr.detail.ajax.section.collapse.*.*" value="true"/>

Whether sections in Ajax mode are allowed to collapse. Default is true.

Ajax mode: allow sections to animate

<property as="xs:boolean" name="oxf.fr.detail.ajax.section.animate.*.*" value="true"/>

Whether sections in Ajax mode are allowed to open and close with an animation. Default is true. A value of false is more efficient with slow browsers / large forms.

Sign in  |  Recent Site Activity  |  Revision History  |  Terms  |  Report Abuse  |  Print page  |  Powered by Google Sites