Ajax Support

Introduction

Ajax stands for Asynchronous Javascript and XML and is the driving force behind the shift to richer web applications. These types of applications in general are better suited to agile, dynamic frameworks written in languages like Ruby and Groovy. Grails provides support for building Ajax applications through its Ajax tab library for a full list of these see the Tag Library Reference.

Rails developers will be familiar with the tag library as there are equivalent helper methods in Rails for most of Grails' Ajax tags. In addtion Ajax is provided through integration with the Prototype library, but the Grails team are looking at providing a generic mechanism that works with a number of different javascript implementations.

Loading Remote Content

Remote content can be loaded in a number of ways, the most commons way is through the "remoteLink" tag. This tag allows the creation of HTML anchor tags that perform an asynchronous request and optionally set the response in an element. The simplest way to create a remote link is as follows:

<g:remoteLink action="delete" id="1">Delete Book</g:remoteLink>

The above link sends an asynchronous request to the "delete" action of the current controller with an id of "1". This is great, but usually you would want to provide some kind of feedback to the user as to what has happened:

@Property delete = {
      def b = Book.get( params['id'] )
      b.delete()
      render "Book ${b.id} was deleted"
}

<div id="message"></div>
<g:remoteLink action="delete" id="1" update="message">Delete Book</g:remoteLink>

The above example will call the action and set the contents of the "message" div to the response in this case "Book 1 was deleted". This is done by the "update" attribute on the tag, which can also take a map to indicate what should be updated on failure:

<div id="message"></div>
<div id="error"></div>
<g:remoteLink action="delete" id="1" update="[update:'message',failure:'error']">Delete Book</g:remoteLink>

Here the error div will be updated if the request failed.

Handling Events

Specific javascript can be called if certain events occur, all the events start with the "on" prefix and allow you to give feedback to the user where appropriate, or take other action:

<g:remoteLink action="show" id="1" update="sucess" onLoading="showProgress();">Show Book 1</g:remoteLink>

The above code will execute the "showLoading()" function which may show a progress bar or whatever is appropriate. Other events include:

• onSuccess (optional) - The javascript function to call if successful
• onFailure (optional) - The javascript function to call if the call failed
• on_ERROR_CODE (optional) - The javascript function to call to handle specified error codes (eg on404="alert('not found!')")
• onUninitialized (optional) - The javascript function to call the a ajax engine failed to initialise
• onLoading (optional) - The javascript function to call when the remote function is loading the response
• onLoaded (optional) - The javascript function to call when the remote function is completed loading the response
• onComplete (optional) - The javascript function to call when the remote function is complete, including any updates

Submitting a Form remotely

An HTML form can also be submitted asynchronously in one of two ways. Firstly using the "formRemote" tag which expects similar attributes to those for the "remoteLink" tag:

<g:formRemote url="[controller:'book',action:'delete']" update="[update:'message',failure:'error']">
       <input type="hidden" name="id" value="1" />
       <input type="submit" value="Delete Book!" />
</g:formRemote >

Or alternatively you can use the "submitToRemote" button this allows some buttons to submit remotely and some not depending on the action:

<form action="delete">
       <input type="hidden" name="id" value="1" />
       <g:submitToRemote action="delete" update="[update:'message',failure:'error']" />
</form>