Mostly Grails tips from Code Panda

Migrating from the Grails UI-performance plugin to resources plugin.

The UI-performance plugin has been a standard for managing images, css and javascript files for many grails applications. In the upcoming Grails 2.0 release, however, it seems that the recommended way of managing resources is via the Resources plugin.

Many of the posts on the web ( like this one, or this one )describe how to get started with the Resources plugin from scratch. However, chances are that your project already uses UI-performance. How easy is it to migrate an existing project to use Resources?

In this post, I would like to document the steps we took to migrate our Grails project from the UI-performance plugin to the new resources plugin.

Steps

1. Uninstall UI-performance

You do this by grails uninstall-plugin ui-performance

2. Install resources plugin

Grails install-plugin resources.

You might be tempted to install all the other related plugins at this point, but I would recommend just sticking with vanilla versions of the plugin.

3. Replace all references to ui-performance tags with new resources tags.

For this, I wrote a simple tag library that simply maps the UI-performance tags to resources tags

UI-performance assumes certain defaults for directories, which resources does not. Using a tag library makes it easy to switch back and forth between the two plugins.

One thing that is important for these tags is that you can’t use relative paths in your file references. So if your tag is <p:image src=”myfolder/image1.jpg”/>, you need to change it to <p:image src=”/myfolder/image1.jpg” />

In our application, we don’t use sprites or the dependantJavascript tag, but you could write similar taglib code to override this.

4. [Optional] Add tags to your layouts to include the tags used by resources plugin to provide ‘ESP‘

At this point, you will want to change your layouts to include JavaScript resources in your application’s head and body.

Go through each of your layout files and add a <r:layoutResources/> tag in your head and body sections. This step is useful if you wish to leverage other features of the resources plugin in the future, but is not necessary for translating uiperf to resources.

5. Run your application and make sure everything renders correctly.

Try your application with both grails run-app and grails run-war to see that it works in the way you want it to work.

6. [Optional] Define modules.

One of the more powerful features of the resources plugin is the ability to define modules that encapsulate a series of resources. One of the main benefits of this approach is that it guarantees that all your javascript and css files get included correctly, and they appear on the right place in your page. It also makes the inclusion of resources less verbose, as you can bundle several js files and css files together.

On the other hand, changing resources to modules is also tedious and error prone if you already have a bunch of resources defined with the Ui-performance plugin. You have to go through each page of your site that has a <p:whatever/> tag and refactor these to use the new <r:require> tags.

If you choose to declare modules, you will have to introduce a new file called ApplicationResources.groovy and follow the instructions in the plugin user guide.

7. [Optional] Change your tags from r:external to r:require.

If you have defined a module in the previous step, you will wish to change the parts in your code that reference the old css and javascripts, and replace them with the new, simpler <r:require tags/> for the modules. It really depends on why you want to switch from one plugin to the other.

8. Add additional support plugins and make sure that everything works correctly.

For our application, we’re adding the cached-resources, cdn-resources, less-resources and zipped-resources plugins. For this step, we install each plugin individually and make sure that they work correctly. Refer for each plugin documentation for additional steps. For the CDN-resources plugin, for example, I had to go ahead and set up a CDN location for my application.

9. Test and Deploy.

Discussion

If the UI-performance plugin works well for you, there is really no reason to migrate to the new resources plugin mechanism.

For us, there were two things that we are currently doing that made us want to switch to Resources:

we started using LESS and it felt that this is slightly better supported by the resources plugin than by UI-performance.

We wanted to use a CDN. Although we got UI performance to work with a CDN, the version of the plugin that included the patch ( 1.2.2. trunk ) had some issues dealing with images in css files. At the end of the day, it felt safer to write a simple mapper to enable CDN support.

Cached-resources is more efficient than the current way in which UI-performance handles versioning.

In UI-performance, a new CSS, image and JS file gets created and downloaded by the client whenever a new War is pushed.

Given that we follow principles of continous deployment, it meant our clients kept downloading the same images over and over again. Using Cached resources means that we are able to reduce the number of files being downloaded by our clients.

We like the notion of modules and feel that this is something we would like to refactor our code to use.

Hopefully, you would agree that the process of transitioning an existing project that uses the ui-performance plugin into resources plugin is fairly seamless and pain free.