JavaScript Remoting for Apex Controllers

JavaScript remoting in Visualforce provides support for methods in Apex controllers to be called via JavaScript.

To use JavaScript remoting in a Visualforce page, you add the request as a JavaScript invocation, which has the following form:

[<namespace>.]<controller>.<method>([params...,] <callbackFunction>(result, event) {

    // callback function logic 
    

}, {escape:true});

where

namespace is the namespace of the controller class. This is required if your organization has a namespace defined, or if the class comes from an installed package.
controller is the name of your Apex controller.
method is the name of the Apex method you're calling.
params is the comma-separated list of parameters that your method takes.
callbackFunction is the name of the JavaScript function that will handle the response from the controller. callbackFunction receives the status of the method call and the result as parameters.
escape specifies whether your Apex method's response should be escaped (by default, true) or not (false).

While the remote method call executes synchronously, it does not wait for the response to be returned. The response is handled asynchronously by the callback function, whenever the response completes. See Handling the Remote Response below for details.

Declaring a Remote Method

In your controller, your Apex method declaration is preceded with the @RemoteAction annotation like this:

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

Your Apex method must be static and either global or public. Globally-exposed remote actions should not perform sensitive operations or expose non-public data. global remote actions may only call other global methods. public remote actions may not be used in global components, or otherwise used in a global scope. Scope escalation will result in a compiler error or, for references which are resolved at runtime, a runtime failure. The following table describes these restrictions in more detail:

`@RemoteAction` Scope	Visualforce Page	Non-Global Component	Global Component	iframe
Global Remote Method	Allowed	Allowed	Allowed	Allowed
Public Remote Method	Allowed	Allowed	Error	Error

When remote actions are accessed via markup that is included indirectly, via components or the <apex:include> or <apex:composition> tags, the scope of the remote method is carried forward into the top level container, that is, the top level item in the inclusion hierarchy, which must abide by scope escalation rules:

	Top Level Container
@RemoteAction Accessed From	Visualforce Page	Non-Global Component	Global Component	iframe
Global Component	Allowed	Allowed	Allowed	Allowed
Non–Global Component	Allowed	Allowed	Only if non-global component doesn't include public remote methods.	Only if non-global component doesn't include public remote methods.
`<apex:include><apex:composition>`	Allowed, within the same namespace; error if namespaces are different, and the included page or its child hierarchy contains public remote methods.	n/a	n/a	Error

Overloading is not permitted; in other words, your remote method can't have the same number of parameters as other methods with the same name. For instance, with the method above, you can't also have a getItemId(Integer objectNumber) method.

Your method can take Apex primitives, collections, typed and generic sObjects, and user-defined Apex classes as arguments. Generic sObjects must have an ID or sobjectType value to identify actual type. Your method can return Apex primitives, sObjects, collections, user-defined Apex classes and enums, SaveResult, UpsertResult, DeleteResult, SelectOption, or PageReference.

Handling the Remote Response

The response to a remote method call is handled asynchronously by the callback function defined in the remote method call. Your callback function will receive as parameters an event object representing the status of the remote call (true on success, false on error), 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.

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

Note

Exceptions caused by JavaScript remoting are logged to the Firebug console, if enabled.

JavaScript Remoting and `<apex:actionFunction>`

The <apex:actionFunction> component also lets you call controller action methods through JavaScript. Here are some differences between the two:

The <apex:actionFunction> tag:
- lets you specify rerender targets
- submits the form
- does not require JavaScript
JavaScript remoting:
- lets you pass parameters
- provides a callback
- requires JavaScript

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

JavaScript Remoting for Apex Controllers

Declaring a Remote Method

Handling the Remote Response

JavaScript Remoting and <apex:actionFunction>

JavaScript Remoting and `<apex:actionFunction>`