OReilly Flash Remoting The Definitive Guide Connecting Flash MX Applications To Remote Services Sep 2003 ISBN 059600401X

Method Flash 6 binds a data provider to a data consumer using string replacements DataGlue.bindFormatStringsdataConsumer, dataProvider, Arguments dataConsumer The field that you want to

Method

Flash 6

binds a data provider to a data consumer

using string replacements

DataGlue.bindFormatStrings(dataConsumer, dataProvider,

Arguments

dataConsumer

The field that you want to sort the RecordSet object by.

dataProvider

The direction to sort the recordset "DESC" specifies a

descending sort; anything else is ascending

labelString

The label that will show in the UI component

dataString

The data that will correspond to the label in the UI

component

Description

The DataGlue object contains two methods for binding data to a

UI component The bindFormatFunction( ) method is best used

when the data coming from the recordset or other data provider has to be formatted in a particular way If the data can be used

directly, the bindFormatStrings( ) method is easier to use

formats the data Simply specify the fields to use for the label

and data properties of the data consumer in the method call

Example

The following example code assumes a combo box named

allProducts_cb is present on the main timeline:

#include "NetServices.as"

#include "DataGlue.as"

// Initialize the connection and service objects

if (connected == null) {

connected = true;

NetServices.setDefaultGatewayUrl("http://localhost/flashservices/gateway"); var my_conn = NetServices.createGatewayConnection( );

var myService = my_conn.getService("com.oreilly.frdg.searchProducts", this); }

// The remote getSearchResult( ) method (not shown) returns a recordset

myService.getSearchResult( );

// Display the product names in the combo box Use the product IDs as the data function getSearchResult_Result(result_rs) {

DataGlue.bindFormatStrings(allProducts_cb, result_rs,

'#ProductName#', '#ProductID#');

}

The fields that are utilized in the bindFormatStrings( ) method

(ProductName and ProductID) are surrounded by quotes and

