JavaScript Remoting for Apex Controllers

Adding JavaScript Remoting to a Visualforce Page

[namespace.]controller.method(
    [parameters...,]
    callbackFunction,
    [configuration]
);

The remote method call executes synchronously, but it doesn’t wait for the response to return. When the response returns, the callback function handles it asynchronously. See Handling the Remote Response for details.

Configuring JavaScript Remoting Requests

{ buffer: true, escape: true, timeout: 30000 }

<script type="text/javascript">

    Visualforce.remoting.timeout = 120000; // Set timeout at page level

    function getRemoteAccount() {
        var accountName = document.getElementById('acctSearch').value;

        // This remoting call will use the page's timeout value
        Visualforce.remoting.Manager.invokeAction(
            '{!$RemoteAction.AccountRemoter.getAccount}',
            accountName, 
            handleResult
        );
    }

    function handleResult(result, event) { ... }
</script>

Override a page-level timeout configuration on a per-request basis by setting the timeout in the configuration object for that request, as described above.

OAuth 2.0 Authentication for JavaScript Remoting

JavaScript remoting requests can use OAuth 2.0 for authentication, instead of requiring a standard username and password login process. OAuth allows cross-application and cross-org integrations that aren’t possible to do securely with standard authentication.

A Visualforce page that uses OAuth for authentication configures it at the page level, and uses OAuth for all JavaScript remoting requests. Other than configuration, using JavaScript remoting is exactly the same.

<script type="text/javascript">

    Visualforce.remoting.oauthAccessToken = <access_token>;

    // ...
</script>

oauthAccessToken is an OAuth authentication token obtained by your page’s code. Obtaining and updating an access token is straightforward OAuth, with one addition. JavaScript remoting OAuth authentication requests the “visualforce” scope, so your token must be generated with this or a scope that contains it, including “web” or “full”. Set scope=visualforce (or “web” or “full”) in your OAuth request.

For information about obtaining access tokens, and using OAuth with the Force.com platform, see Authenticating Remote Access Applications in the Salesforce online help and wiki.developerforce.com/page/Digging_Deeper_into_OAuth_2.0_on_Force.com.

Namespaces and JavaScript Remoting

Visualforce.remoting.Manager.invokeAction(
    'fully_qualified_remote_action', 
     invocation_parameters
);

The fully qualified remote action is a string that represents the complete path to the remote action method, including namespace, base class, and so on: namespace[.BaseClass][.ContainingClass].ConcreteClass.Method. Use $RemoteAction in an expression to automatically resolve the namespace, for example {!$RemoteAction.MyController.getAccount}.

<script type="text/javascript">
function getRemoteAccount() {
    var accountName = document.getElementById('acctSearch').value;

    Visualforce.remoting.Manager.invokeAction(
        '{!$RemoteAction.MyController.getAccount}', 
        accountName, 
        function(result, event){
            if (event.status) {
                document.getElementById('acctId').innerHTML = result.Id
                document.getElementById('acctName').innerHTML = result.Name;
            } else if (event.type === 'exception') {
                document.getElementById("responseErrors").innerHTML = event.message;
            } else {
                document.getElementById("responseErrors").innerHTML = event.message;
            }
        }, 
        {escape: true}
    );
}
</script>

Note

Errors encountered when calling invokeAction are reported only in the JavaScript console. For example, if $RemoteAction finds matching @RemoteAction methods in multiple namespaces, it returns the first matching method and logs a warning to the JavaScript console. If a matching controller or action is not found, the call silently fails and an error is logged to the JavaScript console.

Declaring a Remote Method

@RemoteAction
global static String getItemId(String objectName) { ... }

Your method can take Apex primitives, collections, typed and generic sObjects, and user-defined Apex classes and interfaces as arguments. Generic sObjects must have an ID or sobjectType value to identify actual type. Interface parameters must have an apexType to identify actual type.

Your method can return Apex primitives, sObjects, collections, user-defined Apex classes and enums, SaveResult, UpsertResult, DeleteResult, SelectOption, or PageReference.

Remote Methods and Inheritance

When a @RemoteAction method is looked up or called, Visualforce inspects the page controller’s inheritance hierarchy and finds @RemoteAction methods in the controller’s ancestor classes.

