Object Functions and Data Types in AJAX Toolkit

Object Functions

A get function for each field in the object.

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

A set function for each field in the object.

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

Data Types

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.

Quick Link to parent document: Working with the AJAX Toolkit

Processing results obtained from API calls in Javascript

We can get the results by using these two API calls:

• Query()
  • QueryResult = sforce.connection.query(string queryString);
• QueryMore()
  • QueryResult = sforce.connection.query(QueryLocator queryLocator);

Executes a query against the specified object and returns data that matches the specified criteria.

QueryResult has following 4 properties:

• queryLocator
• done
• records
• size

Ponits to remember

• Default query result size = 500 rows
• If the query results exceed 500 rows, queryMore() call and a server-side cursor(queryLocator) to retrieve additional rows in 500-row chunks.
• You can increase the default size up to 2,000 in the QueryOptions header.
  • connection.setQueryOptions(250);

queryMore() and queryLocator

1. var result = sforce.connection.query("select name, id from account");  
2. var queryMoreFlag = true;  
3. while (queryMoreFlag) {  
4.      var records = result.getArray("records");  
5.      for (var i = 0; i < records.length; i++) {  
6.      //process records[i]  
7.      }  
8.      if (result.getBoolean("done")) {  
9.           queryMoreFlag = false;  
10.      } else {  
11.      result = sforce.connection.queryMore(result.queryLocator);  
12.      }  
13. }  

QueryResultIterator()

The AJAX Toolkit provides the QueryResultIterator object so that you can easily iterate through results without invoking queryMore and queryLocator.

1. var result = sforce.connection.query("select id, name from account");  
2.      var it = new sforce.QueryResultIterator(result);  
3.      while (it.hasNext()) {  
4.           var account = it.next();  
5.           sforce.debug.log(account.Name);  
6.     }  

Quick Link to parent document: Working with the AJAX Toolkit

Embedding API Calls in JavaScript

• Synchronous Call

• syntax:

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

                             e.g.

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

• An Example showing How to Make Synchronous calls with AJAX Toolkit

• Asynchronous call

• Asynchronous calls allow the client side process to continue, 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.

• syntax:

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

                             e.g.

                             var callback = {onSuccess: handleSuccess, onFailure: handleFailure};

                             function handleSuccess(result) {}

                             function handleFailure(error) {}

                             sforce.connection.query("Select name from Account", callback);

• An Example showing How to Make Asynchronous calls with AJAX Toolkit

Quick Link to parent document: Working with the AJAX Toolkit

Connecting to the AJAX Toolkit API

The first portion of any JavaScript code that uses the AJAX Toolkit must make the toolkit available to the JavaScript code.

• For Visualforce pages or any source other than a custom onclick JavaScript button, specify a <script> tag that points to the toolkit file:

  <apex:page>

  <script src="../../soap/ajax/29.0/connection.js" type="text/javascript"></script>

  ...

  </apex:page>

•   For a custom onclick JavaScript button, specify the login call to log into the API:

  {!RequireScript("/soap/ajax/29.0/connection.js")}

  sforce.connection.login("username", "password");

  ...

.

After this script executes,the toolkit is loaded and a global object, sforce.connection, is created. This object contains all of the API calls and AJAX Toolkit methods, and manages the session ID.

Quick Link to parent document: Working with the AJAX Toolkit

When to Use the AJAX Toolkit

The following are examples of appropriate uses:

• Display or modify a single record.

• Display two or three fields from many records.

• Perform one or more simple calculations, then update a record.

The following are examples of scenarios that require case-by-case analysis:

• Update more than 200 records.

• Update records that are unusually large. For example, what happens if the user clicks the browser stop button?

• Recalculate a complex value for more than 200 records.

Valid reasons behind:

• The larger the data set returned, the more time it will take to construct and de-construct a SOAP message, and as the size of an individual record gets larger, the impact on performance becomes greater.
• Also, as more HTML nodes are created from the data, the potential for poor performance increases. Because browsers are not efficient, careful consideration needs to be given to browser memory management if you intend to display a large amount of data.

Quick Link to parent document: Working with the AJAX Toolkit