pound signs (#) The pound signs around the RecordSet fields

denote that the field is to be replaced by a field from the data

provider (the RecordSet, in this case).

See Also

3 and Chapter 4

Method

Flash 6

binds a data provider to a data consumer

using a custom function

DataGlue.bindFormatFunction(dataConsumer, dataProvider,

Arguments

dataConsumer

The UI component or other consumer of data to be bound

to a data provider

dataProvider

A RecordSet object or other data provider to be bound to a

data consumer

formatFunction

A custom function that you define that returns an object

with the properties label and data It must accept a single

RecordSet object as a parameter.

Description

The DataGlue object is used to bind a data provider to a data

consumer The most common and useful application of this is to

bind a RecordSet object to a ListBox, ComboBox, or other UI

component that will display the data from the RecordSet The

bindFormatFunction( ) method allows the developer to specify a

function to format the appearance of the data in the UI

component If you don't need to format the data, using

Example

The following example code assumes a combo box named

allProducts_cb is present on the main timeline:

#include "NetServices.as"

#include "DataGlue.as"

// Initialize the connection and service objects

if (connected == null) {

connected = true;

NetServices.setDefaultGatewayUrl("http://localhost/flashservices/gateway"); var my_conn = NetServices.createGatewayConnection( );

var myService = my_conn.getService("com.oreilly.frdg.searchProducts", this); }

// The remote getSearchResult( ) method (not shown) returns a recordset

myService.getSearchResult( );

// Display the product names in the combo box Use the product IDs as the data // The product names are formatted in uppercase for display

function formatDataForBox (theRecord) {

var formatObj = new Object( );

formatObj.label = theRecord.ProductName.toUpperCase( );

formatObj.data = theRecord.ProductID;

return formatObj;

}

// The responder function binds the returned recordset to the combo box

function getSearchResult_Result(result_rs) {

DataGlue.bindFormatFunction(allProducts_cb, result_rs, formatDataForBox);

}

The formatDataForBox( ) function creates an object with two

properties: label and data This function is called by the

The recordset is bound to the combo box, which displays the recordset's capitalized product names in a list and uses the product IDs as the underlying data

See Also

DataGlue.bindFormatStrings( ), the RecordSet class; Chapter 3

RecordSet Class Flash 6

client-side resultset management

myRecordSet.methodName(params)

Methods

addItem( )

Appends a row to the end of the recordset

addItemAt( )

Adds a row to the recordset at the specified index

addView( )

Used to notify an ActionScript object whenever a recordset changes

filter( )

Create a new recordset based on filtering an existing

recordset

getColumnNames( )

Returns a list of column names in the recordset

getItemAt( )

Returns a specific row in the recordset

getItemID( )

Returns the internal item number of the recordset row

Returns the number of records in the recordset

getNumberAvailable( )

Returns the number of records that have been retrieved from the server

isFullyPopulated( )

Returns a Boolean value that tells if the recordset is

populated entirely by the server yet

isLocal( )

Returns a flag that tells if a RecordSet object is associated

with a server

removeAll( )

Removes all records from the recordset

removeItemAt( )

Removes a specified record from the recordset

replaceItemAt( )

Replaces the row at the specified index in the recordset

setDeliveryMode( )

Sets the delivery mode for pageable recordsets

("ondemand", "fetchall", or "page")

setField( )

Replaces a single field in a row with a specified value

Sorts the recordset according to custom criteria

sortItemsBy( )

Sorts the recordset by a specified field

Description

The RecordSet class defines ActionScript objects that can be

created on the client to create a multidimensional array that is indexed sequentially, starting with 0 A RecordSet object mimics

the functionality of a server-side resultset If you return a

resultset from a Flash Remoting method on the server, it will

automatically be cast into a RecordSet object in the Flash

movie Refer to Chapter 5 through Chapter 9 and Appendix A

for datatype conversions on the various platforms

The index of each row of the recordset is a sequential number from 0 to the length of the recordset minus one In other

words, a recordset containing 10 rows has index numbers from

0 to 9 There is also an internal identifier number, which should not be confused with the index number The index number can change if you add or delete rows or sort the recordset The

internal identifier number is a sequential number that is

assigned to each row and remains attached to that row If a row

is deleted, the internal identifying number is not used again and the internal ID numbers of remaining rows does not change (although their index numbers might) Similarly, if a recordset

is sorted, the internal identifiers remain attached to each

individual row The internal identifier can be read with the

getItemId( ) method, or as a property of the recordset row:

myID = myRecordset_rs.getItemAt(0)._ _ID_ _

The RecordSet class is a subclass of the RsDataProviderClass

superclass The RsDataProviderClass.as file is included

automatically when you include the RecordSet.as or

NetServices.as files.

To utilize RecordSet objects, the RecordSet.as file must be

included in the Flash movie This file can be included on its own

if you are not using Flash Remoting, but it is included

automatically when you include the NetServices.as file To

create a client-side RecordSet object from scratch, instantiate it

like so:

var myRecordset_rs = new RecordSet(["First", "Last", "Phone", "Fax", "Email"]);

The ActionScript naming convention for RecordSet objects is to

use _rs at the end of your RecordSet object's variable name.

This ensures that code hints work in the Flash and

Dreamweaver authoring environments

A typical RecordSet object is created by calling a method on the

server that issues a SELECT statement against a database and

returns a resultset The resultset is returned to the Flash movie,

and the resultset is automatically turned into a client-side

RecordSet object The field names in your database query

become the field names in the RecordSet object The object has

many built-in methods that allow the developer to interact with

the recordset as one would on an application server

The RecordSet class is one of the cornerstones of Flash

Remoting, because it allows the seamless integration of

databases into a client-side Flash movie by allowing the

developer to call remote services that return resultsets

Methods of the RecordSet class are discussed at length under "The

RecordSet Object" in Chapter 4 This chapter provides a more formal discussion of each method's syntax, in alphabetical order Consult

Chapter 4 for a different perspective on each method covered here For readability's sake, I use the informal term "recordset" interchangeably

obvious or irrelevant.

Bugs

The initial release of Flash Remoting had a problem with J2EE

resultsets The client-side RecordSet object did not

automatically get created by Flash Remoting Updater 1 fixes the problem

See Also

Chapter 3 and Chapter 4 for general information and Chapter 5

through Chapter 9 for server-specific details

Chapter 3 Client/Server Interaction, UI Components, and RecordSets

The most important aspect of building any applicationand

especially a web applicationis to create a comfortable user

experience If the user is bored, frustrated, or uninterested, she will go elsewhere and probably never return A good Flash

movie can hold a user's attention, but the way in which the user interacts with the web application makes the difference between

an application that is usable and one that just looks nice

One of Flash Remoting's prime uses is to create a user interface that does one of several things:

Allow the user to search a remote site or database

Display information to a user

Collect information from a user

Allow interaction with remote databases or programs

Flash components make it easy to create user interfaces, and Flash Remoting adds features that allow easy connection to

databases and other programs

I learned how to program by pulling apart existing programs and trying to figure out how they worked This was back in

1982, when the hottest computer around was the Commodore

64 My approach was to load an existing program, run it, and then look at the code line by line I would comment each line of the code with my observations of what the program was doing After some practice, I got pretty good at discovering what other people's code did I also got pretty good at writing my own

code

The code was assembly language Although the properties,

methods, and events of modern-day languages make it easy to accomplish complex tasks with one or two lines of code, a

might require hundreds of lines of assembly language Little wonder that I went through 7,000 sheets of tractor-feed printer paper Despite its drawbacks, the flip side of assembly language

is that it gives you access to the core underpinnings of the

software and hardware If you understand the assembly

language, you really understand everything the program does

The goal of Flash Remoting is to take complex tasks and

abstract them so that you, the programmer, can accomplish more with each line of code than was previously possible But saying "it just works" isn't very satisfying to programmers who want to understand Flash Remoting at a deeper level Especially because sometimes it doesn't "just work," a deeper technical understanding can help you solve otherwise vexing problems

The preceding chapters have shown you a few examples of the technology and how to use it Now that Flash Remoting's

concepts are familiar to you, it is a good time to dive more

deeply into the different classes, objects, and components of

Flash Remoting What exactly are NetServices and

Following the discussion of some of Flash Remoting's internals, this chapter explores other topics in depth This chapter

includes many practical details on responder objects and

callback functions, recordset objects, error trapping, and

registering objects for transmission between the client and

server This chapter gives a new understanding of Flash

Remoting, so you can decide when to sit back and enjoy the cruise control and when to tinker under the hood It should be read carefully by all developers, so buckle up

ColdFusion MX

Flash Remoting is supported on a number of different platforms, but perhaps the best supported, simplest, and most popular platform for Flash Remoting is ColdFusion MX The ColdFusion

MX server provides you with three primary means for

implementing the server-side portion of your Flash applications:

1 ColdFusion Markup Language (CFML) pages

ColdFusion Components (CFCs)

Server-Side ActionScript

This chapter covers CFML and CFCs in detail, while Chapter 6

covers Server-Side ActionScript Additionally, this chapter

examines the fundamental differences between using

ColdFusion pages and ColdFusion Components, and how their advantages and disadvantages should influence your application architecture

When Flash Remoting was first introduced, you had no choice but to use either ColdFusion MX (which comes with Flash

Remoting) or purchase Flash Remoting MX for J2EE (Java) or NET from Macromedia The reason for this was that the

protocol used by Flash Remoting, Action Message Format

(AMF), is proprietary to Macromedia and they chose not to

release any specifications about it

Since then, a resourceful programmer named Wolfgang Hamann managed to reverse engineer AMF Soon after AMF was

decoded, an open source project with the goal of creating a

fully compatible PHP-based Flash Remoting gateway was born This project, AMFPHP (http://www.amfphp.org), is well on its way to meeting its goal At the time of this writing, AMFPHP supports connecting Flash to specially defined PHP classes or SOAP-based web services

There are a few other open source projects that have applied Wolfgang's work to other languages These include OpenAMF (http://www.openamf.org), a Java implementation, and FLAP (http://www.simonf.com/flap), a Perl implementation

This chapter covers how to install AMFPHP on a server and write PHP classes that AMFPHP can utilize In addition, this chapter examines a few of the more common uses of PHP with Flash

It's important to note that AMFPHP is a fluid project, so for the final word on its current features be sure to check the

documentation on its web site

Conversion

This appendix documents the conversion of native ActionScript datatypes to and from their nearest server-side equivalent in ColdFusion, Java, C#, Visual Basic, and SOAP