6 Creating custom mappers

You can create your own ResourceMapper artefacts inside your application or plugins to perform tasks such as;

• Moving and renaming resources
• Changing the contents of resource files (compress, minify, compile etc)
• Set HTTP response headers when requests are processed

Resource mappers only get the chance to map (process) each resource once - the final resource is then stored on disk to serve future requests.

6.1 Defining a mapper

The name of the mapper is extracted from the filename like any other Grails artefact, for example "TestResourceMapper" yields a mapper with name "test".

Example grails-app/resourceMappers/TestResourceMapper.groovy:

import org.grails.plugin.resource.mapper.MapperPhase
class TestResourceMapper {
    def phase = MapperPhase.MUTATION
    def map(resource, config) {
        def file = new File(resource.processedFile.parentFile, "_${resource.processedFile.name}")
        assert resource.processedFile.renameTo(file)
        resource.processedFile = file
        resource.updateActualUrlFromProcessedFile()
    }
}

The only method a mapper must implement is map(resource, config) which is passed the ResourceMeta object that represents the resource and the mapper-specific config variables pulled out of grails.resources.mappers.<mappername>. NOTE: The name of the mapper is always in all lower case.

This method can do whatever it needs to the resource's file, provided it calls the updateActualUrlFromProcessedFile() method if the resource moves, unless you patch ResourceMeta.actualUrl manually.

You can change other properties of the resource, such as change the content type of the resource, add or modify tagAttributes (which are passed through when rendering the link for the resource).

That's all you need to do to create a mapper. The best way to learn how they work is to study the source of Cached-Resources and Zipped-Resources plugins.

6.2 Mapper phases and priority

enum MapperPhase {
    GENERATION, // create new assets = compile less files
    MUTATION, // alter/improve assets (may mean creating new/deleting aggregated resources) = spriting
    COMPRESSION, // reducing the file size but maintaining semantics = minify
    LINKNORMALISATION, // convert all inter asset references into a normal form = css links
    AGGREGATION, // combining mutiple assets into one = bundling
    RENAMING, // moving of physical assets = hashing
    LINKREALISATION, // convert normalised inter asset references into real form = css links
    ALTERNATEREPRESENTATION, // attach different representations of the asset = gzipping
    DISTRIBUTION, // moving assets to their hosting environment = s3, cdn
    ABSOLUTISATION, // update inter asset references to their distributed equivalent = css links
    NOTIFICATION // let the world know about the new resources = cache invalidation
}

In most cases it will be enough to specify your phase and operation (see next section). However in some cases there may be issues where multiple mappers in the same phase must operate in a specific order. In those cases a "priority" property can be set to specify the priority integer.

Mappers will be executed in phase order, in order of ascending priority within each phase. The default priority if not specified is equivalent to zero.

6.3 Operation

The common example is to specify exclude:"minify" in a resource declaration to prevent any kind of minifying mapper from being applied to a resource that is already minified.

A similar operation called e.g. "compress" could be used to prevent duplicate zipping of resources that may have been pre-compressed (such as images).

import org.grails.plugin.resource.mapper.MapperPhase
class TestResourceMapper {
    def phase = MapperPhase.COMPRESS
    def operation = "compression"
    def map(resource, config) {
        // Zip the file here
    }
}

Note the operations and mapper names occupy the same namespace so that the "exclude" argument on resource declarations can apply to either.

Resources will fail fast at runtime if an operation is specified on any mapper, where there is also a mapper with a name the same as the operation.

6.4 Processing only the right types of files

import org.grails.plugin.resource.mapper.MapperPhase
class TestResourceMapper {
    def phase = MapperPhase.MUTATION
    static defaultExcludes = [
        '**/*.png',
        '**/*.gif',
        '**/*.jpg',
        '**/*.jpeg',
        '**/*.gz',
        '**/*.zip'
    ]
    static defaultIncludes = [ '/images/**' ]
    def map(resource, config) {
        …
    }

These defaults can be overidden by the user with the grails.resources.<mappername>.includes and grails.resources.<mappername>.excludes Config variables.

6.5 Adding response headers and intercepting requests

Note that this cannot be used to change how the resource is mapped - the mapping is performed once only, but the response headers can be customized every time the file is requested.

As an example, the Zipped-Resources plugin uses this mechanism to set the Content-Encoding header:

import org.grails.plugin.resource.mapper.MapperPhase
class ZipResourceMapper {
    static phase = MapperPhase.ALTERNATEREPRESENTATION
    /**
     * Rename the file to a hash of it's contents, and set caching headers 
     */
    def map(resource, config) {
        // Do the zipping
        ...
        // Set up response headers
        resource.requestProcessors << { req, resp ->
            resp.setHeader('Content-Encoding', 'gzip')
        }    
    }
}

Here the mapper adds a Closure that takes the request and response objects to the resource's requestProcessors list. These will be called in the order they are defined on the resource.