nerdErg

nerdErg | software

1. GSParse Grails plugin

GSParse is a grails plugin, Apache 2.0 Licensed, that lets you parse other files as GSP files. Current release version is 1.3.

GSParse only works on Grails 1.x and 2.x, and there is currently no plan to port it to Grails 3 and 4 as there has been no call for it, and there are other, probably better, ways to do this now.

1.1. Why?

Some web artefacts like Javascript and CSS files need to reference resources and could do with some scripting themselves.

For example, using Javascript for doing Ajax lookup for auto-complete needs a URL to a controller/action. If you try and hard code a relative URL you run into re-useability issues. Lets say you’re using jQuery and the jQuery autocomplete plugin. You might have some code that looks like this:

autocomplete.js
$(function() {
    $("#task").autocomplete('../task/suggestTask', {
        max: 100,
        width: 300
    });
});

Which works fine when you’re at a url that looks like http://your_base_url/controller/action but breaks as soon as you go to a url that looks like http://your_base_url/controller/action/id.

GSParse comes to the rescue here by letting you use grails tags like g.createLink() to do the following:

autocomplete.js
$(function() {
    $("#task").autocomplete('${g.createLink(controller: "task", action: "suggestTask")}', {
        max: 100,
        width: 300
    });
});

CSS needs GSParse too because you want to use relative URLs in the CSS. You can do the exact same trick ie.

sample.css
body {
    background: url('${g.resource(dir: "image", file: "thing.png")}');
    color: #${color};
}

You may have noticed in the above CSS snippet the #${color}, which demonstrates another feature of GSParse where you can pass in parameters, in this case a color.

CSS is desperately in need of scripting, and things like Less.js which enable scripting of CSS. With GSParse you get GSP scripting free of charge. So you can do this for example:

sample.css
${g.set(var: 'p1', value: '#AAA'}
p {
    color: ${p1}
}

which lets you set up a colour pallet atop your CSS file and just reference the colours throughout, thus letting you change the colour scheme simply, or even per user via passed in params.

1.2. Why not just use regular GSP files and views?

Because your IDE doesn’t recognise a GSP file as javascript or CSS, so we let the IDE help build your files then you can decorate them with GSP. Of course this ain’t perfect, your IDE is likely to look at some of the GSP and mark it as an error, but hey it’s better than nothing (and I’m working on fixing that).

1.3. How do you use it?

There is an example project on GitHub here http://github.com/pmcneil/GSParseTestApp

1.3.1. Install it:

grails install-plugin gsp-arse

Then add a URL mapping to your projects UrlMappings.groovy file e.g.

"/resource/$path**"(controller: 'script', action: 'parse')

You can change "resource" to whatever you like.

In Version 1.0 you need to turn off grails.mime.file.extensions, which parses the file extensions from URLs. Unfortunately this removes the extension on the file name meaning GSParse V1.0 can’t find the file. This has been fixed in V1.1 where we use the request.format to set the mime type and guess the file extension by convention.

Then change your references to point to that URL in your layouts/main.gsp, or any specific views like this:

index.html
<link rel="stylesheet" href="${resource(dir:'resource/css',file:'main.css')}" />
<script type="text/javascript" src="${resource(dir:'resource/js',file:'application.js')}?color=FA8DFF"></script>
Don’t blame me for the gsp-arse thing, that’s Grails converting GSParse to lowercase…​ :-)