# 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", specified in 'options' array)

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')};"
            }        getProvider().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] = []
        }