by Adobe



2 May 2011

Note: Flex Test Drive requires Flex 4.5 SDK and Flash Builder 4.5; download a 60-day trial version of Flash Builder 4.5 before continuing if you haven't already.

Connect to data


<?xml version="1.0" encoding="utf-8"?> <s:Application xmlns:fx="" xmlns:s="library://" xmlns:mx="library://" xmlns:employeeservice="services.employeeservice.*" minWidth="955" minHeight="600"> <fx:Script> <![CDATA[ import mx.controls.Alert; import; protected function empDg_creationCompleteHandler(event:FlexEvent):void { getEmployeesResult.token = employeeService.getEmployees(); } ]]> </fx:Script> <fx:Declarations> <s:CallResponder id="getEmployeesResult"/> <employeeservice:EmployeeService id="employeeService" fault=" + '\n' + event.fault.faultDetail)" showBusyCursor="true"/> </fx:Declarations> <s:Label x="50" y="50" color="maroon" fontSize="20" fontWeight="bold" text="XYZ Corporation Directory"/> <s:Button id="empBtn" x="50" y="100" label="Employees"/> <s:Button id="deptBtn" x="140" y="100" label="Departments"/> <s:DataGrid id="empDg" x="50" y="130" creationComplete="empDg_creationCompleteHandler(event)" requestedRowCount="4" width="650"> <s:columns> <s:ArrayList> <s:GridColumn dataField="lastname" headerText="Last Name" width="110"></s:GridColumn> <s:GridColumn dataField="firstname" headerText="First Name" width="110"></s:GridColumn> <s:GridColumn dataField="title" headerText="Title" width="70"></s:GridColumn> <s:GridColumn dataField="cellphone" headerText="Cell Phone" width="110"></s:GridColumn> <s:GridColumn dataField="email" headerText="Email" ></s:GridColumn> </s:ArrayList> </s:columns> <s:typicalItem> <fx:Object id="id1" cellphone="cellphone1" city="city1" departmentid="departmentid1" email="email1" firstname="firstname1" lastname="lastname1" office="office1" officephone="officephone1" photofile="photofile1" state="state1" street="street1" title="title1" zipcode="zipcode1"></fx:Object> </s:typicalItem> <s:AsyncListView list="{getEmployeesResult.lastResult}"/> </s:DataGrid> </s:Application>


In this tutorial, you retrieve data from a database and display it in your DataGrid. A Flex application does not connect directly to a remote database. Instead, you connect to remote data using a data service written in your favorite web language (PHP, ColdFusion, Java, or any other server-side web technology).
This tutorial shows you how to create a data service that uses Flash Remoting to call methods of a PHP class, a ColdFusion component, or a Java class. The other types of calls are covered in other tutorials  not included in the Flex Test Drive.

Step 1: Create a Flex data service.

Use the Data menu and the Service Wizard to create a service for your application server. For PHP using Flash Builder 4.5 for PHP, select PHP by Zend (see Figure 1); for PHP using Flash Builder 4.5, select PHP; for Java, select BlazeDS and for ColdFusion, select ColdFusion. For PHP and ColdFusion, browse to the service file you put on your application server earlier (see Figure 2 for a PHP example). For Java,  import the employeeService destination, and change the service package to services.employeeservice (see Figure 3).
Create a data service for your application server (PHP example).
Figure 1. Create a data service for your application server (PHP example).
Configure the data service (PHP example).
Figure 2. Configure the data service (PHP example).
PHP developers: Flash Builder uses the Zend Framework to introspect the service  and make Flash Remoting calls. If this is your first time creating a PHP service, Flash Builder will install the Zend Framework.
ColdFusion developers: RDS must be enabled on your server for Flash Builder to create a data service. If you have RDS configured to use a password, you will get an Authentication Required dialog box where you must enter the password or the username and password.
For Java, select the service(s) to import.
Figure 3: For Java, select the service(s) to import.
Java developers: The testdrive application was configured to use RDS with no password (in the web.xml file); if you get an Authentication Required dialog box, select No password required. You are also changing the service package (where the generated service classes will be located) so it matches the location referenced in the solution code, which can be used with PHP, ColdFusion, or Java servers.
Flash Builder introspects the server-side class file and creates a corresponding client-side class with the same operations. You can see your new data service in the Data/Services view (see Figure 4).
Locate your new data service in the Data/Services panel.
Figure 4. Locate your new data service in the Data/Services panel.
Note: Depending upon the application server you are using, some of the symbols and data types you see may be different from those shown in Figure 4.

Step 2: Connect the getEmployees() service operation to the DataGrid.

In Design mode, either drag the operation from the Data/Services view onto the DataGrid or select Bind to Data from the DataGrid context menu and confirm you want to replace the binding with the new service operation. In the Bind To Data dialog box, configure the return type (see Figure 5). For PHP and ColdFusion,
auto-detect it from sample data and have it create an array of Employee objects (see Figure 6). For Java, use the existing Employee[] data type (see Figure 7).
Bind the DataGrid to the getEmployees() operation.
Figure 5: Bind the DataGrid to the getEmployees() operation.
For PHP and ColdFusion, specify the return type for the getEmployees() operation.
Figure 6. For PHP and ColdFusion, specify the return type for the getEmployees() operation.
PHP and ColdFusion developers: Before Flash Builder can bind the results of the operation to a component, it needs to know what to do with the data returned from the operation. You are telling it to create an array of Employee objects so Flash Builder creates an Employee ActionScript class file with matching properties and uses that. You could also write your PHP classes and ColdFusion component methods to return strongly typed objects instead of general objects.
For Java, specify the return type to be the existing data type, Employee[].
Figure 7: For Java, specify the return type to be the existing data type, Employee[].
The DataGrid component has also been updated so that it now has a column for each of the properties contained in the return data objects (see Figure 8).
View the new DataGrid columns.
Figure 8. View the new DataGrid columns.

