(Quick Reference)

9 Configuration - Reference Documentation

Authors: Marc Palmer (marc@grailsrocks.com), Luke Daley (ld@ldaley.com), Peter N. Steinmetz (ndoc3@steinmetz.org)

Version: 1.2.14

9 Configuration

There are various configuration options to control processing of your resources.

All of these config variables can of course be set per-environment.

Setting the location of processed static resources

By default the plugin writes processed resources to a temporary directory.

You can change this to a directory that exists in a reliable location and hence can be used to server resources via e.g. Apache, by assigning a full filesystem path value to grails.resources.work.dir

Change the /static/ URI prefix: grails.resources.uri.prefix

By default the plugin serves the modified static resources from URIs beginning with <appcontext>/static/.

You can change this by assigning a value to grails.resources.uri.prefix

Debug mode: grails.resources.debug

Setting grails.resources.debug=true will force debug mode all the time, as if you added _debugResources=y to every request.

Dependency-only mode: grails.resources.processing.enabled

You can turn off resource processing completely with the trivial Config variable:

grails.resources.processing.enabled = false

Like the _debugResources option, this will perform no processing at all. It will also not require a writable file system on the server, but obviously precludes any processing of resources.

You do however retain the dependency management abilities.

Disabling specific resource mappers in different environments

You can disable any mapper using the standard environment-specific configuration of Grails:

grails.resources.mappers.bundle.enabled = false
grails.resources.mappers.hashandcache.enabled = false

Controlling the scope of the adhoc filter: grails.resources.adhoc.patterns

The ad-hoc resource filter is mapped using Servlet SDK filter mappings, which are more restricted that Ant patterns. You can specify folder (xxx/) or file type (.xxx) mappings only.

You may not want the adhoc filter, which is only used for legacy resources (which are not linked to using resource tags), to intercept everything in your application.

The default value is:

grails.resources.adhoc.patterns = ["/images/*", "*.css", "*.js"]

Controlling the includes and excludes of the adhoc filter: grails.resources.adhoc.includes/excludes

While the grails.resources.adhoc.patterns setting gives you coarse control over which legacy URIs are intercepted, you can get full Ant-style include/exclude patterns using the grails.resources.adhoc.includes and grails.resources.adhoc.excludes variables.

They both accept a list of Ant-style patterns.

Including specific resource patterns per-mapper: grails.resources.<mappername>.includes

You can control the list of matching resources on a per-mapper basis. Mappers provide sensible defaults but you may have new content types (for example a new CSS variant such as LESS) that were not known at the time the mapper was written.

So for example to add .less files to processing by the CSS rewriters (necessary for correct behaviour with bundle mapper):

grails.resources.mappers.cssrewriter.includes = ['**/*.css', '**/*.less']
grails.resources.mappers.csspreprocessor.includes = ['**/*.css', '**/*.less']

You can also use this to ensure that only resources under a specific folder are processed.

Note that the value you provide replaces the default list supplied by the mapper.

Excluding specific resource patterns per-mapper:grails.resources.<mappername>.excludes

There may be times when a mapper is processing too many files - those that may have already been processed or that may become damaged by the mapping (i.e. incompatibilities due to relative code loading by JS code). Simply add the resource names or patterns to that mapper's excludes:

grails.resources.mappers.cssrewriter.excludes = ['unsafe/**']
grails.resources.mappers.csspreprocessor.excludes = ['unsafe/**']
grails.resources.mappers.bundle.excludes = ['unsafe/**/*.css']

Note that the value you provide replaces the default list supplied by the mapper.

Excluding specific mapper all together

You can exclude any (also custom) mapper from processing all together by using grails.resources.mappers.<mappername>.enabled = true | false.

For example:

grails.resources.mappers.cssrewriter.enabled = false

Disabling CSS rewriting: grails.resources.rewrite.css

It is possible to turn off all CSS rewriting by setting this value to false. This is not recommended as it will usually break bundling unless all your links are relative and you don't have any mappers that move your resources relative to your CSS.