JavaScript and CSS assets
Last updated
Last updated
Most JavaScript and CSS assets used by the XForms engine are available in two versions:
A full version, which may contain comments, spaces, longer identifiers, etc.
A minimal version, which is usually much smaller
Both versions work exactly the same. For development and debugging of the XForms engine itself, the full version is easier to work with. But if you never work directly with these JavaScript and CSS files, as well as for deployment, the minimal versions are recommended as they will load faster in the user's web browser.
You enable minimal resources in properties-local.xml as follows:
Default:
prod mode: true
dev mode: false
Starting with Orbeon Forms 2020.1, disabling combined resources is deprecated. Disabling combined resources already doesn't work when embedding forms, whether with the , the , or the , and future versions of Orbeon Forms are likely to completely drop the support for non-combined resources.
Serving external CSS and JavaScript assets can have a high performance cost on page loads. This is particularly important with the intensive use of JavaScript in Orbeon Forms. In particular, it can be shown that serving many small files is slower than serving a single large file.
This is why Orbeon Forms supports the option of combining the multiple JavaScript and CSS files required for a given XForms page into one or two JavaScript files and one or two CSS file.
NOTE: In theory, HTTP pipelining can improve very much on this, but this is (very unfortunately) useless in practice at the time of writing because browsers do not implement it or do not enable it by default. HTTP/2 might help solve this.
There are 3 categories of asset resources:
built-in XForms engine resources, like xforms.js
XBL components resources, like grid.js
user resources (placed in the <head> element
Resources are split into 2 groups:
baseline resources, which include
main built-in XForms engine resources
XBL resources for components specified with the oxf.xforms.resources.baseline property
other resources, which include
other built-in XForms engine resources, such as for the Formatted Text / Rich Text Editor or tree selection
XBL resources not part of the baseline
user resources
The idea is that this way, in an application with multiple pages:
a large baseline of resources is loaded and cached once and for all
a smaller incremental set of extra resources is loaded for each individual page
If all the resources belong to the baseline, only one JavaScript and one CSS files are produced. Otherwise, two JavaScript and two CSS files are produced.
The URLs produced identify the resources needed by the page, for example:
When the Orbeon Forms XForms server receives a request for a combined resource, it determine what files need to be combined and outputs them all together. Furthermore, for CSS files, all URLs referred to with url() are rewritten, so that links to images, in particular, remain correct.
Some CSS and JavaScript files are never included into aggregated resources:
resources with f:url-norewrite="true": <xh:link rel="stylesheet" href="/style.css" f:url-norewrite="true"/>`
resources with an absolute URL, such as:
<xh:link rel="stylesheet" href="http://example.org/style.css"/>
CSS resources with a media attribute that is present but different from "all":
<xh:link rel="stylesheet" href="/style.css" media="print"/>
You enable this feature in properties-local.xml as follows:
When this is enabled, Orbeon Forms combines JS and CSS resources.
Default:
prod mode: true
dev mode: false
[SINCE Orbeon Forms 2017.1]
NOTE: These properties are mainly intended for internal use. Proceed with caution.
The default baseline of XForms assets is configured with the oxf.xforms.assets.baseline property. Here is an example:
Minimal versions:
are enabled when "min" is set to true and
assume that an asset named file.min.css is the minimal version for file.css.
[SINCE Orbeon Forms 2021.1]
The "xbl" key allows specifying a JSON array of XBL components, indicated by direct name (QName), whose assets must also be included.
This capability renders the oxf.xforms.resources.baseline property deprecated.
[DEPRECATED SINCE Orbeon Forms 2019.2]
The oxf.xforms.assets.baseline.excludes property can be used to exclude assets.
It doesn't make much sense to use this property in a properties file. Instead, it should be used via an attribute on xf:model.
This property is deprecated. Use oxf.xforms.assets.baseline.updates instead.
[SINCE Orbeon Forms 2019.2]
The oxf.xforms.assets.baseline.updates property can be used to exclude and add assets.
It doesn't make much sense to use this property in a properties file. Instead, it should be used via an attribute on xf:model.
Each asset must be prefixed with a + or a - to indicate whether the asset as removed from or added to the baseline.
[DEPRECATED SINCE Orbeon Forms 2021.1]
The baseline of resources is configured as follows:
The value consists of a list of qualified names referring to XBL components. Resources for the components specified are always included in every page, whether the component is used by the page or not.
Starting Orbeon Forms 2021.1, use oxf.xforms.assets.baseline instead.
[UNTIL Orbeon Forms 2019.1]
In addition, you can enable caching on disk of combined resources with:
This cache works differently from other Orbeon Forms caches, as the result is stored in the resources, typically under:
One benefit of this mechanism is that it allows making such combined files to be served by an Apache front-end.
NOTE: This property is removed with Orbeon Forms 2019.2. HTTP reverse proxies can cache resources without having access to a file on disk, which makes this feature obsolete.
This feature is enabled by default in Orbeon Forms PE.
To further improve caching efficiency, Orbeon Forms supports enabling versioned resources. Usually, a resource such as a CSS, JavaScript or image file, is served through URLs like this one:
When configuring caching on the server, for example by using an Apache front-end, you may face a dilemma:
Caching aggressively (with an expiration date far in the future and no revalidation) so that the client asks for the resource as rarely as possible. Doing so may cause resources on the client to be out of date.
Caching for a shorter period of time or by forcing revalidation so that your client always has a fresh version of the resources. Doing so may cause longer page loads and more load on the server.
Orbeon Forms solves this by providing the option of using versioned resources, that is inserting automatically a version number within resource URLs.
You enable versioned resources in properties-local.xml:
With Orbeon Forms PE, versioned resources are enabled by default in prod mode.
You can configure an optional application version number for your own resources:
Note that if this property is commented out or missing, no versioning takes place for your application resources even if oxf.resources.versioned is set to true.
The Orbeon Forms version number is not exposed by default to users in the prod run mode. You can change this by setting the following property to false:
When this is set to true, the version number is HMAC-encoded with the configured password. This means the version number is stable, but cannot be guessed.
With versioned resources enabled, resources are served with URLs as follows:
The XForms Server component, which serves the resource in this case, sets an expiration date far in the future. For example, this is the description of the cache entry in the Firefox about:cache page:
This means that the resource can effectively be cached "for ever" by a client. In case the client visits Orbeon Forms pages often, the resources will be available from cache, therefore reducing page loading times and server load as well.
When Orbeon Forms is upgraded on the server, the version number changes as well. An XForms page will refer to resources with the new version number, so the cached resource is not used by the browser and a new resource is loaded from the server, before being cached. This "magic" is enabled simply with the inclusion of the Orbeon Forms version number in the URL.
Only CSS and JavaScript resources used by the XForms engine are loaded through the XForms Server component. Other resources like images referred by XForms stylesheets are served by the Page Flow Controller, through URLs like this one:
With resource versioning enabled, the URL becomes:
When resource versioning is enabled, the Page Flow Controller by default serves all the resources defined in <files> elements by first checking the oxf.resources.versioned property. If versioning is enabled, the PFC removes the version number from the URL before searching for the resource on disk. It is possible to turn this behavior on and off selectively with the versioned attribute. Here is how to turn off versioning for PDF files in page-flow.xml:
Conversely, resource URLs produced by an XForms page are automatically rewritten following the Page Flow's <files> definitions.
The versioning mechanism is made available to your own application resources as well. Any resource whose path doesn't start with /ops/ or /config/ is considered part of your application, not of Orbeon Forms. In that case, the Orbeon Forms version number is not used, but you specify instead an application version number in properties-local.xml:
For deployed application, you should upgrade the application version number whenever you modify application resources so that clients retrieve the proper resources.
The following scenario shows the entire lifecycle for application resources:
You create an image as RESOURCES/apps/foo/bar.png
You refer to it as:
With versioning enabled, the image path is rewritten automatically as follows:
Note that the application resource number is used because the resource is not part of Orbeon Forms.
Your browser sees a URL like:
When the browser loads the image, the PFC receives back:
The PFC knows that PNG files are versioned, so removes the version number and sends this resource to the browser:
From client-side JavaScript, you can access the application version number as follow:
Versioned resources served by the PFC (that is all the resources except the XForms engine's CSS and JavaScript resources) also get an aggressive expiration date.
NOTE: We recommend restarting Orbeon Forms after changing the oxf.resources.versioned property, as data in Orbeon Forms caches may not be made aware of the change until the next restart.
With Orbeon Forms 2019.1, this feature is removed from Orbeon Forms and the oxf.xforms.resources.javascript-at-bottom property doesn't have any effect.
With Orbeon Forms 2018.1 and 2018.2, this feature is deprecated and scripts are by default placed within the <head> section with the defer attribute.
With Orbeon Forms 2017.2 and older, this feature is enabled by default.
The following property, if enabled, places external and inline JavaScript at the bottom of the page for performanc reasons:
Mappings between resources URLs and the resources are stored in the xforms.resources cache, configured in .
This is an feature.
With the introduction of , the feature is disabled by default in dev mode but enabled by default in prod mode.
In case you use Apache, you can in addition configure a rewriting rule with to allow Apache to directly load resources containing a version number, as shown below.
See Yahoo’s