# remoteLink

## Purpose

Creates a link that calls a remote function when clicked

## Examples

Example controller for an application called `shop`:

    class BookControlller {
         def list = {
    	    [ books: Book.list( params ) ]
    	 }
         def show = {
    	    [ book : Book.get( params['id'] ) ]
         }
         def bookByName = {
    	     [ book : Book.findByName( params.bookName ) ] }
    	 }

Example usages for above controller:

    <g:remoteLink action="show" id="1">Test 1</g:remoteLink><g:remoteLink action="show" id="1" update="[update:'success',failure:'error']"
        on404="alert('not found');">Test 2</g:remoteLink><g:remoteLink action="show" id="1" update="success"
        onLoading="showSpinner();">Test 3</g:remoteLink><g:remoteLink action="show" id="1" update="success"
        params="[sortBy:'name',offset:offset]">Test 4</g:remoteLink>

As a method call in GSP:

    my link = <%= remoteLink( action:'show', id:1,
      update:'success', onFailure:'showError();' )
      { "this is the link body" } %>

## Description

Attributes

- `action` (optional) - the name of the action to use in the link, if not specified the default action will be linked
- `controller` (optional) - the name of the controller to use in the link, if not specified the current controller will be linked
- `id` (optional) - The id to use in the link
- `fragment` (optional) - The link fragment (often called anchor tag) to use
- `mapping` (optional) - The named URL mapping to use to rewrite the link
- `params` (optional) - a map containing request parameters
- `update` (optional) - Either a map containing the elements to update for 'success' or 'failure' states, or a string with the element to update in which cause failure events would be ignored
- `before` (optional) - The javascript function to call before the remote function call
- `after` (optional) - The javascript function to call after the remote function call
- `asynchronous` (optional) - Whether to do the call asynchronously or not (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 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

## Source

Show Source

    def remoteLink = { attrs, body ->
            out << '<a href="'        def cloned = deepClone(attrs)
            out << createLink(cloned)        out << '" onclick="'
            // create remote function
            out << remoteFunction(attrs)
            attrs.remove('url')
            out << 'return false;"'        // handle elementId like link
            def elementId = attrs.remove('elementId')
            if (elementId) {
                out << " id=\"${elementId}\""
            }        // process remaining attributes
            attrs.each { k,v ->
                out << ' ' << k << "=\"" << v << "\""
            }
            out << ">"
            // output the body
            out << body()        // close tag
            out << "</a>"
        }