jawr Grails plugin

  • Tags : performance, utility
  • Latest : 3.5
  • Last Updated: 06 January 2014
  • Grails version : 2.3 > *
  • Authors :
3 votes
Dependency :
compile ":jawr:3.5"

Source

Summary

jawr grails plugin

Description

Jawr is a tunable packaging solution for Javascript and CSS which allows for rapid development of resources in separate module files. You can work with a large set of split javascript files in development mode, then Jawr bundles all together into one or several files in any way you define. By using a tag library, Jawr allows you to use the same, unchanged GSP pages for development and production. Jawr also minifies and compresses the files, resulting in reduced page load times. You can find all the information and detailed documentation at https://jawr.dev.java.net/.

Latest plugin version is 3.3.3. The version number matches the Jawr version it uses underneath.

Update warning

If you are upgrading from a version prior to 2.51, be aware that Jawr now uses a servlet instead of a controller to serve files. This has several advantages: it is faster, there is no need to fiddle with the grails.mime.file.extensions property, and no controller mappings need to be added. So if you are upgrading, you need to remove the controller mappings, reset the grails.mime.file.extensions property and then follow URL mapping instructions below.

Installation

Type this command in your Grails application directory
$> grails install-plugin Jawr
If this doesn't work, download the zip file from this page and then install it from your hard drive:
$> grails install-plugin /path/to/grails-jawr-3.3.1.zip


Configuration

To configure Jawr you must add properties to the Config.groovy file located at the /conf folder of your application. The syntax you must use is exactly the same described for the .properties file used in standard java web applications. Check the config file syntax page for details. Keep in mind that there are a few property keys that don't apply when using Jawr with Grails. Those are: 

  • jawr.config.reload.interval: The Jawr servlet can be configured to listen to changes to the .properies file to reload it when it changes. In Grails, Jawr will instead listen to changes to the Config.groovy script to reload its configuration. This happens automatically when you start grails in development mode (but keep in mind that the changes are applied after you refresh a page in your browser).  
  • jawr.charset.name: The value set for grails.views.gsp.encoding will be used for this attribute (which is 'utf-8' by default in Grails).
Using this syntax, you will be able to define bundles as specified in the relevant documentation pages. Note that you are not forced to use Jawr for both js and css files. If you add none of the jawr.css.* parameters, for instance, Jawr will do no effort to serve CSS files.     Jawr uses log4j to log messages, so you can configure its tracing level along with the rest of your application. All jawr packages start with net.jawr.*, so you can use that as a key for an appender.

The configuration will indicate to the plugin which Jawr servlet to start.  

So if you configure only JS bundle, the plugin will start only the Jawr JS servlet. So to enable the JS or the CSS servlet, you must at least define a bundle of the specified type. To enable the Jawr Image servlet, you need to define one of the following property :

  • jawr.img.mapping
  • jawr.css.image.classpath.use.servlet
  • jawr.img.* (Any property which starts with jawr.img)
  • jawr.image.* (Any property which starts with jawr.image)

URL mapping

There are two ways to map Jawr to requests: 

  • You can have Jawr respond to all requests ending in .js and .css, thus letting Jawr control all requests to your resources. This is the default behavior, and you don't need to configure anything at all for it to work, simply omit the jawr.js.mapping/jawr.css.mapping properties from your config and you are ready to go.
    • This is the usual approach, but you may want to bundle only part of your code and serve the rest normally. This is specially useful if you are adding Jawr to an existing application and you do not want to change every existing script tag. Note that Jawr handles individual files (you don't need to explicitly define a bundle for every file you want to compress and serve standalone), so that should not keep you from using this mapping method.
  • You can define a URL fragment as a prefix (such as '/jawr/') to prefix every URL. Jawr will only serve requests containing this prefix. To use this you must add two special parameters to your Config.groovy file, to specify the prefixes for js and css:
jawr.js.mapping = '/script/' // The value can be anything you want for the prefix
jawr.css.mapping = '/style/'

Note that the value for these properties must be a url-mapping string without the wildcard (i.e. with no asterisk).

  • Image URL mapping
By default, Jawr will handle the following image types : .png, .jpeg, .jpg, .gif, .ico.

You can configure the image mapping by settings the jawr.img.mappings. If you want to define a set of extension file to handle, you need to list the extension with a semi colon separator, like this :

jawr.img.mapping='*.png; *.jpg; *.gif'

With either method, once you have filled out the properties, you will be ready to start adding Jawr tags to your pages.

Using the tag library

The tag library for grails works exactly the same as the JSP version, so you will find all the details in the JSP taglib documentation page.

The only difference is that in GSP pages there is no need to import the tags at all. Also, keep in mind that the namespace for the Jawr taglib is 'jawr:'.

This is how you would use the tags in a typical page:

<html>
 <head>
  <jawr:script src="/bundles/yui.js"  />
  <jawr:style src="/bundles/all.css" />
 </head>
<body>
  …
</body>
</html>