ASDoc

mx.remoting
Class DataGlue

class DataGlue
extends Object

You use the DataGlue class to format data records for use in a ListBox, ComboBox, or other Flash UI component. The DataGlue methods let you bind RecordSet objects to a UI component. After using DataGlue methods, the RecordSet or other data provider fields are bound to the UI component so that if the data changes, the user interface reflects those changes. You can import the DataGlue class using the following import statement:

   import mx.remoting.DataGlue;

Methods
`static`	`bindFormatFunction( dataConsumer: Object, dataProvider: Object, formatFunction: Function) : Void`Binds a label field and a data field from a data provider, such as a RecordSet object, to a data consumer, such as a ListBox or ComboBox component, and formats the data using a function that you create.
`static`	`bindFormatStrings( dataConsumer: Object, dataProvider: Object, labelString: String, dataString: String) : Void`Provides an easy way to attach fields from a RecordSet, or other data provider, to the `label` and `data` properties of a data consumer component, such as a ListBox or a ComboBox.

Properties
`static`	`version: String` Component version.

Method Detail

bindFormatFunction

static
											 bindFormatFunction(
										dataConsumer:
													Object, dataProvider:
													Object, formatFunction:
													Function)
										 : Void

Binds a label field and a data field from a data provider, such as a RecordSet object, to a data consumer, such as a ListBox or ComboBox component, and formats the data using a function that you create. The label field appears in the data consumer and you can access the data field from the data property when the label field is selected. Use the bindFormatFunction() method when the data from the data provider needs to be formatted in a particular way. In this case, you define a custom function to format the data and specify that function as the formatFunction parameter when you call bindFormatFunction(). This formatFunction function takes a record as a parameter and must return an ActionScript object that contains label and data fields as name:value structures. In the following example, myFormatFunction receives a customer record and returns the label value of "Last 4 digits: " plus the last four digits of the credit card number and a data value of the ID field from the record.

   function myFormatFunction(rec:Object):Object {
     var lastFour:String = rec.cardNum.substr(-4, 4);
     return({label: "Last 4 digits: " + lastFour, data:rec.ID});
   }
   DataGlue.bindFormatFunction(cust_combo, custData, myFormatFunction);

After using the DataGlue.bindFormatFunction() method, you can access the label and data fields that were attached to the data consumer component through its label and data properties. For example, the following statement accesses the data property of the currently selected item in the custCat_cmbo ComboBox:

   var myData:String = cust_cmbo.value;

Use the DataGlue.bindFormatStrings() method when you can attach label and data fields directly from the record set to the data consumer without special formatting requirements

Parameters
    dataConsumer: Object - A ListBox or similar UI component to which you want to bind a data provider, such as a RecordSet object. The data consumer must support data provider objects (that is, have a setDataProvider() method).
    dataProvider: Object - A RecordSet object or other object that implements the standard data provider interface.
    formatFunction: Function - A user-defined function that takes a data record as a parameter. This function must return an ActionScript object that contains the fields Label and Data.

Example
The following example accesses the customerData service and calls the custService.getCustomers() function to retrieve all customers in the Billable category ("B" parameter). It returns the results to the onCustData() function, which calls the DataGlue.bindFormatFunction() function to bind the records to the cust_ListBox component in the Flash user interface. The DataGlue.bindFormatFunction() function calls the formatSales() function to format the TotalSales field for the label value in the ListBox. It returns the Name field from the record as the data value.

   import mx.remoting.Service;
   import mx.services.Log;
   import mx.rpc.RelayResponder;
   import mx.rpc.FaultEvent;
   import mx.rpc.ResultEvent;
   import mx.remoting.PendingCall;
   import mx.remoting.RecordSet;
   import mx.controls.ListBox;
   import mx.remoting.DataGlue;
   
   mx.remoting.debug.NetDebug.initialize(); // initialize the NCD
   // access the customerData service
   var custService:Service = new Service(
     "http://localhost:8300/flashservices/gateway",
     null,
     "customerData",      null,
     null);
   // get Billable (B) customers
   var pc:PendingCall = custService.getCustomers("B");
   pc.responder = new RelayResponder( this, "onCustData", "onCustFault" );
   
   // receive results from getCustomers
   function onCustData( re:ResultEvent ):Void {
     mx.remoting.debug.NetDebug.trace({level:"Debug", 
       message:"onCustData" });
   // use DataGlue.bindFormatFunction() to bind records to cust_ListBox component
   // using formatSales function to format
     DataGlue.bindFormatFunction( cust_ListBox, re.result, formatSales);
   }
   // formatting function TotalSales as the label field after adding decimal point 
   // dollar sign. It returns data field of customer name (rec.Name field).
   function formatSales(rec:Object):Object {
     return{label:"$" + rec.TotalSales + ".00", data:rec.Name};
   }

