API Calls and the AJAX Toolkit

Use the following sections to understand how API calls are used with the AJAX Toolkit. All calls described in the SOAP API Developer's Guide, plus the runTests call documented in the Force.com Apex Code Developer's Guide can be used with the AJAX Toolkit.

Synchronous and Asynchronous Calls with the AJAX Toolkit

The AJAX Toolkit allows you to issue synchronous or asynchronous calls. Asynchronous calls allow the client side process to continue while waiting for a call back from the server. To issue an asynchronous call, you must include an additional parameter with the API call, referred to as a callback function. Once the result is ready, the server invokes the callback method with the result.

API Call Syntax in the AJAX Toolkit

API calls use slightly different syntax in AJAX Toolkit.

Synchronous syntax:

1sforce.connection.method("arg1","arg2", ...);

For example:

1sforce.connection.login("MyName@MyOrg.com","myPassword1");

Asynchronous syntax:

1method("arg1","arg2", ..., callback_method);

For example:

1var callback = {onSuccess: handleSuccess, onFailure: handleFailure};
2function handleSuccess(result) {}
3function handleFailure(error) {}
4sforce.connection.query("Select name from Account", callback);

In this example, onSuccess is the callback function, which will return the results when they are ready.

See Core Calls in the SOAP API Developer's Guide for call usage, arguments, and best practices, but use the AJAX Toolkit syntax for methods you embed in JavaScript.

Because delete is a JavaScript keyword, use deleteIds instead of the API call delete.

Note

Object Functions

Property values can be accessed directly or by using a generic set or get method:

A get function for each field in the object. For example, an Account object has a get("Name") function. This can be used instead of object.Field (for example, account.Name).
A set function for each field in the object. For example, an Account object has a set("Name) function. This can be used instead of object.Field = value.

For example, you can get the value of the Name field from an Account using either of these methods:

account.get("Name")
account.Name
account["Name"]

You can set the value of the Name field from an Account using either of these methods:

account.set("Name", "MyAccount");
account.Name = "MyAccount";
account["Name"]="MyAccount";

For information about processing results, see Processing Results.

Data Types in AJAX Toolkit

The AJAX Toolkit returns all data as strings. If needed, you can convert the data into an appropriate datatype by using one of the functions supplied with the returned object:

getDate maps dates to JavaScript Date.
getDateTime maps dateTime values to JavaScript Date.
getInt maps integer values to JavaScript Int.
getFloat maps float values to JavaScript Float.
getBoolean maps boolean values to JavaScript Boolean.
getArray retrieves arrays of values.
getBase64Binary returns the decoded value of a Base64 binary encoded string. This is typically used for working with documents and attachments. See Working with Base64 Binary Encoded Strings for information about working with Base64 binary encoded strings.

If you request a field whose value is null in a query, the returned value will be null. If you do not request a field, whether the value is null or not, the value is not returned, and is therefore undefined.

The source Context Variable

The AJAX Toolkit provides a context variable, source, which allows you to pass in any context and get it back in the callback method. For an example of how to use source in an error handling context, see Error Handling with the AJAX Toolkit.

Debugging with the AJAX Toolkit

The AJAX Toolkit provides a debugging window that pops up when certain errors are encountered.

You can invoke logging explicitly using the log method. For example, if you wanted to display the debugging window with the value of a variable at a certain point in your client application, you could add this line at the appropriate place:

1sforce.debug.log(myVar);

You can open the debugging window at any point by using this command:

1sforce.debug.open();

Using the Samples

The next two sections contain examples of synchrononous and asynchronous calls.

The AJAX Toolkit provides a debugging window that pops up when certain errors are encountered.

You can invoke logging explicitly using the log() method. For example, if you wanted to display the debugging window with the value of a variable at a certain point in your client application, you could add this line at the appropriate place:

1sforce.debug.log(myVar);

The AJAX Toolkit samples in the following sections use log(). To use the samples in the following sections, add this simple version of the log code before the first use of log:

1function log(message) {
2  alert(message);
3}

You can make log() as sophisticated as you wish.

AJAX Toolkit Developer's Guide

No Results