Posted on Sunday 21 May 2006
If you've played around with Remoting you probably have encountered instances of mx.remoting.RecordSet, perhaps unknowingly. Here's an outline on using RecordSets, followed by a sample movie which showcases a few of the functions discussed here.
Whenever you return a mysql query result from amfphp or a DataTable from Fluorine, you receive an instance of mx.remoting.RecordSet. In essence, it is an object with an items property, which is an array of objects. The objects have the same key names as the columns from the corresponding query or DataTable. A RecordSet can be directly used as the dataProvider of a list, combo box, or datagrid.
Most of the examples in amfphp so far have directly set the dataProvider of a combo box or datagrid without processing the recordset. In real life, you will often need to do more than just display the data in v2 components. Like arrays, recordsets have a length property. To get an item from the RecordSet, use getItemAt(index). For example:
for(var i = 0; i < rs.length; i++)
{
var item = rs.getItemAt(i);
for(var j in item)
{
trace(j + ': ' + item[j]);
}
}
Again the j's here are the SQL column names. You can also modify an recordset in addition to reading it. addItemAt(index, item) can be used to add an item. This can be useful if you retrieve a list of possible filters, and then addItemAt(0, {label:'(no filter)', data:-1}) to add a (no filter) item. editField, removeItem, removeItemAt round out the bunch, although in practice you will rarely use this.
You can filter a recordset using the appropriately named filter method. Here's how you use it:
var rs2 = rs.filter( function(item) {
return item.name.indexOf('a') == 0;
}
Here rs2 will contain a list of all the items in rs which have a name column starting with a. The filter function can be used for an autocomplete with a few hundred choices: just load all the data at once and filter when the user has entered a few characters. Usually you will use inline functions for filtering recordsets.
Another item of interest: sorting. sortItemsBy(fieldNames: Array, order: String, optionFlags: Number) takes in an array of column names, an order (ASC or DESC) and options (the Array constants like Array.NUMERIC) and sorts the items without making a copy. There are also the sort and sortItems functions which give even more options.
RecordSets can live simultaneously on the server and the client as pageable recordsets. This is a very powerful technique that I'm not going to detail here, but it involves setDeliveryMode and a lot of black magic.
Finally, what with all these wonderful functions, you'll probably want to make your custom components recordset-aware like the v2 components are. This is actually not as hard as it would seem. RecordSets dispatch an event called modelChanged which sends an event object containing an 'eventName' key. This eventName can be addItems, removeItems, updateItems, sort, allRows, fetchRows. These last 2 are used with pageable recordsets. Normally, you should react to the first four by partly or fully invalidating your view. For example, I once created a custom grid display which showed a grid layout of movieclips. The grid listened to updateItems, removeItems and addItems to forward the new data to the child movieclips, while doing fading effects so the transition would be smoother. Pretty sweet.
Here's a sample movie which shows the use of getting items, sorting, and filtering. The php is nothing to write home about, but here it is. The source of the fla can be downloaded here. Note that there is nothing special about the database used; in fact, I pulled it from an old project of mine with a completely different interface.
The documentation for RecordSets is available here.
(This was supposed to be a video tutorial, but Captivate kept crashing on me because I 'only' have 1 GB left on my hard drive, which is filled with excellent music. You have to wonder in what audio codec it records to fill up 1 GB in 10 minutes. Someone get me a copy of Camstasia.)