global with sharing class ChildRemoteController 
    extends ParentRemoteController { }
global virtual with sharing class ParentRemoteController 
    extends GrandparentRemoteController { }

global virtual with sharing class GrandparentRemoteController {
    @RemoteAction
    global static String sayHello(String helloTo) {
        return 'Hello ' + helloTo + ' from the Grandparent.';
    }
}

<apex:page controller="ChildRemoteController" >
    <script type="text/javascript">
        function sayHello(helloTo) {
            ChildRemoteController.sayHello(helloTo, function(result, event){
                if(event.status) {
                    document.getElementById("result").innerHTML = result;
                }
            });
        }
    </script>

    <button onclick="sayHello('Jude');">Say Hello</button><br/>
    <div id="result">[Results]</div>
    
</apex:page>

Declaring a Remote Method with Interface Parameters

You can declare @RemoteAction methods with interface parameters and return types, instead of being restricted to concrete classes. This, for example, allows a package provider to package a remote method and associated interface, which subscriber organizations can call from Visualforce pages, passing in their own class that implements the packaged interface.

public class RemoteController {
    public interface MyInterface { String getMyString(); }
    public class MyClass implements MyInterface { 
        private String myString; 
        public String getMyString() { return myString; }
        public void setMyString(String s) { myString = s; }
    }
    
    @RemoteAction
    public static MyInterface setMessage(MyInterface i) {
        MyClass myC = new MyClass();
        myC.setMyString('MyClassified says "' + i.getMyString() + '".');
        return myC;
    }
}

Visualforce.remoting.Manager.invokeAction(
    '{!$RemoteAction.RemoteController.setMessage}',
    {'apexType':'thenamespace.RemoteController.MyClass', 'myString':'Lumos!'}, 
    handleResult
);

RemoteController.setMessage(
    {'apexType':'c.RemoteController.MyClass', 'myString':'Lumos!'}, 
    handleResult
);

Handling the Remote Response

The response to a remote method call is handled asynchronously by the callback function provided in the remote method call. Your callback function will receive as parameters an event object representing the status of the remote call, and the result object returned by the remote Apex method. Your function can update information and user interface elements on the page based on the data returned.

Apex primitive data types returned by result—such as strings or numbers—are converted to their JavaScript equivalents. Apex objects that are returned are converted to JavaScript objects, while collections are converted to a JavaScript array. Keep in mind that JavaScript is case-sensitive, so id, Id, and ID are considered different fields.

As part of a JavaScript remote call, if the Apex method response contains references to the same object, the object won't be duplicated in the returned JavaScript object, and instead, the rendered JavaScript object will contain references to the same object. An example is an Apex method which returns a list that contains the same object twice.

By default, the response of the remote call must return within 30 seconds, after which the call will time out. If your request needs longer to complete, configure a longer timeout, up to 120 seconds.

The response of the remote call has a maximum size of 15 MB.

Note

Keep your JavaScript console open during development when using JavaScript remoting. Errors and exceptions encountered by JavaScript remoting are logged to the JavaScript console, if enabled, and are otherwise silently ignored.

When a @RemoteAction method throws an exception due to a programming error or other failure, the Apex stack trace is returned to the browser. Inspect the stack trace in a JavaScript debugger console or use it in the error handling of your response callback function. Here’s a callback function that simply displays the stack trace when there’s an exception:

<script type="text/javascript">
function getRemoteAccount() {
    var accountName = document.getElementById('acctSearch').value;

    Visualforce.remoting.Manager.invokeAction(
        '{!$RemoteAction.MyController.getAccount}', 
        accountName, 
        function(result, event){
            if (event.status) {
                document.getElementById('acctId').innerHTML = result.Id
                document.getElementById('acctName').innerHTML = result.Name;
            } else if (event.type === 'exception') {
                document.getElementById("responseErrors").innerHTML = 
                    event.message + "<br/>\n<pre>" + event.where + "</pre>";
            } else {
                document.getElementById("responseErrors").innerHTML = event.message;
            }
        }
    );
}
</script>

JavaScript Remoting and <apex:actionFunction>

In general, <apex:actionFunction> is easier to use and requires less code, while JavaScript remoting offers more flexibility.