Grails with Twitter Bootstrap

twitter-bootstrap

Twitter Bootstrap is awesome. So is Grails. It is a match made in heaven, and these two are now officially BFF’s. For those, not familiar with Twitter Bootstrap, it is a bundle of CSS (or LESS) files, along with Javascript goodies and some graphics, enough kickstart your site/app and make it look professional. Seriously, it rocks, you should definitely check it out.

So, the idea of this exercise (and it is by no means mine), is to apply all the Bootstrap goodies to a vanilla Grails installation, both on the sample pages and the dynamic scaffolding (the CRUD UI for all the domain classes in the app).

I won’t go through the steps of downloading, and setting up Grails on your PC/Mac, let’s assume, you have all this figured out, and you are ready to create a Grails app. FYI, you can find the end product on GitHub, feel free to pull/fork, but if you feel like going through this exercise with me, see below. So, it begins:

  • For the sake of keeping this simple, this works with Grails 2.2.2, haven’t tested this with any other Grails version.
  • grails create-app grails-twitter-bootstrap. OMG, you have just unleashed hell…
  • You will need to add two plugin dependencies to your grails-app/conf/BuildConfig.groovy file:

compile “:twitter-bootstrap:2.3.0”

compile “:lesscss-resources:1.3.3”

  • The first, is for the Twitter Bootstrap plugin, which adds all the Bootstrap resources, ready to be used by the mighty Grails Resources plugin. There as some steps that you need to follow, before you start using this plugin, that can be found on the plugin’s full documentation page. To cut the long story short… by adding
    <r:require modules="bootstrap"/>
  • to a view, or layout, you make all the Bootstrap resources available on the page. You can selectively, add parts of Bootstrap, for example
    <r:require modules="bootstrap-modal"/>
  • for the modal JS windows, but you can just add the whole thing. I want to use the Responsive Bootstrap and I would like to use the LESS files instead of the CSS, so my require looks like this
    <r:require modules="bootstrap-responsive-less,bootstrap-js"/>
  • Don’t forget to also apply the rest of the configuration listed on the plugin’s documentation page.
  • Happy days! Of course, in order to be able to use the LESS files, I had to install the LESSCSS resources plugin, which is the second plugin, listed above. That’s it, no more plugins for today.
  • Grails, by default, comes with the main.gsp layout, which is used on all the pages and the scaffolding pages. So, I just remove the reference to the Grails CSS files from the layout and add the above Bootstrap require.
  • So far, so good. We have reached the part where we need to tell our Grails scaffolding templates, to use Twitter Bootstrap. But, wait a sec, where are these templates? There are two ways you can generate scaffolding for a domain class, either statically, or dynamically. By static, I mean, run
    grails generate-controller
  • and this will create the .gsp’s files. However, in this way, you will have to edit all the .gsp files for all the domain classes. Instead, we can use Grails dynamic scaffolding, just by adding:
    static scaffold = true
  • and then, we will be using the mysterious Grails scaffolding templates that are nowhere to be found. Keep in mind, in the above command, “true” works based on convention over configuration, for example for a BookController and a Book domain class, other wise you will have to explicitly say which domain class, this controller provides scaffolding for, like
    static scaffold = Book
  • So, in order to get the scaffolding templates, you need to run
    grails install-templates
  • The templates will be created under the src/templates/scaffolding directory. You are looking at the familiar create, edit, list, show and _form gsp files. Any change on any of these files, will affect all the scaffolding for all the domain classes using dynamic scaffolding.
  • And this is where the Twitter Bootstrap magic will have to kick in. I won’t go into detail, the commits on the GitHub repo with the sample application are pretty self explanatory, but allow me to list the changes applied:
  • Use responsive design for both the index/error pages and the scaffolding pages
  • For the scaffolding pages, I used fluid layout
  • Bootstrap styled buttons, forms, navigation, and some nice slideshow for the front page.

Hope you enjoyed this post, feel free to ping me if you have any questions, the easier way to get the hang of it, would be to pull the project from GitHub and have a look at the few commits that reflect the steps taken into this post.

Enjoy,

Iraklis

Advertisements