bindFormatStrings

static
											 bindFormatStrings(
										dataConsumer:
													Object, dataProvider:
													Object, labelString:
													String, dataString:
													String)
										 : Void

Provides an easy way to attach fields from a RecordSet, or other data provider, to the label and data properties of a data consumer component, such as a ListBox or a ComboBox. Simply use the labelString and dataString parameters to specify the fields from the data provider that you want to use for the label and data properties of the data consumer. Enclose the names of fields that come from the data provider in pound signs (#). For example, if you want your ListBox to display the Name and Product Code fields from your Products record set, you could define your label and dataString parameters as "#Name#" and "#Product Code#", respectively, to achieve an entry like Widget R38 in the ListBox. The label field can also be a combination of static text and a RecordSet field, such as "Product: #Name#". If you need to specify only a data field, set the dataProvider property of the data consumer. For information on the dataProvider property, see Using Components Help for the particular data consumer component that you are using. (For example, to find information on the dataProvider property for the ComboBox, select Help > Using Components > ComboBox.dataProvider.) After using the DataGlue.bindFormatSrings() method, you can access the information specified in the labelString and dataString parameters through the label and data properties of the user interface component. For example, the following statement accesses the data property of the currently selected item in the custCat_cmbo ComboBox:

   var myData:String = custCat_cmbo.getSelectedItem().data;

Use the DataGlue.bindFormatFunction() method when the data from the data provider needs to be formatted in a particular way. In this case, you must also define a custom function to format the data and you must specify the name of that function as a parameter when you call bindFormatFunction(). For a sample application that uses the DataGlue.bindFormatStrings() method, see Using the Flash Remoting ActionScript API in the CustomerInfoExampleAPI application.

Parameters
    dataConsumer: Object - A Flash UI component, such as ListBox or ComboBox. The data consumer must support data provider objects, which means that it must have a dataProvider property.
    dataProvider: Object - A RecordSet or other object that implements the DataProvider interface.
    labelString: String - A format string that defines how to format the label that appears in the UI component. The format string is arbitrary text that can contain record field names enclosed in pound (#) signs.
    dataString: String - A format string that specifies the data provider data field that you are attaching to the data consumer component.

Example
The onCategoryData() function is a result handling function from the CustomerInfoFormExampleAPI sample application. It populates a ComboBox in the user interface with the record set it receives as the result of a call to the custService.getCategories() function. The onCategoryData() function calls the DataGlue.bindFormatStrings() method to map the Name and ID fields from the Categories record set to the custCat_cmbo ComboBox in the user interface. The result in the ComboBox is a list of entries such as: Billable B, Prospect P, and so on.

   function onCategoryData( re:ResultEvent ):Void {
   // call trace to document the call to this function
     mx.remoting.debug.NetDebug.trace({level:"Debug", 
         message:"onCategoryData" });
     // call DataGlue.bindFormatStrings to specify label = Name field and 
     // data = ID field
     DataGlue.bindFormatStrings( custCat_cmbo, re.result, "#Name#", "#ID#" );
     custCat_cmbo.addEventListener( "change", onCustCat_Change );
     refreshCustomerData();
   }

For information on adding event listeners, see Using Components Help. To produce a more descriptive label such as "Category P:", you could replace the preceding call to bindFormatStrings() with the following one, which combines the static text "Category" with the ID field from the record set. The result in the ComboBox would be an entry such as: Category P: Prospect.

   DataGlue.bindFormatStrings( custCat_cmbo, re.result, "Category #ID#: #Name#", "#ID#" );

Property Detail

version

static
												 version:
												String

Component version. For internal use only.

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/flashremoting/mx2004/actionscript_api_reference/mx/remoting/DataGlue.html

mx.remoting Class DataGlue

bindFormatFunction

bindFormatStrings

version

mx.remoting
Class DataGlue