# Form Runner

## Children pages

* [Detail page](https://doc.orbeon.com/configuration/properties/form-runner/form-runner-detail-page)
  * [Attachments](https://doc.orbeon.com/configuration/properties/form-runner/form-runner-detail-page/form-runner-attachments)
  * [Email](https://doc.orbeon.com/configuration/properties/form-runner/form-runner-detail-page/form-runner-email)
  * [PDF](https://doc.orbeon.com/configuration/properties/form-runner/form-runner-detail-page/form-runner-pdf)
* [Persistence](https://doc.orbeon.com/configuration/properties/form-runner/persistence)
* [Summary page](https://doc.orbeon.com/configuration/properties/form-runner/form-runner-summary-page)

## Default values

For the latest default values of Form Runner properties, see [properties-form-runner.xml](https://github.com/orbeon/orbeon-forms/blob/master/src/main/resources/config/properties-form-runner.xml).

## Form Runner properties documented elsewhere

* [Custom dialogs and model Logic](https://doc.orbeon.com/form-runner/advanced/custom)
  * `oxf.fr.detail.model.custom`
  * `oxf.fr.detail.dialogs.custom`
* [Wizard View](https://doc.orbeon.com/form-runner/component/wizard)
  * `oxf.fr.detail.view.appearance`
  * `oxf.fr.detail.buttons.inner`
  * `oxf.xforms.xbl.fr.wizard.validate`
  * `oxf.xforms.xbl.fr.wizard.separate-toc`
  * `oxf.xforms.xbl.fr.wizard.section-status`
  * `oxf.xforms.xbl.fr.wizard.subsections-nav`
  * `oxf.xforms.xbl.fr.wizard.subsections-toc`
* [Autosave](https://doc.orbeon.com/form-runner/persistence/autosave)
  * `oxf.fr.detail.autosave-delay`
  * `oxf.fr.persistence.*.autosave`
* [Simple data migration](https://doc.orbeon.com/form-runner/features/simple-data-migration)
  * `oxf.fr.detail.data-migration`
* [Configuration Properties \~ Persistence](https://doc.orbeon.com/configuration/properties/form-runner/persistence)
  * `oxf.fr.persistence.provider`
  * `oxf.fr.persistence.[provider].uri`
  * `oxf.fr.persistence.[provider].active`
  * `oxf.fr.persistence.[provider].autosave`
  * `oxf.fr.persistence.[provider].permissions`
  * `oxf.fr.persistence.[provider].versioning`
  * `oxf.fr.persistence.[provider].data-format-version`
* [Form Runner Access Control](https://doc.orbeon.com/form-runner/access-control)
  * `oxf.fr.support-owner-group`
  * `oxf.fr.authentication.method`
  * `oxf.fr.authentication.container.roles`
  * `oxf.fr.authentication.container.roles.split`
  * `oxf.fr.authentication.header.username`
  * `oxf.fr.authentication.header.group`
  * `oxf.fr.authentication.header.roles`
  * `oxf.fr.authentication.header.roles.split`
  * `oxf.fr.authentication.header.roles.property-name`
  * `oxf.fr.authentication.header.sticky`
* [Form Runner Published Forms page](https://doc.orbeon.com/form-runner/form-runner-pages/published-forms-page)
  * `oxf.fr.home.page-size`
  * `oxf.fr.home.table.link-to`
* [TIFF Production](https://doc.orbeon.com/form-runner/features/tiff-production)
  * `oxf.fr.detail.tiff.compression.type`
  * `oxf.fr.detail.tiff.compression.quality`
  * `oxf.fr.detail.tiff.scale`
  * `oxf.fr.detail.tiff.filename`

## Language

### Default language

The following property determines Form Runner's default language:

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

When wildcards are specified, this property can control the default language for a given app or form.

The property without wildcards can also be used to control the default language of pages which don't involve a specific form, such as the Form Runner Home page

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

For more details, see [Language selection at runtime](https://doc.orbeon.com/form-runner/features/localization#language-selection-at-runtime)

### Available languages

For a given form, you can filter which languages are available in the language selector with a space-separated list of language codes:

```xml
<property
  as="xs:string"
  name="oxf.fr.available-languages.*.*"
  value="en fr"/>
```

The language selector by default shows all languages available in the form definition. When this property is specified, only the intersection of the languages is shown in the selector. For example:

* Example 1
  * form languages: `en fr jp`
  * property: `en fr`
  * resulting languages: `en fr`
* Example 2
  * form languages: `en fr jp`
  * property: `en jp kr`
  * resulting languages: `en jp`

If the property is blank or contains the wildcard `*`, all the form languages are available.

\[SINCE Orbeon Forms 4.3]

For pages which don't involve a specific form, such as the Form Runner Home page, the following property controls the available languages:

```xml
<property
  as="xs:string"
  name="oxf.fr.available-languages"
  value="en fr"/>
```

For more details, see [Language selection at runtime](https://doc.orbeon.com/form-runner/features/localization#language-selection-at-runtime)

## Timezone

\[SINCE Orbeon Forms 2021.1]

The Summary and Home pages display timestamps showing the created and last modified dates of forms and data.

You can configure an explicit timezone to display these timestamps:

```xml
<property
      as="xs:string"
      name="oxf.fr.default-timezone"
      value="America/Los_Angeles"/>
```

```xml
<property
      as="xs:string"
      name="oxf.fr.default-timezone"
      value="Asia/Kolkata"/>
```

If the property is blank (the default), the Java environment's default timezone is used.

\[UNTIL Orbeon Forms 2020.1]

The Java environment's default timezone is used.

## Remote servers

\[SINCE Orbeon Forms 4.7]

The `oxf.fr.home.remote-servers` property allows you to configure one or more remote Orbeon Forms servers for pushing and pulling form definitions. This property is used by:

* The [Forms Admin page](https://doc.orbeon.com/form-runner/form-runner-pages/forms-admin-page) to display remote server options in the UI
* The [Remote server APIs](https://doc.orbeon.com/form-runner/api/other-apis/remote) to programmatically push to or pull from remote servers

### Configuration format

The property value is a JSON array containing one or more server configuration objects:

```xml
<property as="xs:string" name="oxf.fr.home.remote-servers">
  [
    {
      "name"      : "prod",
      "label"     : "Production",
      "url"       : "https://prod.example.com/orbeon",
      "ui-access" : true,
      "api-access": true
    },
    {
      "name"      : "staging",
      "label"     : "Staging",
      "url"       : "https://staging.example.com/orbeon",
      "ui-access" : true,
      "api-access": false
    }
  ]
</property>
```

### Configuration fields

Each remote server object supports the following fields:

* `name` (optional): \[SINCE Orbeon Forms 2025.1] A unique identifier for the remote server, used by the API. If not specified, the server can only be accessed through the UI.
* `label` (required): A human-readable label displayed in the Forms Admin page UI.
* `url` (required): The base URL of the remote Orbeon Forms instance (without trailing slash)
* `ui-access` (optional): \[SINCE Orbeon Forms 2025.1] Whether the server is accessible from the Forms Admin page UI. Defaults to `true`.
* `api-access` (optional): \[SINCE Orbeon Forms 2025.1] Whether the server is accessible via the Remote server APIs. Defaults to `false`.

### Authentication on the remote server

Services on the remote server must be protected with Basic authentication. If the remote server needs to be accessible both by users through another form of authentication and services through Basic authentication, then this is typically configured using an [authorization service](https://doc.orbeon.com/xml-platform/controller/authorization-of-pages-and-services#authorization-service).

### Backward compatibility

\[SINCE Orbeon Forms 4.4]

\[UNTIL Orbeon Forms 4.6]

Use the `oxf.fr.production-server-uri` property:

```xml
<property
  as="xs:anyURI"
  name="oxf.fr.production-server-uri"
  value="http://remote.server:8080/orbeon/"/>
```

\[SINCE Orbeon Forms 4.7]

If the `oxf.fr.production-server-uri` property is set and not empty, it takes precedence over the `oxf.fr.home.remote-servers` property for backward compatibility.

## Summary page

See [Summary page configuration properties](https://doc.orbeon.com/configuration/properties/form-runner/form-runner-summary-page).

## Detail page

See [Detail page configuration properties](https://doc.orbeon.com/configuration/properties/form-runner/form-runner-detail-page).

## Show Orbeon Forms version

\[UNTIL Orbeon Forms 4.6, use `oxf.show-version` starting Orbeon Forms 4.6.1]

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

Whether to show the Orbeon Forms version at the bottom.

## Default logo

With this property, you can set the default logo URI. This logo appears on the Summary, Detail and Home pages for a given form. You can omit (or comment out) this property or set its value to the empty string if you don't want a default logo at all.

\[SINCE Orbeon Forms 2024.1.1] When the URI ends with `.svg`, Orbeon Forms generates markup that implements a fallback strategy - it first attempts to load the SVG version, then automatically falls back to a PNG version (using the same path but with `.png` extension) if SVG is not supported by the renderer. In practice, this means browsers will display the SVG version, while PDF generation will use the PNG version.

```xml
<property as="xs:anyURI"  name="oxf.fr.default-logo.uri.*.*">
    /apps/fr/style/orbeon-logo.svg
</property>
```

If you use two `*` wildcards, as in the example above, the property also sets the logo on the [Published Forms page](https://doc.orbeon.com/form-runner/form-runner-pages/published-forms-page) and the [Forms Admin page](https://doc.orbeon.com/form-runner/form-runner-pages/forms-admin-page)

1. Place your logo file(s) under one of the following recommended locations:
   * `WEB-INF/resources/forms/assets`: logo for all forms
   * `WEB-INF/resources/forms/APP/assets`: logo for app name APP
   * `WEB-INF/resources/forms/APP/FORM/assets`: logo for app name APP and form name FORM
2. Define the `oxf.fr.default-logo.uri.*.*` property to point to the file(s) you added. The path points to location under the `WEB-INF/resources` directory.

For example, to change the default logo for all forms and pages to an image called `my-logo.png`, place the image at the proper location and use the following property:

```xml
<property as="xs:anyURI"  name="oxf.fr.default-logo.uri.*.*">
    /forms/assets/my-logo.png
</property>
```

NOTE: Since Orbeon Forms 4.0, this property doesn't have an impact on the Form Builder logo. To override the Form Builder logo, you can use custom CSS (see the [`oxf.fr.css.custom.uri`](https://github.com/orbeon/orbeon-forms-doc/blob/master/form-runner/styling/css/README.md#adding-your-own-css-files) configuration).

## Adding your own CSS

See the [CSS page](https://doc.orbeon.com/form-runner/styling/css).

## Adding your own JavaScript

\[SINCE Orbeon Forms 4.4]

1. Place your JavaScript file(s) under one of the following recommended locations:
   * `WEB-INF/resources/forms/assets`: scripts for all forms
   * `WEB-INF/resources/forms/APP/assets`: scripts for app name APP
   * `WEB-INF/resources/forms/APP/FORM/assets`: scripts for app name APP and form name FORM
2. Define the [`oxf.fr.js.custom.uri`](#adding-your-own-adding-your-own-javascript-files) property to point to the file(s) you added. The path points to location under the `WEB-INF/resources` directory.

```xml
<property as="xs:string" name="oxf.fr.js.custom.uri.*.*">
    /forms/acme/assets/acme.js
    /forms/acme/sales/assets/acme-sales.js
</property>
```

You can add more than one file, and just separate the paths by whitespace in the property.

\[SINCE Orbeon Forms 2017.1]

In addition to [`oxf.fr.js.custom.uri`](#adding-your-own-adding-your-own-javascript-files), you can also use the following properties, which apply only to the Summary and Detail pages respectively:

* [`oxf.fr.summary.js.custom.uri`](https://doc.orbeon.com/configuration/properties/form-runner-summary-page#adding-your-own-javascript-files)
* [`oxf.fr.detail.js.custom.uri`](https://doc.orbeon.com/configuration/properties/form-runner-detail-page#adding-your-own-javascript-files)

## 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`](https://github.com/orbeon/orbeon-forms/blob/master/form-runner/jvm/src/main/resources/apps/fr/i18n/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:

```xml
<property
    as="xs:string"
    name="oxf.fr.resource.*.*.en.detail.buttons.send"
    value='&lt;i class="icon-arrow-right"/&gt; Send'/>
```

This also works for resources that don't exist yet. For your own resources, start with a prefix specific to your company or project. For example:

```xml
<property
  as="xs:string"
  name="oxf.fr.resource.*.*.en.acme.my-resource-1"
  value="Resource 1 in English"/>

<property
  as="xs:string"
  name="oxf.fr.resource.*.*.fr.acme.my-resource-1"
  value="Resource 1 en français"/>
```

*NOTE: You can add new resources as shown above, but you cannot create new languages.*

### Date and time formats

Form Runner uses 3 date/time format resources to display dates and times throughout its user interface, including the Summary page, Home page, and form/data cards. The format used depends on how far in the past the date is:

* `within-day` - for dates within the last 24 hours
* `day-this-year` - for dates earlier this year
* `short-date` - for dates in previous years

The example below shows how to override all 3 formats to use an ISO-8601 style format `[Y0001]-[M01]-[D01] [H01]:[m01]:[s01]` for the English language (`en`). These formats are used for displaying Created and Last Modified timestamps in the Summary page, Last Modified timestamps in the Home page, and date information in the Published Forms and Form Data cards.

```xml
<property
    as="xs:string"
    name="oxf.fr.resource.*.*.en.common.formats.within-day"
    value="[Y0001]-[M01]-[D01] [H01]:[m01]:[s01]"/>
<property
    as="xs:string"
    name="oxf.fr.resource.*.*.en.common.formats.day-this-year"
    value="[Y0001]-[M01]-[D01] [H01]:[m01]:[s01]"/>
<property
    as="xs:string"
    name="oxf.fr.resource.*.*.en.common.formats.short-date"
    value="[Y0001]-[M01]-[D01] [H01]:[m01]:[s01]"/>
```

After setting these properties, make sure to restart your application server, as resources are aggressively cached for performance reasons.

## Email settings

See [Email](https://doc.orbeon.com/configuration/properties/form-runner/form-runner-detail-page/form-runner-email).

## Sections and grids

### Appearance of repeated sections

\[SINCE Orbeon Forms 2016.1]

The following property allows you to set the appearance of repeated sections to `full` (the default) or `minimal` for all forms or for a subset of forms:

```xml
<property
    as="xs:string"
    name="oxf.xforms.xbl.fr.section.appearance.*.*"
    value="minimal"/>
```

See also the [`appearance`](https://doc.orbeon.com/form-runner/component/section#repeated-mode) attribute of the [section component](https://doc.orbeon.com/form-runner/component/section).

### Appearance of repeated grids

\[SINCE Orbeon Forms 2016.1]

The following property allows you to set the appearance of repeated grids to `full` (the default) or `minimal` for all forms or for a subset of forms:

```xml
<property
    as="xs:string"
    name="oxf.xforms.xbl.fr.grid.appearance.*.*"
    value="minimal"/>
```

See also the [`appearance`](https://doc.orbeon.com/form-runner/component/grid#repeated-mode) attribute of the [grid component](https://doc.orbeon.com/form-runner/component/grid).

### Insert position of repeated sections

\[SINCE Orbeon Forms 2016.2]

The following property allows you to select where new repetitions are added when using the "Add Another" or "+" button. Allowed values are `index` (default for the `full` appearance) and `bottom` (default for the `minimal` appearance):

```xml
<property
    as="xs:string"
    name="oxf.xforms.xbl.fr.section.insert.*.*"
    value="index"/>
```

See also the [`insert`](https://doc.orbeon.com/form-runner/component/section#repeated-mode) attribute of the [section component](https://doc.orbeon.com/form-runner/component/section).

### Insert position of repeated grids

\[SINCE Orbeon Forms 2016.2]

The following property allows you to select where new repetitions are added when using the "Add Another" or "+" button. Allowed values are `index` (default for the `full` appearance) and `bottom` (default for the `minimal` appearance):

```xml
<property
    as="xs:string"
    name="oxf.xforms.xbl.fr.grid.insert.*.*"
    value="index"/>
```

See also the [`insert`](https://doc.orbeon.com/form-runner/component/grid#repeated-mode) attribute of the [grid component](https://doc.orbeon.com/form-runner/component/grid).

### Section collapsing

\[SINCE Orbeon Forms 2016.1]

The following property allows you to set whether a section content can be collapsed by clicking on its title for all forms or for a subset of forms:

```xml
<property
    as="xs:boolean"
    name="oxf.xforms.xbl.fr.section.collapsible.*.*"
    value="false"/>
```

By default, sections are allowed to collapse.

The following property controls the same behavior in noscript mode:

\[UNTIL Orbeon Forms 2018.1]

```xml
<property
    as="xs:boolean"
    name="oxf.xforms.xbl.fr.section.noscript.collapsible.*.*"
    value="false"/>
```

A value of `false` may make sections more accessible and less confusing to screen reader users.

The following property controls the whether collapsing/opening of sections uses an animation. The default is `true`:

```xml
<property
    as="xs:boolean"
    name="oxf.xforms.xbl.fr.section.animate.*.*"
    value="false"/>
```

A value of `false` can be more efficient with slower browsers or large forms.

### Grid markup

#### Current behavior (Orbeon Forms 2022.1 and later)

By default, grids in your forms are rendered using the modern [CSS grid layout](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout) with `div` elements. This provides better compatibility with modern browsers and improved layout capabilities. If your custom CSS relies on the older HTML table-based structure (with `table`, `tr`, and `td` elements), you can revert to the previous behavior by setting the following property:

```xml
<property
    as="xs:string"
    name="oxf.xforms.xbl.fr.grid.markup.*.*"
    value="html-table"/>
```

#### Older versions (before Orbeon Forms 2022.1)

Before Orbeon Forms 2022.1, grids were rendered using HTML tables by default. This was because older browsers, in particular IE11, provided only limited support for CSS grids. Starting with Orbeon Forms 2020.1.7 and 2021.1.1, anticipating the drop of IE11 support, you could opt-in to use CSS grid layout by setting the following property. For more details on grid rendering in different versions, see the [Grids CSS documentation](https://doc.orbeon.com/form-runner/styling/grids).

```xml
<property
    as="xs:string"
    name="oxf.xforms.xbl.fr.grid.markup.*.*"
    value="css-grid"/>
```

### Deprecated properties

Before Orbeon Forms 2016.1, you could use the following properties, deprecated since Orbeon Forms 2016.1. Section collapsing:

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

Section collapsing in noscript mode:

\[UNTIL Orbeon Forms 2018.1]

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

Section collapsing animation:

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

## Noscript properties

\[DEPRECATED SINCE Orbeon Forms 2016.3]

\[UNTIL Orbeon Forms 2018.1]

### Show noscript link

```xml
<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

```xml
<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. The default is `true`.