JQuery for Grails

  • Authors : Sergey Nebolsin, Craig Jone, Marc Palmer and Finn Herpich
26 votes

83% of Grails users

Dependency : 
runtime ":jquery:1.8.3"

Documentation

Summary

Provides integration for the JQuery library with grails JavascriptProvider

Installation

To install the jQuery plugin type this command from your project's root folder: 
grails install-plugin jquery

Targets:

grails installJQuery

  • This target downloads and installs jquery-1.4.2.js and jquery-1.4.2.min.js under web-app/js/jquery/
The complete jQuery distribution is downloaded and installed under your project's /web-app/js/jQuery folder.

Description

jQuery Plugin

Current maintainer: Finn Herpich
Author : Sergey Nebolsin
Contributers : Craig Jones, Finn Herpich

This plugin provides integration with jQuery-Javascript-library. When installing the plugin, it downloads and installs automatically the latest jQuery 1.4 distribution in your application and registers itself to be used with the adaptive AJAX tags.

Before upgrading to 1.4.* from a prior version please check http://jquery14.com/day-01/jquery-14 for changes which may break your code.
The code has moved to https://github.com/gpc/grails-jquery

Index

  • Find help
  • Usage
  • Upgrading
  • Releases

Find help

Question? Ask on the Grails user mailinglist. If you have no luck and you'll get no response please mail the current maintainer.

Found a bug? Please file a bugreport at http://jira.codehaus.org/browse/GRAILSPLUGINS/component/13544 JIRA for the grails-jquery component.

Usage

Ajax via jQuery

To have the Grails' adaptive AJAX support adapt itself to jQuery (rather than the default of Prototype, or another choice like YUI or Dojo):

Since Grails 1.2:
Add this line to your layout-file 

<g:javascript library="jquery" plugin="jquery"/>
and the following to your grails-app/conf/config.groovy 
grails.views.javascript.library="jquery"
  • alternatively you can use:
<g:javascript library="jquery" />
(without plugin="jquery") but you will need to call the grails installJQuery target (see Installation Tab)

Prior Grails 1.2:
Add the following line in the head section of every GSP that needs it. (Note: It is NOT sufficient to add it only to main.gsp in layouts.) 

<g:javascript library="jquery"/>

Thereafter the <g:remoteField>, <g:remoteLink>, <g:formRemote> etc. tags will utilize jQuery for the ajax calls. (See the Grails documentation, or "The Definitive Guide to Grails" chapter 9, etc.)

Ajax via jQuery in Partial GSP

Sometimes, the GSP being rendered is itself an Ajax respose. That is, rather than being a whole HTML page in response to a regular HTTP request, it's partial HTML that will dynamically replace the body of a DIV. In this case, there is no head section, so the g:javascript tag is not the right way to trigger the jquery binding.

Instead, use the g:setProvider tag at the top of the response (or anywhere above the first ajax-adpative tag). 

<g:setProvider library="jquery"/>

Delayed Javascript execution

One of the advantages of jQuery is that you can specify that your javascript is not to run until the page has loaded completely. To do that with this plugin, use the supplied jq:jquery tag (instead of g:javascript): 
<jq:jquery> your delayed-action javascript here </jq:jquery>
Everything inside this tag will be wrapped into 
<script type="text/javascript">jQuery(function(){ your delayed-action javascript here });</script>

Change jQuery-version

Sometimes you need an older version of jQuery but you also want to take the advantage of grails build-in AJAX-tags. Since 1.4.2.1 you can specify the following in your application Config.groovy-file: 
jquery {
    sources = 'jquery' // Holds the value where to store jQuery-js files /web-app/js/
    version = '1.4.1' // The jQuery version in use
}
sources Specifies the folder underneath web-app/js where the jQuery-lib should be
version Specifies the version of the lib

The settings above will result in js/jquery/jquery-1.4.1.min as location

jq:resource

Idea

This tag has been developed to help you load all the resources you need for most of your jquery plugins, which are javascript and css files. Although that taglib was design with with Jquery UI in mind, it can be used with all other kind of jquery plugins. With so many available on the web, that can be only a good thing to make their integration easier

Config

You can specify some properties for the taglib in the conf/JqueryConfig.groovy file 
jquery {
	sources = 'js/jquery'
    coreSuffix = 'core'
	cssFolder = 'theme'
	cssDefault = 'base'
	minFolder = 'minified'
	minExtentsion = 'min'
}

Taglib-API

bundle: bundle which your components belongs to. It will be used to build the filename to include. Ex: "ui" , "effect" optional

components: list string with the name of the components you want to use in your page. Ex: "datepicker, tabs", "jcrop" mandatory

theme: the name of the folder where to find the css files of the components. Ex: "cupertino", optional, default: "base"

Implementation

With the tag jq:resource, you list components you want to include, then the taglib is using your configuration and some convention/defaults to build the path of js and css files your components may need. It'll then check if the file exist in your grails so that i can create the <link> and <style> tags needed. Also, if your environement is dev or test, it will include the full version of the js, if it's production it will try to include the minified version.

The algorithm is as follow, for a component named "mycomp" in the bundle "ui", on a dev config:

  • build the js filename from the component and bundle names => ui.mycomp.js
  • check if the file ui.mycomp.js file exists in the js folder
  • add the tag <style src="jsfolder/ui.mycomp.js" .. >
  • if not added before and if the file exist, add the tag <style src="jsfolder/ui.core.js" .. >
  • check if the css file "cssfolder/base/ui.mycomp.css" exist
  • add the tag <link href="cssfolder/base/ui.mycomp.css" ...>
  • if not added before and exist, add <link href="cssfolder/base/ui.core.css"...>
  • if not added before and exist, add <link href="cssfolder/base/ui.theme.css" ...>

Tips

  • try as much as possible to follow the standards, which follow the Jquery UI folder structure and naming convention
  • make sure that you copy all the necessary files in the right place, so that the taglib can find your file
  • try to make only one call to the taglib per bundle, or you will get the "core" css and js file included several times

Manually Installing jQuery plugins ("sub-plugins")

Manually installing a plugin is quite easy.

First, save the plugin code to your web-app/js/jquery folder. It's not required, but for consistency, you might make sure it has a dot-notation prefix of "jquery.". For example, to use Josh Bush's progress bar plugin (http://digitalbush.com/projects/progress-bar-plugin/), open 

http://digitalbush.com/wp-content/uploads/2007/02/jqueryprogressbar.js
and save it as 
<working-folder>/web-app/js/jquery/jquery.progressbar.js
Next, edit your application.properties file and add a corresponding jquery.plugins line: 
jquery.plugins.progressbar=jquery.progressbar.js
You can now take advantage of the jq:plugin tag to load the plugin code as needed, as described above. 
<jq:plugin name="progressbar"/>
(Of course, how to actually use the plugin depends on the plugin.)

Upgrading

If you want to upgrade:

  • Delete the plugin from the projects /plugin folder
  • (Optional) Delete the previous jQuery version folder from /web-app/js/jQuery
  • Install the plugin by executing grails install-plugin jquery

Plugin version history

2010-05-01 1.4.2.1

2010-01-26 1.4.1.1 2010-01-18 1.4.0.1 2009-06-11 1.3.2.4
  • Added config-file JQueryConfig.groovy
  • Moved sources and version to jquery.sources and jquery.version
2009-06-09 1.3.2.3 2009-06-08 1.3.2.2 2009-02-22 1.0RC2b
  • Update to jQuery 1.3.2
2009-02-22 1.0RC2
  • Update to jQuery 1.3.1
  • Code clean up
2008-10-28 1.0RC1 First release candidate