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

DataGlue.bindFormatStrings( ) Method Flash 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 because you don't have to define a custom function that 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/flashservi var my_conn = NetServices.createGatewayConnection( ); var myService = my_conn.getService("com.oreilly.frdg.searchPr } // The remote getSearchResult( ) method (not shown) returns a r myService.getSearchResult( ); // Display the product names in the combo box Use the product 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 DataGlue.bindFormatFunction( ), the RecordSet class; Chapter 3 and Chapter 4 DataGlue.bindFormatFunction( ) Method Flash 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 DataGlue.bindFormatStrings( ) is more straightforward 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/flashservi var my_conn = NetServices.createGatewayConnection( ); var myService = my_conn.getService("com.oreilly.frdg.searchPr } // The remote getSearchResult( ) method (not shown) returns a r myService.getSearchResult( ); // Display the product names in the combo box Use the product // 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 c function getSearchResult_Result(result_rs) { DataGlue.bindFormatFunction(allProducts_cb, result_rs, format } The formatDataForBox( ) function creates an object with two properties: label and data This function is called by the bindFormatFunction( ) method for each row in the recordset 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 getLength( ) 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 sort( ) 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 class Much of the RecordSet class's functionality comes from its 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", " 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 with the more formal "RecordSet object" where the distinction is 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 Chapter 4 Flash Remoting Internals 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 simple statement like myService.getSearchResults(string) 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 createGatewayConnection( ) and why do they work as they do? 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 Chapter 5 Flash Remoting and 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: 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 Chapter 9 Flash Remoting and PHP 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 Appendix A ActionScript Datatype 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 Chapter 6 Server-Side ActionScript ActionScript has evolved over the years into a highly sophisticated object-based language ActionScript 1.0 is based on the ECMA-262 standard, which was designed to standardize the features of JavaScript across platforms and implementations JavaScript Versions 1.3 and higher conform to this standard, and Flash MX ActionScript conforms closelybut not entirelyto the standard Server-Side ActionScript (SSAS) is Macromedia's way of allowing ActionScript developers to leverage their experience in coding ActionScript to be able to develop server-side services without having to learn a new language like ColdFusion or Java Now you can query databases directly with ActionScript, albeit executed on the server-side and not on the client-side in the Flash Player  ... 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... 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... Chapter 9 Flash Remoting and PHP 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