AJAX Toolkit Developer Guide

Clouds with binary code floating aboveCloud with binary code floating above

No Results

Search Tips:

  • Please consider misspellings
  • Try different search keywords
AJAX Toolkit Developer Guide
When to Use the AJAX Toolkit
Working with the AJAX Toolkit
Connecting to the API
Embedding API Calls in JavaScript
Processing Results
API Calls and the AJAX Toolkit
API End-of-Life Policy
SOAP Header Options with the AJAX Toolkit
Error Handling with the AJAX Toolkit
Advanced Topics
PDF

Embedding API Calls in JavaScript

After you have made the toolkit available using the procedure in Connecting to the API, you can write the JavaScript code that contains your API calls and processing. Be sure to check the SOAP API Developer Guide for information about each call that you wish to use. The syntax for calls is different in the AJAX Toolkit; for details see API Calls and the AJAX Toolkit.

The following example shows a simple synchronized call that you can issue after connecting. This query returns the Name and Id for every User and writes them to the log.

result = sforce.connection.query("Select Name, Id from User");
  records = result.getArray("records");
 
  for (var i=0; i< records.length; i++) {
    var record = records[i];
    log(record.Name + " -- " + record.Id);
  }
We recommend that you wrap your JavaScript code so that the entire HTML page is rendered by the browser before the code executes, to avoid errors. For example:
<body onload="setupPage();">
     <div id="output"></div>
</body>

When you specify setupPage() in the body onload, the browser initializes all HTML elements before it calls setupPage().

For example, the following code could be added to a Visualforce page to retrieve data:

<script type="text/javascript">
    function setupPage() {
           sforce.connection.query("Select Id, Name, Industry From Account order by Industry",
           {onSuccess : layoutResults,
            onFailure : queryFailed,
            source : {
                      output : document.getElementById("output"),
                      startTime : new Date().getTime()
                     }
           });
       }
</script>

The API interaction in the code above is accomplished in the first line of the setupPage function. A SOQL statement specifies what data to return. For more information about the source context variable, see source Context Variable.

After fetching the data in this example, you should handle error conditions, for example:

function queryFailed(error, source) {
       source.output.innerHTML = "<font color "red">
                An error has occurred: </font> <p>" + error;
       }

For more about error handling, see Error Handling with the AJAX Toolkit.

Use a callback function to handle the results of this asynchronous call. A callback function is a function that is passed by reference to the AJAX Toolkit. The AJAX Toolkit calls the callback function under defined conditions, for example, upon completion. For more information about callback function syntax, see API Calls and the AJAX Toolkit.

For example, the following code verifies that at least one result was returned, and iterates through the result set if it exists:

/**
* This method will be called when the toolkit receives a successful
* response from the server.
* @queryResult - result that server returned
* @source - state passed into the query method call.
*/

function layoutResults(queryResult, source) {

     if (queryResult.size > 0) {
     var output = "";

     //get the records array
     var records = queryResult.getArray('records');

     //loop through the records and construct html string
     for (var i = 0; i < records.length; i++) {
          var account = records[i];
          output += account.Id + " " + account.Name +
          " [Industry - " + account.Industry + "]<br>";
     }

     //render the generated html string
     source.output.innerHTML = output;
     }
}

A suggested best practice is to use JavaScript onFailure as the callback function for failure conditions and JavaScript onSuccess for processing results that are successfully returned.

For more information about embedding API calls in JavaScript with the AJAX Toolkit, especially the differences in syntax and availability of asynchronous calls, see API Calls and the AJAX Toolkit.