# remoteFunction

## Purpose

Creates a remote javascript function that can be assigned to a DOM event to call the remote method

## 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:

    $('mydiv').onclick = <g:remoteFunction action="show" id="1" />

Example as a method call in GSP only:

    <select onchange="${remoteFunction(action:'bookbyname',update:[success:'great', failure:'ohno'], params:''bookName=' + this.value' )}">
        <option>first</option>
        <option>second</option>
    </select>

Example changing the asynchronous option to false:

    <select from="[1,2,3,4,5]}" onchange="${remoteFunction(action:'bookbyname', update:[success:'great', failure:'ohno'], options=[asynchronous:false]}" />

## 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
- `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, specified in 'options' array)
- `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 remoteFunction = { attrs  ->
    		// before remote function
    		def after = ''
    		if(attrs["before"])
    			out << "${attrs.remove('before')};"
    		if(attrs["after"])
    			after = "${attrs.remove('after')};"		def p = getProvider()
    		p.doRemoteFunction(owner,attrs,out)
    		attrs.remove('update')
    		// after remote function
    		if(after)
    		   out <<  after
        }    private setUpRequestAttributes(){
            if(!request[INCLUDED_JS]) request[INCLUDED_JS] = []
    		if(!request[INCLUDED_LIBRARIES]) request[INCLUDED_LIBRARIES] = []
        }