Getting Started with the Force.com Toolkit for Adobe AIR and Flex

Getting Started with the Force.com Toolkit for Adobe AIR and Flex

Abstract

The Force.com Toolkit for Adobe AIR and Flex lets you develop Flex and AIR applications and components using Adobe Flex Builder that interact with the Force.com platform. In this article we'll describe how to use the toolkit to build a simple application that shows a list of accounts held within a Force.com environment. You can also download the Adobe Flash Builder for SalesForce alternatively

What You Need to Get Started

  • First, you'll need a copy of Adobe Flex Builder - you can download a trial from Adobe's site.
  • Second, you'll need a Force.com environment in which to build. See this article for more information about environments. The recommended method is to obtain a Developer Edition account which you can sign up for for free. This article will use the Contact object within this environment.
  • Next, you'll need the toolkit itself. The Force.com Toolkit for Adobe Flex and AIR is an open-source project developed by Adobe and salesforce.com. You can download it from Code Share. The toolkit consists of a ZIP file containing both the source code, the API documentation and the compiled ActionScript libraries.

Importing the Library Into Your Project

You'll need to import the associated library into your Flex Builder project to start using the toolkit. You can find the libraries in the bin folder of the toolkit ZIP file. You'll need force-flex.swc if you're building a browser-based Flex application or force-air.swc if you're building a desktop AIR application. To import the toolkit library into your project, you'll need to place it in your project's libs folder or make an explicit reference to it via the Flex Build Path screen of your project's properties dialog.

The Connection Object

The main class within the toolkit is the Connection class. This class gives you access to all the key Force.com operations such as login, query and update. You'll need to create an instance of this class and keep that instance alive for the duration of your communication with Force.com. The easiest way to create an instance of the class is to declare it in MXML like this: 

<salesforce:Connection id="force"/>

The salesforce namespace should automatically get filled in for you by the IDE but if it doesn't you can add the following attribute to your application MXML's root element: 

xmlns:salesforce="http://www.salesforce.com/"

Alternatively you can create an instance of the class directly through ActionScript - the fully-qualified name is com.salesforce.Connection.

Logging Into Force.com

Before you can really accomplish anything with Force.com you must authenticate yourself by logging in. This is done via the login() method of the Connection object. It takes a LoginRequest object as a parameter. You'll need to create and fill in this LoginRequest object with either a Force.com username and password or an existing session ID and server URL if you're going to be accepting an existing session from Force.com.

You also need to provide a responder object because all operations with the toolkit are asynchronous. The responder object represents your handler functions for success or failure of the operation. Below is a sample of a typical login: 

import com.salesforce.objects.LoginRequest;
import com.salesforce.AsyncResponder;
...
var lr:LoginRequest = new LoginRequest();
lr.username = "my username";
lr.password = "my password"+"access token";  // password is password appended with access token.     (to get security token, go to setup -> "my personal information" -> "reset security token".)
lr.callback = new AsyncResponder(loginSuccess);
force.login(lr);

Note that the force variable above is an instance of the previously-mentioned Connection object. Also when we create the AsyncResponder object we only pass in one function name which is the success handler. We can optionally pass in a second parameter which is the name of the failure handler function.

You then need to implement the loginSuccess handler. You will receive a LoginResult object as an argument but you typically don't need to do anything with this object. 

private function loginSuccess(result:LoginResult):void 
{
	trace("I'm logged in!");
}

Performing a Query

After a successful login, you can then use the Connection object to retrieve data from Force.com. This is done via the query method. This method takes two parameters: the SOQL query text as a string, and an AsyncResponder to handle the results. A typical pattern would be to make the query call within the login success handler as follows: 

private function loginSuccess(result:LoginResult):void
{
	force.query("SELECT Id, LastName FROM Contact", new AsyncResponder(querySuccess));
}
...
private function querySuccess(result:QueryResult):void
{
	trace("I found " + result.size + " records!");
}

The number of records returned from a query can be found by the size property of the QueryResult object passed into your handler. The actual records themselves can be accessed via the records property which is an ArrayCollection. A simple way to see the results is to set the dataProvider property of a DataGrid to this records property value. You should see something like this:

Image:flex_results.jpg

Each object in the records collection is an SObject (com.salesforce.objects.SObject) with dynamic properties that map to the fields defined on those records in Force.com.

Sample Code

If you'd like to see the fully completed sample code for that we've been discussing in this article, you can grab it here and copy and paste into your IDE to try it out.

Other Operations

There are many other operations available such as create and update that you can take advantage of. They generally all work with the same pattern of making the method call passing in an AsyncResponder then implementing the success (and optionally the failure) handlers.

References

Retrieved from "http://wiki.developerforce.com/index.php/Getting_Started_with_the_Force.com_Toolkit_for_Adobe_AIR_and_Flex"