Step 3: Look at the generated code.

Locate the new files in the Package Explorer and look at the generated code in
The columns property of the DataGrid object is set equal to an ArrayList of GridColumn objects where each GridColumn object has properties to specify what data it should display, how big it should be, what its header text should be, and more. The columns will be displayed in the order in which they are defined.
<s:columns> <s:ArrayList> <s:GridColumn headerText="office" dataField="office"> <s:GridColumn/> <s:GridColumn headerText="departmentid" dataField="departmentid"> <s:GridColumn/> ...
The DataGrid object also has a new creationComplete attribute, which specifies that when the creationComplete event occurs, the empDg_creationCompleteHandler() function is called and the event object is passed to it. The DataGrid creationComplete event is broadcast after the DataGrid has been created and all of its properties are set, including its size and position. The event object passed to the function is an instance of the Event class (in this case a FlexEvent) and has properties containing information about the event that occurred.
<s:DataGrid x="50" y="130" id="empDg" creationComplete="empDg_creationCompleteHandler(event)" requestedRowCount="4">
An instance of your EmployeeService data service is created inside the Declarations block. You place tags for all non-visual objects inside the Declaration tag set. The green color of the tag indicates it is a compiler tag associated with compiler instructions and not an instance of a class.
<employeeservice:EmployeeService id="employeeService" fault=" + '\n' + event.fault.faultDetail)" showBusyCursor="true"/>
The empDg_creationCompleteHandler() function inside the Script block calls the getEmployees() method of this data service. You place all ActionScript code (which can only include property and method declarations) inside the Script compiler tag.
protected function empDg_creationCompleteHandler(event:FlexEvent):void { getEmployeesResult.token = employeeService.getEmployees(); }
When this code is executed, Flash Player makes a call to the server. This happens asynchronously in the background; the user can still interact with the application.
When you make a service call, you need to specify what Flash Player should do when it gets a result or error back from the server. A fault handler was specified for the data service itself and will be used to display errors returned from calls to any of its operations in a pop-up box, an instance of the Alert component.
<employeeservice:EmployeeService id="employeeService" fault=" + '\n' + event.fault.faultDetail)" showBusyCursor="true"/>
To handle successful results, a CallResponder object was created in the Declarations block:
<s:CallResponder id="getEmployeesResult"/>
This object has a lastResult property, which automatically gets populated with the data when it is returned to Flash Player from the server. Now it needs to be associated with the service call.
When a service call is initiated, an instance of the AsyncToken class is created. To associate the CallResponder object with the service call, you set the CallResponder's token property equal to AsyncToken generated at the time the service call is made. Now when data is returned from the server, it is handled by the CallResponder object, which, in addition to getting its lastResult property set, also has a result and fault event for which you can set handlers.
getEmployeesResult.token = employeeService.getEmployees();
Finally, the dataProvider property of the DataGrid is bound to the lastResult property of the CallResponder object. This means that whenever the value of getEmployeesResult.lastResult changes at runtime, the DataGrid's dataProvider property is updated and the DataGrid will repopulate itself with the new data. This could be done as shown here:
<s:DataGrid x="50" y="130" id="empDg" creationComplete="empDg_creationCompleteHandler(event)" dataProvider="{getEmployeesResult.lastResult}">
In the generated code, however, the dataProvider property is instead set equal to an instance of the AsyncListView class and the list property of the  AsyncListView object is bound to the lastResult property of the CallResponder object. The AsyncListView class provides more advanced data handling features (to handle when attempted changes to the data set fail) that will not be covered or used in this test drive. The AsyncListView instance is not placed inside a dataProvider tag set (though it can be) because dataProvider is the default property of the DataGrid and can be left out.
<s:DataGrid ...> <s:columns> ... </s:columns> <s:AsyncListView list="{getEmployeesResult.lastResult}"/> </s:DataGrid>

Step 4: Configure DataGrid columns and run the application.

Select the DataGrid component in Design mode, click the Configure Columns button in the Properties view, and use the wizard (shown in Figure 9) to get the DataGrid to appear as shown in Figure 10. Be sure to set column widths so all the data is displayed.
Figure 10. Customize the DataGrid to appear as shown in this figure.
When you run the application, you should now see data from the database displayed in the DataGrid.
This application contains a single "page" that displays a list of employees. In the next tutorial, you create additional "pages" to view employee details and a list of departments.

Learn more

Refer to the following resources to learn more about this topic:
Documentation: Accessing Data with Flex
Documentation: Using Flex 4.5
Documentation: Using LiveCycle Data Services 3.1
Documentation: Using LiveAdobe ColdFusion 9
Documentation: Tutorials on data access with Flash Builder
ActionScript 3 Reference
Flex Developer Center