CSS

Rationale

Form Runner has a built-in theme for forms. This page documents how you can change that default.

CSS stands for Cascading Style Sheets, and is the standard technology to add style to web pages and web applications. Orbeon Forms supports custom CSS files which allows you to change your forms' appearance. This assumes that you have some CSS knowledge.

Adding your own CSS files

  1. Place your CSS file(s) under one of the following recommended locations:

    • WEB-INF/resources/forms/assets: CSS for all forms

    • WEB-INF/resources/forms/APP/assets: CSS for app name APP

    • WEB-INF/resources/forms/APP/FORM/assets: CSS for app name APP and form name FORM

  2. Define the oxf.fr.css.custom.uri property to point to the file(s) you added. The path points to location under the WEB-INF/resources directory.

<property as="xs:string" name="oxf.fr.css.custom.uri.*.*">
/forms/acme/assets/acme.css
</property>

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

Note that the locations suggested are just about how to organize the files for clarity. In addition, if some CSS files apply to specific app or form names, you must specify the app and form name in the property or properties. For example:

<property as="xs:string" name="oxf.fr.css.custom.uri.APP.*">
/forms/APP/assets/my-app.css
</property>
<property as="xs:string" name="oxf.fr.css.custom.uri.APP.FORM">
/forms/APP/assets/my-app.css
/forms/APP/FORM/assets/my-app-and-form.css
</property>

The names APP, FORM, my-app.css and my-app-and-form.css are just placeholders for your own app name, form name, and CSS files names.

If a specific property is defined for an app/form, such as oxf.fr.css.custom.uri.APP.FORM, only that property is considered and other properties defined only for a given app but without a specific form, such as oxf.fr.css.custom.uri.APP.*, will be ignored. This means that you must repeat references to CSS resources in the more specific property if desired. For example above /forms/APP/assets/my-app.css is repeated.

[SINCE Orbeon Forms 2017.1]

In addition to oxf.fr.css.custom.uri, you can also use the following properties, which apply only to the Summary and Detail pages respectively:

Authoring CSS

  1. Disable the minimal and combined resources. When working on your CSS, you might want to temporarily set the following properties in your properties-local.xml, which will disable the combined and minimized resources, so the files and line numbers you see in your browser correspond to what you have on disk.

    <property
    as="xs:boolean"
    name="oxf.xforms.minimal-resources"
    value="false"/>
    <property
    as="xs:boolean"
    name="oxf.xforms.combine-resources"
    value="false"/>

    Note that with the Form Runner Liferay Proxy Portlet, you cannot disable combined resources as URL rewriting does not work in that case.

  2. Know which class names to use in your CSS selectors. We strongly recommend you use the Chrome Dev Tools to check which classes are generated by Orbeon Forms. Look specifically for classes that start with fr-. Once you have your CSS working with Chrome and/or Firefox, it is likely that the CSS will work with other modern browsers.

Use case

Sample CSS

Description

Change the width of a column

.fr-grid-invoice .fr-grid-col-1 { width: 40px }

1. In Form Builder, you can name grids (for now [only repeated grids can be named][18]). When doing so, the table element corresponding to your grid gets a fr-grid-my-name class, where my-name is the name you choose for the grid. In the example, the name was invoice. 2. Each column gets a class fr-grid-col-1, fr-grid-col-2 and so on, starting with the number 1.

Styling specific controls

You style specific controls in your form, say to set the width of an input field, by adding a CSS class on that control. To do so:

  1. Edit the source code for the form (in Form Builder, from the left sidebar, under Advanced, click on Edit Source).

  2. Locate the XForms control you need to modify (for instance <xf:input> for an input field).

  3. If not present, add a class attribute (for instance: <xf:input class="" ...="">).

  4. Add the space-separated class or classes in the class attribute (for instance: <xf:input class="my-class" ...>).

The CSS class you use can either be one you define, or one of the following built-in classes:

  • fr-width-2em: sets the field with to 2 em

  • fr-width-3em: sets the field with to 3 em

  • fr-width-5em: sets the field with to 5 em

  • fr-width-7em: sets the field with to 7 em

  • fr-width-10em: sets the field with to 10 em

  • fr-width-15em: sets the field with to 15 em

NOTE: Since Orbeon Forms 2018.1, it is no longer recommended to use those CSS classes. Instead, vary the width of the 12-column grid cell in Form Builder to the desired size.

If you define your own CSS class, then write a CSS rule for that class. Make sure to use a strong selector, so its precedence is higher than CSS provide by Orbeon Forms, e.g. something like:

#fr-view .fr-grid .fr-grid-content .my-class input.xforms-input-input {
...rule...
}

When doing CSS work, make sure to use a tool like the Chrome Dev Tools (or other browsers' similar tools) that shows what CSS rules apply to an element. This will be your best friend for CSS development (in general, not only for Orbeon Forms!).

Changing the page width

The default width with Bootstrap is 940px, but you can change this by overriding the Bootstrap/Orbeon CSS. As usual, to do so, we recommend you use a tool like the Chrome DevTools to find the exact rules you need to override in your environment. For instance, with an out-of-the-box Orbeon Forms deployed as a servlet, you can set the width to 720px with:

.orbeon .container, .orbeon .span12 { width: 720px }

Other considerations

Separate vs. inline CSS

You can either:

  1. Store your CSS is a separate CSS file, which you either provide in addition or that overrides the default CSS provided by Orbeon Forms. For more on this, see the oxf.fr.css.custom.uri configuration property. This is the recommended technique if your CSS is intended to be shared by several forms.

  2. Put your CSS inline, in the form. Uf your CSS is quite short, and specific to a given form (not to be shared amongst forms), this is a possibility. For this, put the rules within your own <style> section of the form:

    <xh:title>My Form Title</xh:title>
    <xh:style type="text/css">
    #fr-view .fr-grid .fr-grid-content .my-class input.xforms-input-input {
    width: 8em
    }
    </xh:style>

NOTE: Since 2018.1, it is no longer recommended to place any inline CSS, as some servers use the Content-Security-Policy header to disable inline scripts and CSS. Orbeon Forms 2018.1 doesn't include any inline scripts and CSS anymore by default.

Strength of CSS rules

Bootstrap, XForms engine, Form Runner and Form Builder CSS rules are contained within an enclosing .orbeon CSS class. This ensures that the Orbeon CSS rules only apply within an element with that class. It also makes Orbeon CSS rules a bit stronger (more specific) than before. You might have to update your custom CSS to take this into account.

See here for more on CSS specificity.

Twitter Bootstrap

Since Orbeon Forms 4.0, Form Runner uses Twitter Bootstrap for some aspects of its layout and styling.

NOTE: If you have custom CSS which works with Orbeon Forms 3.9, it is likely that you will have to update it to work with Orbeon Forms 4.0.

Configuring the presentation of automatic PDF output

See Automatic PDF.

See also