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.
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” />
4. [Optional] Add tags to your layouts to include the tags used by resources plugin to provide ‘ESP‘
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.
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.
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.
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.