| Before you can use Flash Remoting, you must download and install the Flash Remoting components from the Macromedia site (http://www.macromedia.com). These are non-visual components , with which you never interact directly in any way. After you install them, you can forget about them. However, they are required for creating Flash Remoting applications. In the examples in this chapter, the ColdFusion server accesses the greendept.mdb database through the System DSN (Data Source Name ) greendept . You can create the System DSN with the ColdFusion Administrator.  For step-by-step instructions for adding a System DSN, see "Configuring Data Sources," page 880 , in Chapter 32.
It takes just a few lines of ActionScript to create a Flash Remoting connection with a particular service. After that connection is established, a single line of ActionScript can execute any operation (method or function) offered by the service. Here's the ActionScript needed to set up the Flash Remoting connection with qProducts.cfc, residing on the ColdFusion server: #include "NetServices.as" NetServices.setDefaultGatewayUrl ("http://localhost:8500/flashservices/gateway"); gateway_conn = NetServices.createGatewayConnection(); myService = gateway_conn.getService("greendept.qProducts", this);
NetServices.as is a simple file (less than a dozen lines of code) defining the NetServices class used to create Flash Remoting connections. Note the empty line between the include statement and the rest of the program. It's always a good idea to have an empty line after any include statement; the ActionScript compiler can become confused if you don't. The path "http://localhost:8500/flashservices/gateway" is the URL at which you will connect to the FRG. This may differ for different versions of the gateway. For instance, on a .NET installation, "flashservices/gateway" becomes "flashservices/gateway.aspx" . The flashservices/gateway path is not an actual folder on the ColdFusion server. It is a logical mapping referencing the FRG. It is automatically created by the ColdFusion server. The FRG, in turn , automatically uses the wwwroot folder (for example, c:\CFusionMX\ wwwroot \) as its root. Note that your local server URL may be slightly different from the one shown in the preceding code. In particular, the port number may be something other than 8500. You may also have the option of using 127.0.0.1 instead of localhost . The second-to-the-last line creates a new connection with the FRG. The NetServices class does not have a typical constructor function; you do not create new gateway connections using the new keyword. The createGatewayConnection() method is as close as you'll come to a constructor for Flash Remoting connections. Finally, the last line creates a service ( myService ) that allows the Flash client to interact with the service on the server (qProducts.cfc, in the greendept folder, in this example). Notice that dots are used instead of slashes when specifying the path to the service on the server, and the ".cfc" is left off ( greendept.qProducts ). The qProducts.cfc component is based on the qProducts query in qProducts.cfm in Chapter 13. However, the qProducts query in the CFC selects only ProductID , ProductName , ListPrice and Weight , instead of selecting all the fields in the Products table. The getBooks() function in the CFC simply returns the recordset created by the qProducts query. Here's what qProducts.cfc looks like: <cfcomponent> <cffunction name="getBooks" access="remote" returntype="query" output="false"> <cfquery name="qProducts" datasource="greendept"> SELECT ProductID, ProductName, ListPrice, Weight FROM Products WHERE Category = '13001010000'</cfquery> <cfreturn qProducts> </cffunction> </cfcomponent>
Four ColdFusion tags are used to create this component: The <cfcomponent> tag identifies it as a component. The <cffunction> tag creates the getBooks() function. The <cfquery> tag retrieves records from the greendept database when the getBooks() function is executed. The <cfquery> tag stores the retrieved recordset in the qProducts query. Finally, the <cfreturn> tag returns the qProducts query when the function is executed. To make use of this CFC, you need to do two things in the Flash client: create a callback function to get the result and call the getBooks() function. The result will be an ActionScript object representing the qProducts query. When you get the result, you'll bind it to the dataProvider attribute of a DataGrid object. You use the Flash Remoting service that you created, myService , to execute the getBooks() function, like this: myService.getBooks();
This works because functions in the CFC effectively become methods of myService . To simplify this example, the getBooks() function was designed to take no arguments. However, you can design CFCs that do take arguments, in which case the function call would look something like this: myService.myFunc(arg1,arg2);
For more on creating CFCs with arguments, see "Creating and Using ColdFusion Components (CFCs)," page 903 , in Chapter 33, "ColdFusion Markup Language (CFML)."
The Flash client's callback function for the getBooks() function must have a specific name: getBooks_Result . All we're going to do in the callback function in this example is databinding. Here's what it looks like: function getBooks_Result ( result ) { books_dg.setDataProvider(result); }
In this example, books_dg is the instance name of the DataGrid object. When getBooks() returns a result, getBooks_Result() fires, binding the result to the books_dg.dataProvider attribute, causing the data in the recordset to appear in the DataGrid. In getBooks_rem.fla on the CD accompanying this book, the getBooks() function is called when you click the Get Books button. At that point, the Flash Remoting connection has done its job. After that, you will just work with the data in the DataGrid object. TIP If you want to quickly create a "skeleton" program to create a Flash Remoting connection, choose File, New. Then go to the Templates Tab and select Remoting, Basic Remoting. You can edit the template to reflect the instance name of the components you are using, the name and path of the service you are accessing, and so on.
| 