In any GUI tool, one of the most popular components is the one that shows data in a table format like JTable in Java or Datawindow in PowerBuilder. The Adobe Flex 2 version of such a component is called DataGrid. In any UI framework, the robustness of such a component depends on formatting and validating utilities as well as a whole suite of data input controls: CheckBoxes, ComboBoxes, RadioButtons, all sorts of Inputs, Masks, and so on. Using theatrical terminology, the role of the king is played by his entourage. Practically speaking, touching up the DataGrid is touching up a large portion of the Flex framework.
We'll start by upgrading the standard DataGrid to a "destination-aware" control capable of populating itself. Next, we'll look at the task of formatting DataGrid columns and that would naturally lead us to a hidden treasury of the Flex DataGrid - the DataGridColumn, which, once you start treating it like a companion rather than a dull element of MXML syntax, can help you do truly amazing things.
After setting the stage for the DataGrid's satellite controls, we'll lead you through making a professional library with a component manifest file and namespace declaration that supports flexible mappings of your custom tags to the required hierarchy of implementation classes.
Making DataGird Destination-Aware
Introducing Flex remoting substantially increased the size of our application code. Imagine a real-world application with two-dozen different ComboBoxes or DataGrids. If we put all the relevant RemoteObjects in a single application file it will become unmanageable in no time. For similar reasons, any decent sized application is usually partitioned into different files.
As far as partitioning goes, there's a compelling argument to encapsulate instantiation and interoperation with RemoteObject inside the visual component, making it a destination-aware component, if you will. Embedding a Remote Object directly into the DataGrid will make it fully autonomous and reusable. This design approach sets application business logic free from low-level details like mundane remoting.
The concept of destination-aware controls eliminates the tedious effort required to populate your controls with Remoting or DataServices-based data. Here's how an MXML application with a destination-aware DataGrid might look if we apply the familiar remoting destination com_theriabook_composition_EmployeeDAO:
<!-- DestinationAwareDataGridExDemo.mxml-->
<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx=http://www.adobe.com/2006/mxml layout="vertical"
xmlns:fx="com.theriabook.controls.*">
<fx:DataGridEx id="dg"
destination="com_theriabook_composition_EmployeeDAO"
method="getEmployees" creationComplete="dg.fill()"/>
</mx:Application>
In Listing 1 we have sub-classed the standard Flex DataGrid.
The data are coming from a server-side database with the help of a Java object called EmployeeDAO. If we run the application, our screen will show the grid of employee records in its default formatting:. (See Figure 1).
Formatting with labelFunction
We have just looked at the default data formatting provided by DataGrid out-of-the-box. The easiest way to improve column formatting is by supplying a labelFunction for each column that requires extra attention:
<mx:DataGridColumn dataField="PHONE" labelFunction="phoneLabelFunction" />
Once the labelFunction is declared it automatically gets called by the DataGrid, which supplies the appropriate data item plus information about the column so that you can technically apply one function to more than one column. As far as the formatting techniques themselves, Flex offers plenty of pre-defined formatters, which can be used out-of-the-box or customized to your specific needs. For instance, to format Social Security numbers (SS_NUMBER), we could have used mx.formatters.SwitchSymbolFormatter to create the following function:
import mx.formatters.SwitchSymbolFormatter;
private var sf:SwitchSymbolFormatter;
private function ssnLabelFunction(item:Object, column:DataGridColumn):String {
if (!sf) {
sf = new SwitchSymbolFormatter();
}
return sf.formatValue("###-##-####", item["SS_NUMBER"]);
}
Then inside the DataGridColumn we can mention this function name:
<mx:DataGridColumn dataField="SS_NUMBER" labelFunction="ssnLabelFunction" />
Similarly, in Listing 2 we can apply the same technique to the PHONE field setting the formatString to (###)###-####.
Figure 2 shows how our formatting looks on the screen.
Formatting with Extended DataGridColumn
The labelFunction formatting does the job. The price tag is hard-coding labelFunction(s) names in the DataGridColumn definitions. If you packaged a set of label functions in the class mydomain.LabelFunction your column definitions might look like this:
<mx:DataGridColumn dataField="PHONE" labelFunction="mydomain.LabelFunctions.phone" />
<mx:DataGridColumn dataField="SS_NUMBER" labelFunction=" mydomain.LabelFunctions.ssn" />
A more pragmatic approach is to provide the formatString as an extra attribute to the DataGridColumn and have it encapsulate the implementation details. We're talking of the following alternative:
<fx:DataGridColumn dataField="PHONE" formatString="phone" />
<fx:DataGridColumn dataField="SS_NUMBER" formatString="ssn" />
Implementing such syntax is within arm's reach. We just have to extend - well, not the arm, but the DataGridColumn so that instead of mx:DataGridColumn we would use our, say, fx:DataGridColumn. The mx.controls.dataGridClasses.DataGridColumn is just a respository of styles and properties to be used by the DataGrid. In the Flex class hierarchy it merely extends CSSStyleDeclaration. Nothing prevents us from extending it further and adding an extra attribute. In the case of formatString the setter function will delegate assigning the labelFunction to the helper FormattingManager:
public class DataGridColumn extends mx.controls.dataGridClasses.DataGridColumn {
public function set formatString( fs:String ) : void{
FormattingManager.setFormat(this, fs);
}
}
Wait a minute, where did the FormattingManager come from? We'll get to the implementation of this class later. At this point, we have to eliminate the possible naming collision between our to-be-made DataGridColumn and the standard mx.controls.dataGridClasses.DataGridColumn.
Introducing the Component Manifest File
Up till now we've been keeping folders with classes of our custom components under the folder of application MXML files. To reference these components we've been declaring namespaces pointing to some hard-coded, albeit relative paths, such as xmlns:lib="com.theriabook.controls.*" or xmlns="*". The problem with this approach is that these namespaces point to one folder at a time. As a result, we either end up with multiple custom name spaces or we have a wild mix of components in one folder.
To break the spell and abstract the namespace from the exact file location we need to use the component manifest file. Component manifest is an XML file that allows mapping of component names to the implementing classes. Below is the example of component manifest, which combines our custom DataGrid and DataGridColumn located in different folders:
<?xml version="1.0"?>
<componentPackage>
<component id="DataGrid" class="com.theriabook.controls.DataGrid"/>
<component id="DataGridColumn"
class="com.theriabook.controls.dataGridClasses.DataGridColumn"/>
</componentPackage>
To benefit from using this component manifest you have to compile your components with the compc or use the Flex Library project. To be more specific, you have to instruct compc to select the URL that your application can use later in place of the hard-coded folder in the xmlns declaration. So we'll create a new FlexLibrary project - theriabook, where we'll put the theriabook-manifest.xml containing the XML above and set the relevant project properties, as shown in Figure 3.
Now we can move DataGrid from our application project to theriabook and replace xmlns:fx="com.theriabook.controls" with xmlns:fx="http://www.theriabook.com/2006" provided that our application project will include a reference to theriabook.swc. As a result our application will reference fx:DataGrid and fx:DataGridColumn irrespective to their physical location.
Having done that, let's get back to the custom DataGridColumn.
More on Customizing the DataGridColumn
We'll put
our DataGridColumn in the dataGridClasses subfolder as a sign of our
respect for the well-thought-out directory structure of the Flex
framework:
As mentioned above, the "dirty" job of locating and assigning the proper label function has been delegated to the helper class FormattingManager. This class, presented in Listing 4, should be put in our theriabook project.
Tada! And the winner is...the developer. Once we add theriabook.swc (with DataGrid, DataGridColumn, and FormattingManager) to the library path, the application code gets reduced to Listing 5.
Improving FormattingManager
In the previous
examples we've used SwitchSymbolFormatter for both phone and ssn
formatting. As soon as we start formatting numbers or currency values,
it's natural to use NumberFormatter or CurrencyFormatter - descendants
of mx.formatters.Formatter. In fact, Flex offers a dedicated formatter
even for the phone formatting.
While SwitchSymbolFormatter derives from Object, all the rest of the formatters descend from Formatter. By encapsulating this specific of SwitchSymbolFormatter in the custom class MaskFormatter we'll help ourselves in basing the next version of FormattingManager entirely on Formatters as in Listing 6.
Look how this MaskFormatter simplifies our FormattingManager: we can replace all the private methods with an anonymous function, as shown in Listing 7. Please note that the reference to the appropriate formatter is preserved with the closure.
The testing application FormatStringDemo is in Listing 8. If you run it, the DataGrid dg will be formatted as shown in Figure 4:
Let's focus on the hard-coding that we allowed in case of the money value:
case "money":
formatter = new CurrencyFormatter();
CurrencyFormatter(formatter).precision=2;
break;
This hard-coding reflects, perhaps, the most "popular" case. But what if we want to have the full advantage of the properties of the corresponding formatter, such as precision, in case of CurrencyFormatter? To address these cases we're going to introduce one more fx:DataGridColumn property - formatData. Here's how it will be used in the application MXML:
<fx:DataGridColumn dataField="SALARY" >
<fx:formatData>
<mx:Object formatString="money" precision="0"/>
</fx:formatData>
</fx:DataGridColumn>
The elegance of MXML lets us implement this extension with just a few lines of extra code in com.theriabook.controls.dataGridClasses.DataGridColumn:
public function set formatData(fd :Object) : void{
FormattingManager.setFormat(this, fd);
}
Then, to accommodate the change on the FormattingManager side, we'll iterate through all the properties of the formatData object and attempt to assign them to the appropriate properties of the formatter with an emphasis on the word appropriate. The MXML compiler isn't going to help us check the properties of the unsealed <mx:Object> against the properties of the formatter. Accordingly, to protect ourselves from the no-such-property-exceptions, we surround property assignments with try/catch:
public static function setFormat(
dgc:mx.controls.dataGridClasses.DataGridColumn,
formatData:Object
):void {
. . . . .
if (!(formatData is String)) {
for (var property:String in formatData) {
try {
formatter[property] = formatData[property];
} catch (err:Error) {
// Property does not match formatter type
}
}
}
. . . . .
}
The complete listing of renewed FormattingManager is in Listing 9. While maintaining your own framework, you would transform this class to accommodate your requirements
Finally, Listing 10 has the sample application to test our changes, FormatDataDemo.
When you run the application it will produce the DataGrid shown in Figure 5.
We'll continue beefing up our custom DataGridColumn after a short detour into CheckBox and RadioButton controls.
CheckBox as a Drop-In Renderer
As we warned the
reader at the beginning of this article, DataGrids rarely come alone.
In this section we're going to suggest customizimg the CheckBox, which
will help us illustrate custom DataGridColumns from a different
perspective.
The state of a CheckBox control is managed by the Boolean property selected. At the same time, many business systems use either Y/N or, sometimes, 0/1 flags. As a result, translating business-specific values into selected and vice versa burdens the application code. Listing 11 presents the custom CheckBox, which supports application-specific on and off values along with the current value.
So, using this CheckBox, we could have written:
<fx:CheckBox value="Y" onValue="Y" offValue="N" />
to have selected CheckBox, or
<fx:CheckBox value="N" onValue="Y" offValue="N" />
to set selected to false.
DataGridColumn as ItemRenderer's Knowledge Base
Now let's get back to the DataGrid world. What if we wanted to use our
CheckBox as the DataGrid item renderer? Here's the suggested use case
example:
<fx:DataGridColumn dataField="BENE_DAY_CARE"
itemRenderer="com.theriabook.controls.CheckBox" >
</fx:DataGridColumn>
Obviously, we need to modify the CheckBox more to take care of the value within the data setter:
override public function set data(item:Object):void
{
super.data = item;
if( item!=null ) {
value = item[DataGridListData(listData).dataField];
}
}
But how will we communicate the offValue and onValue properties to our CheckBox-turned-itemRenderer? Ideally, we would need something like:
<fx:DataGridColumn dataField="BENE_DAY_CARE"
itemRenderer="com.theriabook.controls.CheckBox" >
<fx:extendedProperties>
<mx:Object onValue="Y" offValue="N" />
</fx:extendedProperties>
</fx:DataGridColumn>
Flex creators thought of this in advance. An object referenced by itemRenderer is not a CheckBox but rather an instance of mx.core.ClassFactory wrapped around the CheckBox. The mechanism of mx.core.ClassFactory allows Flex to generate instances of another class - in our case com.theriabook.controls.CheckBox. Importantly, each instance created by the factory is assigned identical properties borrowed from the properties property of the factory object. Accordingly, all we have to do is pass the value of the extendedProperties as the properties of the itemRenderer as shown in Listings 12.
The test application, ExtendedPropertiesDemo, is in Listing 13. When you run it, it produces the data grid shown in Figure 6.
We should have mentioned the alternative run-of-the-mill approach with inline itemRenderer. It's in Listing 14.
Arguably, the extendedProperties approach is more efficient, since it absolves MXML of generating an extra nested class (mx:Component) for each column of this kind and we've introduced you to yet another mean of customizing a DataGridColumn. We'll continue building on top of it in the following sections.
Nitpicking CheckBox
There are some additional
remarks that we ought to add to our CheckBox implementation at this
point. The first one is related to the horizontal alignment of the
CheckBox. Instincts tell us that label-free checkbox should be centered
in the column, rather than stuck in the leftmost position. At first,
you may try the textAlign style of the DataGridColumn to no avail. Then
you may resort to another run-of-the-mill approach to center the
Checkbox by putting it inside a container, such as HBox. Here's the
performance-based advice endorsed by Flex Framework engineers: avoid
containers inside the datagrid cell at any reasonable cost. In
particular, instead of using HBox, why not sub-class the CheckBox and
override the updateDisplayList method? It gets quite natural once
you've stepped on this path, so we'll add the code shown below to our
CheckBox (the complete code of com.theriabook.controls.CheckBox is in
Listing 15):
import mx.core.mx_internal;
use namespace mx_internal;
. . . .
override protected function updateDisplayList(
unscaledWidth:Number, unscaledHeight:Number):void
{
super.updateDisplayList(unscaledWidth, unscaledHeight);
if (currentIcon) {
var style:String = getStyle("textAlign");
if ((!label) && (style=="center") ) {
currentIcon.x = (unscaledWidth - currentIcon.measuredWidth)/2;
}
}
}
Please note the use of namespace mx_internal. It's required so the reference to currentIcon visualizes the checkbox picture, since the currentIcon, the child of the original CheckBox, is originally scoped as mx_internal.
Now we modify the testing application to include textAlign="center":
<fx:DataGridColumn dataField="BENE_DAY_CARE" textAlign="center"
itemRenderer="com.theriabook.controls.CheckBox" >
<fx:extendedProperties>
<mx:Object onValue="Y" offValue="N" />
</fx:extendedProperties>
</fx:DataGridColumn>
And, when we run it, all checkboxes are in their proper places:
The second nitpicking point is related to undefined as the possible value of a property. Under our current business scenario, we can assume that some of the employees are not eligible for day care benefits, and relevant items in the dataProvider's collection are lacking BENE_DAY_CARE property, which can be expressed as item.BENE_DAY_CARE=="undefined" for dynamic items. (See Figure 7)
Does it make sense to show checkboxes for non-eligible employees? Perhaps, it doesn't. In these cases we would make currentIcon invisible. You may select a different approach and show a fuzzy checkbox image instead, but that is beside the point. The following modification of updateDisplayList does the job of removing checkBox when the value is undefined:
override protected function updateDisplayList(unscaledWidth:Number,unscaledHeight:Number):void
{
super.updateDisplayList(unscaledWidth, unscaledHeight);
if (currentIcon) {
var style:String = getStyle("textAlign");
if ((!label) && (style=="center") ) {
currentIcon.x = (unscaledWidth - currentIcon.measuredWidth)/2;
}
currentIcon.visible = (_value!=undefined);
}
}
To accommodate this change we also have to loosen up the class definitions for value as shown in Listing 15, where we change Object to undefined.
Next and probably the most important fix is that our CheckBoxes have been silenced. Try to click on one, scroll the row out of view, and scroll it back in. The checkbox doesn't retain your selection and it shouldn't: we have never communicated the change to the underlying data. To remedy this situation we'll add the constructor method, where we'd start listening on the "change" event; once an event is intercepted we'll modify the data item with the CheckBox value. That, in turn, will result in either onValue or offValue as per our value getter:
public function CheckBox() {
super();
addEventListener(Event.CHANGE,
function(event:Event):void{
if (listData) {
data[DataGridListData(listData).dataField] = value;
}
}
);
}
The complete code for the second version of CheckBox is in Listing 15.
Next comes the test application in Listing 16. We've added the "Revoke day care benefit" button, which makes DAY_CARE_BENE undefined on the currently selected DataGrid item. We also had to notify the collection with the itemUpdated() call.
When you run the application, you'll see that checkboxes retain the selection after scrolling out and back into view. If you click the "Revoke" button for the first two rows, you're going to see a picture similar to Figure 8.
The last CheckBox fix will come in handy once you declare the DataGrid editable. Why declare it editable in the first place if we seem to be editing the DataGrid already? Let's not forget that the only field we've edited so far is the checkbox BENE_DAY_CARE. Should you also decide to allow editing the text fields you'd have to change the definition of the DataGrid as shown in bold in this snippet:
<fx:DataGrid id="dg" creationComplete="dg.fill();dg.selectedIndex=0;" editable="true"
destination="com_theriabook_composition_EmployeeDAO" method="getEmployees" >
But once you do that, a click on our beautiful checkbox would turn it into default editor - TextInput, quite like in a Cinderella story. To make the miracle last, you'd declare that your renderer is good to go as an editor as well:
<fx:DataGridColumn dataField="BENE_DAY_CARE" textAlign="center"
itemRenderer="com.theriabook.controls.CheckBox" rendererIsEditor="true">
. . .
</fx:DataGrid>
By default, DataGrid reads the text property of the item editor. You can nominate a different property via editorDataField (in our case that would be value). Alternatively, and what will help us later, you can "upgrade" the checkbox to carry the text property itself:
public function set text(val:String) :void {
value = val;
}
public function get text():* {
return value;
}
Summary
While DataGrid is a powerful component
right off-the-shelf, but the fact that it's truly extendable can
substantially increase its usability. In the next part of this article,
we'll continue experimenting with the DataGrid by using radio buttons
as renderers and introduce computed columns.