jQuery Plugin

jQuery Plugin

Author : Sergey Nebolsin
Contributers : Craig Jones, Finn Herpich

This plugin provides integration with jQuery. When installing the plugin, it downloads and installs automatically the latest jQuery 1.3.2 distribution in your application, and registers itself to be used with the adaptive AJAX tags. It also contains a helper tag to easily include additional jQuery javascript.

Index

  • Installation
  • Usage
  • Upgrading
  • Releases
  • FAQ

Installation

To install the jQuery plugin type this command from your project's root folder: 
grails install-plugin jquery
The complete jQuery distribution is downloaded and installed under your project's /web-app/js/jQuery folder.

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), 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>, and <g:formRemote> 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>

Using jQuery plugins ("sub-plugins")

This jQuery plugin for Grails is aware of certain plugins that exist for jQuery itself ("sub-plugins", if you will). For example, jQuery has a treeview plugin.

To take advantage of such jQuery plugins, first install the jQuery plugin using the grails script that we've supplied: 

grails install-jquery-plugin treeview

Then, in the head section of any GSP that needs it, include: 

<jq:plugin name="treeview"/>

In the case of the treeview plugin, there's a css file that goes with it. So, you'll want to include a reference to it in the head section as well: 

<link rel="stylesheet" href="${createLinkTo(dir:'css',file:'jquery.treeview.css')}" />

Manually Installing jQuery plugins ("sub-plugins")

Currently, the install-jquery-plugin script is only aware of a limited number of the jquery plugins. However, 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.jqueryprogressbar.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

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

FAQ

(Ask on the user mailing list, and ye shall be heard.)

No Comments Yet

Post a Comment