(Quick Reference)

formRemote

Purpose

Creates a form tag that uses a remote uri to execute an Ajax call, serializing the form elements and falling back to a normal form submit if JavaScript is not supported.

Examples

Example controller for an application called "shop":

class BookController {
    def show() {
        [book: Book.get(params.id)]
    }

def byAuthor() { [books: Book.findByAuthor(params.author, params)] } }

Example usages for this controller:

<g:formRemote name="myForm" on404="alert('not found!')" update="updateMe"
              url="[controller: 'book', action:'show']">
    Book Id: <input name="id" type="text" />
</g:formRemote>

<div id="updateMe">this div is updated with the result of the show call</div>

<g:formRemote name="myForm" update="updateMe"
              url="[controller: 'book', action: 'byAuthor',
                    params: [sort: 'title', order: 'desc']]">
    Author: <input name="author" type="text" />
</g:formRemote>

<div id="updateMe">this div is updated with the result of the byAuthor call</div>

You can override both the form method and action to use when JavaScript is unavailable by providing method and action attributes. This example will submit the form to /<context>/book/show using a GET if JavaScript is unavailable:

<g:formRemote name="myForm" update="updateMe" method="GET"
              action="${createLink(controller: 'book', action: 'show')}"
              url="[controller: 'book', action: 'show']">
    Book Id: <input name="id" type="text" />
</g:formRemote>

<div id="updateMe"><!-- this div is updated with the result of the submit --></div>

Description

This tag creates a form that fires an AJAX request when it is submitted. The exact Javascript used to fire off the AJAX request depends on which Javascript library is used. This tag also requires the use of either the <g:javascript/> or <g:setProvider/> tags. See the AJAX section of the user guide to find out more.

Attributes

  • name (required) - The name of the form. This attribute will be assigned to id attribute if not present, otherwise, the value of this attribute will be omitted
  • url (required) - The url to submit to as either a Map (containing values for the controller, action, id, and params) or a URL string
  • id (optional) - The id of the form rendered to the output. If id is not set, the value of name will be assigned
  • action (optional) - The action to execute as a fallback, defaults to the url if not specified
  • update (optional) - Either a Map containing the elements to update for 'success' or 'failure' states, or a string with the element id to update, in which case failure events would be ignored
  • before (optional) - The JavaScript function to call before the remote function call. A semi-colon is automatically added so you don't have to provide one yourself in this string.
  • after (optional) - The JavaScript function to call after the remote function call. A semi-colon is automatically added so you don't have to provide one yourself in this string.
  • asynchronous (optional) - Whether to do the call asynchronously (defaults to true)
  • method (optional) - The method to use the execute the call (defaults to POST)

Events

  • onSuccess (optional) - The JavaScript function to call if successful
  • onFailure (optional) - The JavaScript function to call if the call fails
  • on_ERROR_CODE (optional) - The JavaScript function to call to handle the specified error code (eg on404="alert('not found!')")
  • onUninitialized (optional) - The JavaScript function to call if Ajax fails to initialise
  • onLoading (optional) - The JavaScript function to call when the remote function loads the response
  • onLoaded (optional) - The JavaScript function to call when the remote function completes loading the response
  • onComplete (optional) - The JavaScript function to call when the remote function completes, including any updates

Source