One of the things that makes Flex so attractive is the extensive set of default behaviors provided in its many controls. Sometimes, however, that default behavior is not what you want and you have to work with Flex to get your desired behavior. I ran into a case of that recently when working with a DataGroup.

I created an ItemRenderer which contained a button the user could click to expand the cell to provide some additional information about the product in that cell. That worked fine but I discovered that the DataGrid row collapsed back to its original size as soon as I moved the mouse out of that cell. The problem is that the Flex ItemRenderer base class includes some default behaviors for mouse over events (among others). For mouse over, the current cell is highlighted and, of course, for mouse out the highlight is removed. This was fine but, in my case, the problem was that when I moused out, the ItemRenderer reverted to its normal state—which was the state without the added content. Here’s my original item renderer:

<?xml version="1.0" encoding="utf-8"?>
<s:ItemRenderer xmlns:fx="http://ns.adobe.com/mxml/2009" 
				xmlns:s="library://ns.adobe.com/flex/spark" 
				xmlns:mx="library://ns.adobe.com/flex/mx" 
				autoDrawBackground="true">
 
	<s:states>
		<s:State name="normal" />
		<s:State name="details" />
	</s:states>
 
	<s:Rect height="100%" width="100%">
		<s:stroke>
			<s:SolidColorStroke color="black"/>
		</s:stroke>
	</s:Rect>
	<s:VGroup paddingTop="10" paddingLeft="10" paddingBottom="10" paddingRight="10">
		<s:Label text="Always Displayed" includeIn="normal, details"/>
		<s:Label text="{data}"/>
		<s:Group>
			<s:Button label="Add 2nd label" includeIn="normal" click="currentState='details'" />
			<s:Button label="Remove 2nd label" includeIn="details" click="currentState='normal'"/>
		</s:Group>
		<s:Label text="Detailed description" includeIn="details"/>
	</s:VGroup>
</s:ItemRenderer>

There are two states, “normal” which is the original state without the “Detailed description” label, and “details” which does include this label. There is also a pair of buttons to allow the user to show and hide the detailed description label. Only one of those buttons is shown at any given time based on the value of currentState.

The solution I found was to override the ItemRenderer method getCurrentRendererState. I also added two states, including the hovered state which the Flex ItemRenderer base class implements:

<s:states>
    <s:State name="normal" />
    <s:State name="hovered" />
    <s:State name="details" />
    <s:State name="hoveredDetails"/>
</s:states>

I modified my item renderer to apply the new states appropriately:

<s:VGroup paddingTop="10" paddingLeft="10" paddingBottom="10" paddingRight="10">
    <s:Label text="Always Displayed" includeIn="normal, hovered, details, hoveredDetails"/>
    <s:Label text="{data}" includeIn="normal, hovered, details, hoveredDetails"/>
    <s:Group>
        <s:Button label="Add 2nd label" includeIn="normal, hovered" click="currentState='details'" />
        <s:Button label="Remove 2nd label" includeIn="details, hoveredDetails" click="currentState='normal'"/>
    </s:Group>
    <s:Label text="Detailed description" includeIn="details, hoveredDetails"/>
</s:VGroup>

And I implemented my override of getCurrentRendererState:

protected override function getCurrentRendererState():String
{
    var newRenderState:String = super.getCurrentRendererState();
    if((currentState == "details" || currentState == "hoveredDetails") && newRenderState == "normal")
    {
        newRenderState = "details";
    }
    if(currentState == "details" && newRenderState == "hovered")
    {
        newRenderState = "hoveredDetails"; 
    }
    return newRenderState;
}

Here, I force the state to include the details even when the user mouses out and, in so doing, get the desired behavior.

Download sample project (FXP).

In my past three posts I’ve been evolving a technique for creating a type-safe collection class that can be used a DataProvider for Flex Lists and DataGrids. As I’ve discussed previously, the problem with these controls is that they use the ArrayList or ArrayCollection classes as their data providers. And the problem those collections is that they are not type-safe. You can put any type of object into an ArrayList or ArrayCollection. That’s not a problem until you put the wrong type into one. Then, you get an error at run-time. It would, of course, be far better to catch the error at compile time. In this post I present the culmination of my technique which makes it convenient to use a type-safe container with Flex Lists and DataGrids.

Having honed the technique over the course of four blog posts I’m now making available a TypeSafeList abstract class which you can easily and quickly extend. With only about 20 lines of code you can create a subclass of TypeSafeList that will contain any single data type of your choice. Any attempt to insert an object of the wrong type will be caught at compile time. And, because TypeSafeList implements IList your subclass can still be used as a data provider for Lists and DataGrids.

If you want to know how the technique works, see my previous posts:

1. Type-Safe DataProviders for Flex Lists with the ActionScript Vector
2. An Enhanced Type-Safe Data Provider Technique for Flex IList-Based Controls
3. Type-Safe DataProvider for Flex DataGrid; Data Loading Encapsulated w/Parsley DynamicCommand

If you just want to use TypeSafeList to quickly create your own type-safe collection classes you can skip the previous posts and just read this one.

To use TypeSafeList you need to create a container class that extends TypeSafeList and has a Vector as an instance variable. You should, of course, type the Vector to contain the object type that you’re interested in. For this example, we’re going store Person objects so we’ll have:

private var _people:Vector.<Person>;

Next, you need to define a type-safe interface for accessing your Vector. Here’s a minimal example:

public interface IPersonVectorDP
{
    function pop():Person;
    function push(value:Person):uint;
}

You can name your interface whatever you like; here, I’ve used IPersonVectorDP. You will add or remove Person objects to _people only through this interface. Your interface could have other methods; e.g., insertItemAt or deleteItemAt (note that you must not use any of the same method names as the IList methods). Whatever methods you define in your interface will need to be implemented in your type-safe collection’s implementation class.

Here’s the beginning of an example TypeSafeList subclass with our _people Vector:

public class PersonVectorDP extends TypeSafeList implements IPersonVectorDP
{
    private var _people:Vector.<Person>;
 
    public function PersonVectorDP()
    {
        _people = new Vector.<Person>;
    }
    .
    .
    .

Next, we implement the methods in our IPersonVectorDP  interface that we defined above. Here, we implement the push and pop methods we declared in IPersonVectorDP:

public function push(value:Person):uint
{
    var count:uint = _people.push(value);
    dispatchAddEvent(value, count);
    return count;
}
 
public function pop():Person
{
    var poppedPerson:Person = _people.pop();
    dispatchRemoveEvent(poppedPerson, _people.length);
    return poppedPerson;
}

These methods wrap Vector’s push and pop methods. In addition, they call event dispatchers in the TypeSafeList superclass. These event dispatchers notify the Flex List/DataGrid controls when the container’s elements have changed so that the controls can update their views of those elements.

At this point, you need to write a function to provide access to your Vector so that TypeSafeList can access elements as needed by Flex’s List & DataGrid controls (through IList). You have a choice between a clean, easy approach that can be wasteful of memory and an efficient approach which requires you to modify a few lines of code in TypeSafeList.

First, here’s the clean, easy approach. You define a function which returns a reference to your Vector as a Vector of Objects. In our example, we return a copy of the _people Vector.

override protected function getVector():Vector.<Object>
{
    var vector:Vector.<Object> = Vector.<Object>(_people);
    return vector;
}

This works fine for TypeSafeList because Objects are what IList uses. IList doesn’t need to know about Persons so neither does TypeSafeList.

The problem with this technique is that every time an element is added to your Vector a copy of the entire Vector is made in getVector. For small collections the overhead will be negligible. But for collections consisting of thousands of elements the overhead could be substantial. But without pointers (or pointers to references) as in C++ there’s nothing that can be done. Except to get in and muck around in the base class code.

So, here’s the efficient but slightly messy alternative: you edit a copy of TypeSafeList and modify the existing getVector function to return a Vector of your type. Here’s the stock getVector function from TypeSafeList:

protected function getVector():Vector.<Object>
{
    throw new IllegalOperationError("Error in TypeSafeList; you must subclass TypeSafeList and override getVector");
    return null;
}

And here’s a modified version:

override protected function getVector():Vector.<Person>
{
    throw new IllegalOperationError("Error in TypeSafeList; you must subclass TypeSafeList and override getVector");
return null;
 
}

Now, you can modify your override to return a Vector of your type; e.g.,

override protected function getVector():Vector.<Person>
{
    return _people;
}

You also need to make a couple more edits to TypeSafeList. First, there’s a Vector.<Object> declaration in getItemIndex; just change it to your type; e.g., Vector.<Person>. Second, there’s a loop in which an element var is declared:

var element:Object = vector[i];

You’ll also need to change the Object type to your type.

As you can see, there are actually only three lines of code to modify if you want to go the performance route. Unfortunately, that means you’ll need to create a separate copy of TypeSafeList for each data type you want to use it with. But until ActionScript has full support for generics this is the best we can do. But, at least, we can now have type-safe collections for use with Flex ListBase-derived controls and DataGrids.

Download the example project (FXP).

In this post I’m continuing the theme of my last two posts, type-safe DataProviders, and combining it with the theme of the two posts before that: the Parsley application framework. I’ll be using Parsley’s DynamicCommand object to encapsulate the fetching of data from a server and then store it in a type-safe DataProvider that will be used with a DataGrid. If you haven’t read my previous two posts you’ll need to do that to get the most out of this post. I’d recommend starting with the first post of the pair, Type-Safe DataProviders for Flex Lists with the ActionScript Vector.

A Type-Safe DataProvider for the Flex DataGrid

My first theme, type-safety, addresses the fact that the built-in Flex types ArrayList and ArrayCollection, which are used as data providers for List & DataGrid controls, are not type-safe. So, if you intend to provide a list of Employees as the data source for your DataGrid you have no way to ensure that some other developer hasn’t accidentally passed you an ArrayList of Dogs, for example. (Well, you could iterate over the entire collection, checking the type of each element, before supplying it to your DataGrid. But who actually does that?) ActionScript does provide a type-safe collection class, Vector, but it doesn’t work as a List/DataGrid DataProvider.

My previous two posts demonstrated a technique with which you can use the Vector to gain type-safety while still providing the IList interface that Flex’s list & grid controls require. Since I’ve already covered that ground I won’t explain how that works here. In this example, the type-safe collection is called EmployeeDataProvider and it implements two interfaces, IList and IEmployeeDataProvider. The latter interface is the one which ensures type-safety:

public interface IEmployeeDataProvider
{
    function pop():Employee;
    function push(value:Employee):uint;
}

Only Employee objects can be added to the collection through this interface. Here’s the beginning of the EmployeeDataProvider class:

public class EmployeeDataProvider extends EventDispatcher implements IList, IEmployeeDataProvider
{
    private var _employees:Vector.<Employee> = new Vector.<Employee>;
 
    public function EmployeeDataProvider(target:IEventDispatcher=null)
    {
        super(target);
    }
 
    // 
    // IEmployeeDataProvider
    //
    public function pop():Employee
    {
        var poppedEmployee:Employee = _employees.pop();
        var event:CollectionEvent =	new CollectionEvent(CollectionEvent.COLLECTION_CHANGE);
        event.kind = CollectionEventKind.REMOVE;
        event.items.push(poppedEmployee);
        event.location = _employees.length;
        dispatchEvent(event);
        return poppedEmployee;
    }
 
    public function push(value:Employee):uint
    {
        var count:uint = _employees.push(value);
        var event:CollectionEvent =	new CollectionEvent(CollectionEvent.COLLECTION_CHANGE);
        event.kind = CollectionEventKind.ADD;
        event.items.push(value);
        event.location = count-1;
        dispatchEvent(event);
        return count;
    }

By using the type-safe container, Vector, we ensure the type-safety of our container object, EmployeeDataProvider. The two functions, pop & push, mostly contain code for dispatching events so that the DataGrid can react to changes in the collection. Other than that, they delegate push & pop to the Flex Vector.

I’m not showing the code that implements IList here because I’ve explained it in my previous posts. (But you can View Source on the SWF above if you want to see it.) The IList interface is not used by my code. The IList implementation is provided only so that the DataGrid will be able to use EmployeeDataProvider as a data source.

Creating a Flex Data Service to Read XML

The data used in this example is a simple XML file that is hosted on my server at http://flexperiential.com/code/employees.xml. I created a Flex HTTPService to fetch this data by choosing Data –> Connect to Data Service from the Flash Builder menu:

After creating the service I right-clicked on the new getEmployees method in the Data/Services window and selected Configure Return Type. Flash Builder then automatically created value objects to match the data: Employee objects containing fields for firstname, lastname, title, email, etc.

Using Parsley DynamicCommand to Fetch Data from the Server

A common pattern for fetching server data is to encapsulate the web service in a command object. Parsley provides a convenient DynamicCommand object which is tailor-made for this purpose. Here’s my class that will be instantiated using DynamicCommand:

public class GetEmployeesCmd extends EventDispatcher
{
    [Inject] public var employeeService:EmployeeServce;
    [Inject] public var employeeDataProvider:EmployeeDataProvider;
 
    public function GetEmployeesCmd()
    {
    }
 
    public function execute(event:EmployeeServiceEvent):AsyncToken
    {
        return employeeService.getEmployees();
    }
 
    public function result(data:Object):void
    {
        for (var i:int = 0; i < data.employee.length; i++)
        {
            var employee:Employee = data.employee[i] as Employee;
            employeeDataProvider.push(employee);
        }
    }
 
    public function error (info:Object): void
    {
        trace("Error fetching employees");
    }
}

This class contains three methods named so that Parsley will automatically recognize them and wire them up: execute, result and error. When you invoke the DynamicCommand Parsley automatically calls the execute method. And, Parsley automatically calls the result method when the service returns its data (ResultEvent) or, in case of an error (FaultEvent), the error method.

I’m also using Parsley here to inject instances of the EmployeeService and the EmployeeDataProvider.

Parsley Context/Configuration

Here’s the Parsley context file that ties all of this together:

<models:EmployeeDataProvider/>
<employeeservce:EmployeeServce/>
<spicefactory:DynamicCommand type="{GetEmployeesCmd}" selector="{EmployeeServiceEvent.LOAD_EMPLOYEES_REQUEST}">
    <spicefactory:ManagedEvents names="{[EmployeeServiceEvent.LOAD_EMPLOYEES_REQUEST]}"/>
</spicefactory:DynamicCommand>

The first two lines specify that the EmployeeDataProvider and EmployeeService classes will be managed by Parsley. The type parameter shown in the DynamicCommand refers to the GetEmployeesCmd class discussed above. The names parameter specifies the event that will cause GetEmployeesCmd.execute to be invoked.

Application MXML File

The application file contains a couple of statements needed to complete the Parsley configuration:

<fx:Declarations>
    <parsley:ContextBuilder config="{ParsleyDynamicCommandContext}"   />
    <parsley:Configure  />
</fx:Declarations>

The first line specifies the context file name and the second line tells Parsley to configure the main app MXML file.

This init function is called after Parsley has finished its object injection and other work (this is specified by the [Init] meta tag):

[Init]
public function init():void
{
    dispatchEvent(new EmployeeServiceEvent(EmployeeServiceEvent.LOAD_EMPLOYEES_REQUEST));
}

The function simply dispatches the event which causes the GetEmployeesCmd to be invoked. We also need to tell Parsley to manage the EmployeeServiceEvent event in the application file:

<fx:Metadata>
    [ManagedEvents("LoadEmployeesRequest")]
</fx:Metadata>

After the execute method has called the web service (just an XML file, here), the result method populates the EmployeeDataProvider instance which is shared by GetEmployeesCmd and the main application. It’s injected into the MXML application file like so:

[Bindable][Inject] public var employeeModel:EmployeeDataProvider;

Finally, the app file contains a DataGrid which displays the employee data:

<mx:DataGrid dataProvider="{employeeModel}" height="100%" width="100%">
    <mx:columns>
        <mx:DataGridColumn dataField="firstname" width="75" />
        <mx:DataGridColumn dataField="lastname" width="75" />
        <mx:DataGridColumn dataField="title" />
        <mx:DataGridColumn dataField="email" />
        <mx:DataGridColumn dataField="department" width="140" />
    </mx:columns>
</mx:DataGrid>

Download the Flex project (fxp).

Next week I’ll finish this series of posts with a TypeSafeList abstract class that you can extend to quickly and easily build your own type-safe DataProviders.

Last week I posted an article showing how to create type-safe lists for use as Flex List-based DataProviders. This week I’m enhancing that example to dispatch events when items are added to or removed from the collection. This will allow Lists to update their displays automatically whenever the contents of the DataProvider change. If you haven’t already read my previous post on this topic, you will probably want to do so before continuing with this one.

Improved IList Type-Safety

But before I get to dispatching events I’d like to point out another improvement I’ve made to the PersonVectorDP example class which strictly enforces the type-safe approach. In last week’s post I recommended using only IPersonVectorDP to provide type-safe access. And I recommended setting the reference to the PersonVectorDP class to null as soon as possible to prevent accidental access through the IList methods:

_people = new PersonVectorDP;
peopleList.dataProvider = _people;
 
// Always access PersonVectorDP only through IPersonVectorDP
_peopleInterface = _people as IPersonVectorDP;
_people = null; // To be safe, null this out ASAP. That way, you can't inadvertently use the wrong method.

This approach will work but still requires some diligence on the part of the developer. It subsequently occurred to me that a better approach is to enforce modification of the collection through the IPersonVectorDP interface by throwing an exception if any attempt is made to modify the collection through the IList methods. So, for example, instead of implementing addItem by pushing the new Person onto the Vector, we now throw an IllegalOperationError instead:

throw new IllegalOperationError("addItem - no access through IList; use IPersonVectorDP instead");

I’ve done the same thing for all the other IList methods which modify the list. Of course, the getItemAt and getItemIndex methods are unchanged.

Now, if you forget to null out the PersonVectorDP reference it won’t matter. And, maybe you need to keep the reference around in order to assign it as the DataProvider to some new List later. Now, you can. And you can be certain that all access to the collection will be type-safe. Best of all, the code is smaller and cleaner!

Dispatching collectionChange Events

Continuing with the modified PersonVectorDP class, the next change I’ve made is to have the class extend EventDispatcher:

public class PersonVectorDP extends EventDispatcher implements IList, IPersonVectorDP

This allows us to remove all of the event-related stub code that is present in the previous example (addEventListener, removeEventListener, dispatchEvent, etc.).  The class still implements IList & IPersonVectorDP, as before.

We also now declare that the class dispatches the event that List-based controls listen for:

[Event(name="collectionChange", type="mx.events.CollectionEvent")]

And we dispatch this event whenever items are added to the list:

public function push(value:Person):uint
{
    var count:uint = _people.push(value);
    var event:CollectionEvent =	new CollectionEvent(CollectionEvent.COLLECTION_CHANGE);
    event.kind = CollectionEventKind.ADD;
    event.items.push(value);
    event.location = count-1;
    dispatchEvent(event);
    return count;
}

and whenever items are removed from the list:

public function pop():Person
{
    var poppedPerson:Person = _people.pop();
    var event:CollectionEvent =	new CollectionEvent(CollectionEvent.COLLECTION_CHANGE);
    event.kind = CollectionEventKind.REMOVE;
    event.items.push(poppedPerson);
    event.location = _people.length;
    dispatchEvent(event);
    return poppedPerson;
}

That’s all the changes that are needed to PersonVectorDP. You could, of course, add accessor methods to the IPersonVectorDP for more functionality; e.g., type-safe equivalents to addItemAt or itemUpdated.

Demo Code to Use the Modified PersonVectorDP Class

Next, I’ve made a few changes to the test app, VectorDataProviderTypeSafe.mxml. I’ve added a couple of input fields and a button to allow adding more people. And, I’ve added a button to remove people:

<s:TextInput id="newPersonFirst" />
<s:TextInput id="newPersonLast" />
<s:Button id="addPerson" label="Add Person" click="addPerson_clickHandler(event)" />
<s:Button id="removePerson" label="Remove Person" click="removePerson_clickHandler(event)" />

This button click listener code is straightforward; here’s the add event listener:

protected function addPerson_clickHandler(event:MouseEvent):void
{
    var person:Person = new Person;
    person.firstName = newPersonFirst.text;
    person.lastName = newPersonLast.text;
    _peopleInterface.push(person);
}

And here’s the remove event listener:

protected function removePerson_clickHandler(event:MouseEvent):void
{
    _peopleInterface.pop();
}

I hope this technique works to help you write more bug-free code!

Download the Flex project (FXP).

Update, 2/25/11: I’ve updated the code to provide both complete type-safety and event dispatching so that Lists will update their views automatically when the list contents are changed. If you’re interested in this topic, you will probably still want to start by reading this post. But be sure to continue with my follow-up post An Enhanced Type-Safe Data Provider Technique for Flex IList-Based Controls to get the new, improved code.

Coming to Flex from a primarily C++/C# background I have always been a bit dismayed by the loose typing that is possible with ActionScript. Strict typing is an inherent advantage of languages like C++, C# and Java because it allows the compiler to catch incorrect-type errors at compile-time and this leads to greater developer productivity. Any time you can catch an error at compile-time instead of at run-time you’re multiplying your productivity.

With ActionScript 3 you do have the ability to require strict typing for most of your objects but there are some areas in which Flex still falls down. One of these in its List-based components and its DataGrids. Data providers for these objects are typically ArrayLists or ArrayCollections of generic Objects. Unfortunately, this means there is no way to do type-checking of the objects added to these containers. You may intend to have an ArrayCollection of Dog objects but there’s nothing to prevent you from slipping a couple of Cats in there. Imagine the mayhem that will ensue!

The ActionScript Vector—a (mostly) Type-Safe Container Class

ActionScript does have a container class, the Vector, which allows for type checking. Unfortunately, it’s little-used and that’s too bad. Part of the reason is probably because it cannot be used with Flex’s list and grid components. But I encourage you to use it whenever possible—which includes any time you might use a regular Array. And, in fact, it is possible to use it for List-based components by simply implementing the IList interface. I’ll show an example of that shortly.

But, first, I want to back up and demonstrate the basics of the Vector class. Any time you have a collection of things of a single type you can declare a Vector of that type. So, to keep Cats out of my collection of Dogs, I could do the following:

var dogs:Vector.<Dog> = new Vector.<Dog>;

The dot-notation will probably look a little odd the first time you see it but this is how you tell ActionScript that you want an array (speaking generically, here) consisting of only Dog objects.  To add Dog instances to the Vector just do the following:

var dog1:Dog = new Dog();
dogs.push(dog1);

And if BorderCollie extends Dog you can, of course, also do:

var dog2:BorderCollie = new BorderCollie();
dogs.push(dog2);

But if you try this:

var cat:Cat = new Cat();
dogs.push(cat);

you will get an error at run-time. It’s nice to get the run-time error but it’s unfortunate that the Flex compiler doesn’t detect this at compile time. The docs say the reason is because push() can accept multiple arguments. Because of the way ActionScript handles functions with an indeterminate number of arguments it’s just not possible to do type-checking at compile-time.

But you will, at least,  get a run-time error as soon as you attempt to push the Cat in there amongst all those Dogs. That’s better than adding a Cat to your Dogs collection and not finding out about the error until sometime later. If you tried this with an ArrayList or ArrayCollection it would, of course, work and then when the inevitable cat-and-dog-fight ensues you’d have to backtrack to find out who let the Cat in.

Next, I’ll show how to wrap a Vector in a class so that it can be used as a DataProvider. And, later I’ve got a solution which even allows for compile-time type checking with the Vector. More on that below.

Flex Lists with Vectors as DataProviders

As I mentioned earlier, one downside of Vectors is that you cannot use them with List-based components like Spark Lists, ComboBoxes, DropDownLists and ButtonBars—at least, not directly. You can, however, adapt Vectors so that they can be used with these Flex components. These components require, as data providers, an object which implements IList. ArrayList and ArrayCollection both implement IList which is why they work as data providers.

The basics of implementing IList are straightforward. The interface consists primarily of methods like addItem, addItemAt, getItem and removeItem. So, you can create a class which implements IList and include a Vector.<YourType> as a member variable. Then, in the implementation of each of these setter and getter methods just do the appropriate action on your Vector instance. That’s it! You can then use your Vector wrapper with a List, ComboBox or DropDownList.

If you want a full-featured IList implementation you’ll need to do some extra work like calling listeners when data items change. But for many purposes you won’t need to bother with these extra features. Here’s a simple implementation of IList which wraps a Vector.<Person> instance. Here’s the Person class:

public class Person
{
    public var firstName:String;
    public var lastName:String;
 
    public function Person()
    {
    }
 
    public function toString():String
    {
        return firstName + " " + lastName;
    }
}

Here’s the PersonVectorDP class with the (partial) IList implementation:

public class PersonVectorDP implements IList
{
    private var _people:Vector.<Person> = new Vector.<Person>;
 
    public function PersonVectorDP()
    {
    }
 
    //
    // IList
    //
    public function get length():int
    {
        return _people.length;
    }
 
    public function addItem(item:Object):void
    {
        _people.push(item);
    }
 
    public function addItemAt(item:Object, index:int):void
    {
        _people.push(item); // TODO: insert at specified index; throw RangeError if index is out of range
    }
 
    public function getItemAt(index:int, prefetch:int=0):Object
    {
        return _people[index] as Object;
    }
 
    public function getItemIndex(item:Object):int
    {
        for (var i:int = 0; i < _people.length; i++)
        {
            var element:Person = _people[i] as Person;
            if(element == item)
            {
                return i;
            }
        }
        return -1;
    }
 
    public function itemUpdated(item:Object, property:Object=null, oldValue:Object=null, newValue:Object=null):void
    {
        //TODO: implement function
        trace("itemUpdated NOT IMPLEMENTED");
    }
 
    public function removeAll():void
    {
        _people.splice(0, _people.length);
    }
 
    public function removeItemAt(index:int):Object
    {
        var removedStrings:Vector.<Person> = _people.splice(index,1);
        return removedStrings[0];
    }
 
    public function setItemAt(item:Object, index:int):Object
    {
        if(index < 0 || index >= _people.length)
        {
            throw new RangeError("setItemAt index: " + index + " is out of range");
        }
        _people.splice(index, 0, item);
        return null;
    }

And here it is in use:

<s:List id="list"/>
<s:ComboBox id="combo"/>
<s:DropDownList id="drop"/>
 
protected function createPersonVectorDP():void
{
    var people:PersonVectorDP = new PersonVectorDP;
    list.dataProvider = people;
    combo.dataProvider = people;
    drop.dataProvider = people;
 
    var person1:Person = new Person;
    person1.firstName = "Don";
    person1.lastName = "Draper";
    people.addItem(person1);
 
    var person2:Person = new Person;
    person2.firstName = "Betty";
    person2.lastName = "Draper";
    people.addItem(person2);
 
    var person3:Person = new Person;
    person3.firstName = "Roger";
    person3.lastName = "Sterling";
    people.addItem(person3);
 
    var person4:Person = new Person;
    person4.firstName = "Peggy";
    person4.lastName = "Olson";
    people.addItem(person4);
}

Download the sample code at the end of this post.

Making the DataProvider Type-Safe

Although this does work there’s a problem with using the IList interface to add elements to the Vector DataProvider. The problem is that those IList methods accept Objects. So, although we were only inserting Persons into our PersonVectorDP container the compiler wouldn’t stop us from inserting Dogs or Cats:

var d:Dog = new Dog;
people.addItem(d); // compiles, but throws error at run-time

We would get an error at run-time but it sure would be nice to get the error at compile-time instead. Fortunately, there’s a solution:  never use the IList interface in your own code. Instead, create your own type-safe interface and use it as a proxy to access the Vector object. We can do this with the following simple interface:

public interface IPersonVectorDP
{
    function pop():Person;
    function push(value:Person):uint;
}

We’ll implement this interface, in addition to IList, in PersonVectorDP:

public function pop():Person
{
    return _people.pop();
}
 
public function push(value:Person):uint
{
    return _people.push(value);
}

Now, we can add and remove elements to _people in a completely type-safe manner. Any attempt to push a Dog in where a Person belongs will be rejected by the compiler.

If you want a more robust set of accessor methods you’re free to add them. As long as you use only these strongly-typed methods you get the best of both worlds: List-compatible collections and type-safety. Just make sure never to use the IList accessor methods. To avoid this mistake you should always access the only through the type-safe interface, never through the Vector wrapper:

var people:PersonVectorDP = new PersonVectorDP;
list.dataProvider = people;
combo.dataProvider = people;
drop.dataProvider = people;
 
// Always use this interface to access the personVectorDP instance:
var peopleInterface:IPersonVectorDP = people as IPersonVectorDP; 
people = null; // To be safe, null this out ASAP. That way, you can't inadvertently use the wrong method.
var person1:Person = new Person;
person1.firstName = "Don";
person1.lastName = "Draper";
peopleInterface.push(person1);
 
var person2:Person = new Person;
person2.firstName = "Betty";
person2.lastName = "Draper";
peopleInterface.push(person2);
 
var person3:Person = new Person;
person3.firstName = "Roger";
person3.lastName = "Sterling";
peopleInterface.push(person3);
 
var person4:Person = new Person;
person4.firstName = "Peggy";
person4.lastName = "Olson";
peopleInterface.push(person4);
 
// Never access people directly. Always use the interface as shown above.
// people.addItem(new Dog()); // This will fail at run-time since people is now null.

Download the sample code (FXP)

In an upcoming post, I’ll show an implementation of PersonVectorDP which dispatches events so that the Flex List classes will reflect changes to the data source. I’ve written an updated post, An Enhanced Type-Safe Data Provider Technique for Flex IList-Based Controls, which includes a new, enhanced version of the code. Please get that version of the code instead.

Brain Teaser

Substitute a StringVectorDP class for the PersonVectorDP class above. This class is the same as the PersonVectorDP class except that its field variable is a Vector of Strings. And, of course, all the IList methods operate on this _strings var.

private var _strings:Vector.<String> = new Vector.<String>;

Consider the following code:

var vectorDP:StringVectorDP = new StringVectorDP();
var d:Dog = new Dog;
vectorDP.addItem(d); // No error either at compile-time or run-time

No error occurs when adding the Dog object either at compile-time or run-time. Why not? Click to see answer

It works because the data type of the objects in the _strings Vector is String. All ActionScript objects have an implicit toString() function. So, when addItem calls Vector.push() the Dog object is converted into a String before getting stored in the Vector. One more reason to use the type-safe interface technique described above!

Update 2/12/2011: Based on feedback from Jens, the creator of the Parsley framework, I’ve updated this post and the downloadable sample code.

Last year I posted an example of a Flex sliding menu component along with a simple project that shows its use. Here, I present a variation of the menu using the Parsley application framework. Parsley is a popular Flex framework which is used for dependency injection, decoupled messaging and much more. Dependency injection allows you to build applications which are more loosely coupled. This makes your applications easier to modify and test.

Similarly, decoupled messaging gives you more flexibility than the standard Flex event mechanism. With Flex events, in order to add an event listener you have to have a reference to the object you want to listen to. This causes closer coupling which, again, makes applications less resilient to changes. With Parsley messaging any object can listen for any event whether or not the receiver has a reference to the sender. Parsley messaging also provides additional flexibility in the ability to send any object as a message payload. With Flex events you can only send an Event or an Event subclass. There are additional benefits to Parsley’s messaging model, such as message selectors, which you can read about on the Parsley website.

Parsley Menu Example

This example is very similar to my original example. The only differences are in the sending and receiving of the MenuItemSelectedEvent and, of course, the configuration of Parsley. For this simple example the amount of code needed to set up Parsley is minimal. To get started we just need to add a pair of SWC library files to the Flex Build Path: parsley-flex4-2.3.0.swc and spicelib-flex-2.3.0.swc. Both are included in the Parsley distribution.

In the menu component, VerticalSlidingMenu.mxml, a MenuItemSelectedEvent is constructed as before. This event contains the id of the menu item which is clicked. The difference is that, instead of dispatching an event, we use the Parsley messaging mechanism to send a message. In this case, we call our message sender sendMessage although we could call it anything we want. What’s interesting here is that we don’t actually define a sendMessage function, per se. Instead, we just declare it using the Parsley MessageDispatcher meta tag:

[MessageDispatcher]
public var sendMessage:Function;
 
protected function menuClickHandler(event:MouseEvent):void
{
	var menuEvent:MenuItemSelectedEvent = new MenuItemSelectedEvent(MenuItemSelectedEvent.MENU_ITEM_SELECTED, event.target.id);
	sendMessage(menuEvent);
}

Parsley provides the function definition.

To receive the event we declare a MessageHandler in MenuParsley.mxml, the main application file:

[MessageHandler]
public function messageHandler (event:MenuItemSelectedEvent) : void 
{
	_menuItemClicked = event.menuItem;
}

This is equivalent to a Flex event listener except that we don’t use addEventListener to link it to the menu component. Parsley takes care of connecting the sender and receiver.

Parsley configuration for this simple example consists of only two statements. First, in MenuParsley.mxml we just need a ContextBuilder tag. The following tag is in the Declarations section:

<parsley:ContextBuilder  />

Second, we just have to add a <parsley:Configure/> tag to the declarations section of VerticalSlidingMenu.mxml. That’s it!

Download the sample application (FXP). For more info on using Parsley see Art’s Flex Notes series of posts.

Arturo Alvarado has a very nice series of tutorials on the Parsley application framework but they’re in Flex 3. A couple of them have been translated into Flex 4 by other blog readers but not the code for his Quick Dive into Parsley (Nested Contexts & Object lifecycle methods – Part 6). I’ve done that translation and you can download it here. Note that I’ve only modified the code needed to make it compile and run.

Flex provides nice form field validation functionality through its various Validator classes, including:

• CreditCardValidator
• CurrencyValidator
• DateValidator
• EmailValidator
• NumberValidator
• PhoneNumberValidator
• SocialSecurityValidator
• StringValidator
• StyleValidator
• ZipCodeValidator

If one of these doesn’t serve your needs you might make use of the RegExpValidator to customize your validation. And, if that still doesn’t do it you can subclass Validator to write your own validation algorithm. However, sometimes even that’s not enough. Sometimes, you really have to have server-side validation. Maybe you have complex server-side business logic that you don’t want to replicate in the client. Maybe you need to look up something in a database. You could fetch information from the DB and process the validation in Flex but it’s much more efficient and secure to do that kind of thing on the server. In addition, by moving code out of the client and onto the server you may be able to reduce the SWF file size.

But Flex doesn’t provide any built-in support for server-side validation. So, how can you accomplish it? This post shows one technique.

Client-Side and Server-Side Validation

The original inspiration for this technique came from the article Data Services with Server-Side Validation on the i am josh blog. This example differs first, in that it is complete, containing all code needed on both the client side and the server side. Second, this example focuses on validating a single field at a time. Josh’s example includes a ValidateableErrors class which contains error information for all the fields in a form. This implies that the server-side validation is to be done for all fields at once after submitting the form. By contrast, this solution provides maximum responsiveness by first doing whatever simple validation is possible on the client. If an input field is validated in the client-side logic the input is then sent on to the server for additional validation. Each field is validated as soon as it loses focus.

Form Which Uses the Custom Validator

We’ll start with a very simple form which contains just two fields:

<s:VGroup paddingTop="10">
    <s:Label text="First Name:"/>
    <s:TextInput id="firstName" focusOut="firstName_focusOutHandler(event)" />
    <s:Label text="Last Name:" />
    <s:TextInput />
</s:VGroup>

The first field is the only one which is active in this example. The second field exists only to allow the focus to leave the first one so that validation can be done.

We also have a custom validator object of class ServerValidator:

<local:ServerValidator id="firstNameValidator" property="text" source="{firstName}" />

Linking the validator to the TextInput field as above means that the validator will be called whenever the field loses focus.

We also have an HTTPService to facilitate sending the contents of the firstName text field to the server for validation:

<s:HTTPService id="serverValidator" method="POST"
			   url="http://flexperiential.com/code/ServerSideValidation/validator.php" 
			   result="serverValidator_resultHandler(event)" 
			   fault="serverValidator_faultHandler(event)" />

Whenever the focus leaves the firstName TextInput field the handler is called to check whether the client-side validation was successful. (If you run the code, the trace statements will show that the validator is called before the focus-out listener.) If the client-side validation was successful, the contents of the firstName field are sent to the server for further checking. The result handler relays the results of the server-side validation to our custom validator class.

protected function serverValidator_resultHandler(event:ResultEvent):void
{
    trace("Validation result: " + event.result.html);
    firstNameValidator.value = event.result.html;
}
 
protected function firstName_focusOutHandler(event:FocusEvent):void
{
    trace("firstName_focusOutHandler");
    if(firstNameValidator.localValidationWasSuccessful)
    {
        trace("Sending data for server-side validation");
        var data:Object ={"firstName" : firstName.text};
        serverValidator.send(data);
    }
}

Custom Validator Class

The custom class, ServerValidator, extends Flex’s Validator class:

public class ServerValidator extends Validator
{
    protected var _value:String;
    private var _localValidationWasSuccessful:Boolean = true; 
    private var _doNeedClientSideValidation:Boolean = true;
    .
    .

The three member variables allow the validator class to keep track of the status of the user’s input and its validation. The variable _value contains the user’s current input—but only after it has passed muster with the client-side validation. We saw this being set above in serverValidator_resultHandler.

The variable _localValidationWasSuccessful keeps track of whether the input passed the client-side validation. If not, the form can avoid sending the data to the server. I’ll cover this in more detail below.

Finally, the variable _doNeedClientSideValidation keeps track of which phase the validator is in: client-side validation or server-side validation.

The heart of the validator is the doValidation method which you must override whenever you create a custom Validator:

protected override function doValidation(value:Object):Array
{
    if(_doNeedClientSideValidation)
    {
        // Client-side validation 
        trace("Client-side validation");
        if(value.toString().toUpperCase().indexOf("D") == -1) // All great names have a "d" (mine does!)
        {
            trace("Client-side validation failed");
            _doNeedClientSideValidation = true;
            _localValidationWasSuccessful = false;
            return [new ValidationResult(true, null, "FAIL_CODE", 'First name must contain a "D"')];  
        }
 
        trace("Client-side validation succeeded");
        // Local validation was successful
        _doNeedClientSideValidation = false;
        _localValidationWasSuccessful = true;
        return [];
    }
 
    trace("Server-side validation");
    _doNeedClientSideValidation = true;
    if(_value == "SUCCESS")
    {
        trace("Server side validation succeeded");
        return [];
    }
    else
    {
        trace("Server side validation FAILED");
        var validationError:ValidationResult = new ValidationResult(true, null, "FAIL_CODE", _value);
        return [validationError];
    }
}

If we’re in the client-side validation phase, the first if statement is entered and we check the user’s input which is passed in through the value argument. In this example, I’m looking for the letter “D.” If the input contains the letter “D” the input is valid; otherwise, it’s not. Inside this if statement, we update the two status variables based on whether the input is valid or not. If it was valid we return an empty array which tells Flex that everything is copacetic. And if it was not valid, we return a ValidationResult object containing information about the error.

The rest of the function is concerned with processing the results of the server-side validation. For this example I’ve created a simple PHP file which checks to see if the name contains at least three characters:

<?php
$first_name = trim($_POST['firstName']);
{
   if( strlen($first_name) < 3 ) 
	{
		echo 'Please enter at least three letters';
   } 
   else 
   {
		echo 'SUCCESS';
   }
}
?>

If it does, the page sends the text “SUCCESS” and, if not, it sends an error message for display to the user. In the MXML form the ServerValidator’s value property is set with the results returned by the server to the HTTPService’s resultHandler. The value setter also calls the Validator class’ validate method which, in turn, causes the doValidation method to be called.

At this point, _doNeedClientSideValidation is false so the first if statement will be skipped. In this example, the value “SUCCESS” is checked for and, if present, the method returns an empty array, again indicating valid input. If anything else is received from the server it’s assumed to be an error message. In this case, a ValidationResult containing the error message is returned.

One Validator per Input Field

Because the validator’s state is closely coupled to the input field’s state it is not possible to use a validator instance with multiple input fields as is sometimes done with standard Flex validators like ZIP code or phone. If this were done, the validator could get out of sync with the state of the input fields and fail to operate correctly.

One last note: in a real form with a submit button (actually, you should never use the word submit; this article on the UX Movement website explains why) you would also want to call all your validators in its click handler.

As I discussed in my previous post “O’Reilly’s Flex 4 Cookbook Continues to Disappoint” I recently was frustrated when looking there for sample code to create a Flex 4 custom effect. The Adobe docs have some information on their page “About creating a custom effect” but some of the details are missing, particularly if you want to create an effect based on the Spark Animate class. When I found example 11.8 “Create Custom Animation Effects” in the Flex 4 Cookbook I thought I’d found the info I needed since the sample code on p. 308 shows a class extending Animate. However, I soon found that the code presented on pp. 308-310 is a confusing mish-mash of Flex 3 and Flex 4 that doesn’t even compile. I’ll spare you the gory details here. But if you’re really interested, see my previous post.

Here, I’ll share the code I eventually created to create a custom effect by extending the Flex 4 Animate and AnimateInstance classes. As discussed on the Adobe page mentioned above, you need to write two classes to create a custom animation class. One class is the factory class which the Flex framework uses to create an instance of your animation effect. The other is the class which implements your custom animation. It’s pretty easy once you figure out the basic outline. Here’s my factory class:

public class CustomAnimateEffect extends Animate {
	public var finalAlpha:Number;
	public function CustomAnimateEffect (target:Object=null) {
		super(target);
		this.instanceClass = CustomAnimateInstance;
	}
 
	// create our new instance
	override protected function initInstance(instance:IEffectInstance):void {
		super.initInstance(instance);
		CustomAnimateInstance(instance).finalAlpha = this.finalAlpha;
	}
 
	override public function getAffectedProperties():Array {
		return ["alpha"];
	}
}

The first thing you have to do is provide the effect factory with the name of your effect class. This is done here in the constructor where instanceClass is set. Then you have to set the properties to be animated in the override of initInstance. In this case, I’m only setting the end value finalAlpha. As you’ll see below, this demo effect starts at whatever alpha the target is currently set to.

You could also set multiple properties and animate them all which is where a custom effect could really become useful. Of course, you could also do that with a Parallel or Sequence object. But with a custom effect you have more flexibility to animate whatever you want in whatever way you want. So, for example, you might choose to animate a target object’s alpha value uniformly throughout the effect’s duration but then wait to start animating its color until 50% of the duration has elapsed. Then, you could animate the color change twice as fast during the remaining half the duration. (OK, you could probably do that with a Sequence and a startDelay but you get the idea.)

To complete the two required classes here’s the code for the custom animation:

public class CustomAnimateInstance extends AnimateInstance{
	public var finalAlpha:Number = -1;
 
	public function CustomAnimateInstance(target:Object) {
		super(target);
	}
 
	override public function play():void {
		var motionPath:SimpleMotionPath = new SimpleMotionPath("alpha");
		motionPath.valueFrom = (target as DisplayObject).alpha;
		motionPath.valueTo = finalAlpha == -1 ? 1 : finalAlpha;
		motionPaths = new Vector.<MotionPath>;
		motionPaths.push(motionPath);
 
		super.play();
	}
 
	override public function animationUpdate(animation:Animation):void {
		(target as DisplayObject).alpha = animation.currentValue.alpha as Number;
	}
}

Here, we override a couple of the methods from IAnimationTarget. Most of the code simply creates a SimpleMotionPath which is required by the Animate class. The Animate class calculates the tweened value for you at each frame. Note that the motion path must be created in the play method and not the constructor. This is because the finalAlpha value doesn’t get set until the effect begins to play. That’s when CustomAnimateEffect’s initInstance  method is called and that’s where the desired value gets passed in from the client code. And, here’s that client code:

<fx:Declarations>
	<local:CustomAnimateEffect id="customEffect" finalAlpha="1" target="{btn2}" /> 
</fx:Declarations>
<s:VGroup gap="10" paddingTop="10" paddingLeft="10">
	<s:Button label="Click to fade in the button below" click="customEffect.play()"/>
	<s:Button id="btn2" label="Fade Me In" fontSize="50" alpha="0.2"/>
</s:VGroup>

Download the source code for the custom Flex 4 animation effect (fxp).

I’ve been a fan of the O’Reilly Cookbooks in the past and have found valuable info in both their ActionScript 3.0 Cookbook and Flex 3 Cookbook. So, when O’Reilly released their Flex 4 Cookbook earlier this year I purchased a PDF copy as soon as it became available. However, I’ve been disappointed by this volume as I’ve blogged previously (Flex 4 Cookbook Sample Code Difficult to Use ). Unfortunately, as I continue to use the book I continue to be frustrated.

My most recent frustration was occasioned by an attempt to use the code in section 11.8, “Create Custom Animation Effects.” I started by creating a new Flex 4 project and then copying the book’s two downloaded sample files, CustomTweenEffect.as and CustomTweenInstance.as, into the new project. I then added some code to my new MXML application to use CustomTweenEffect but I was confronted with four compile errors in the Cookbook code. The first error was caused by what appeared to be an extra constructor in the CustomTweenEffect class. This extra constructor was for a class called CustomDisplacementEffect. This was the only reference to CustomDisplacementEffect in the two downloaded source code files so I commented out this function.

I moved on to an error in the CustomTweenEffect class declaration—a missing import for the Flex Animate class. I added the import statement and, while I was at it, I removed the unneeded import for mx.effects.TweenEffect.

At this point, CustomTweenEffect compiled successfully so next I continued with the one remaining error which was in the CustomTweenInstance class. In this case, the problem appeared to be an incorrectly named constructor function: NewTweenInstance. The class in question is CustomTweenInstance so I changed the constructor function name to match. One step forward, one step back. Now, I had a newly reported error on line 11:

1180: Call to a possibly undefined method Tween.           CustomTweenInstance.as                /CustomEffects/src/oreilly/cookbook    line 11   Flex Problem

Another missing import, easy to fix but annoying. Meanwhile, back in CustomTweenEffect  another new error had popped up:
1046: Type was not found or was not a compile-time constant: IEffectInstance. CustomTweenEffect.as                /CustomEffects/src/oreilly/cookbook    line 16   Flex Problem

Yet another missing import, this time for IEffectInstance. After fixing this, the two cookbook classes finally compiled. Dare I hope that it would run? No. Here’s the run-time error (at CustomTweenEffect.as, line 21):

TypeError: Error #1034: Type Coercion failed: cannot convert spark.effects.supportClasses::AnimateInstance@1d45ae51 to oreilly.cookbook.CustomTweenInstance.

Here’s the code at line 21:

CustomTweenInstance(instance).finalAlpha = this.finalAlpha;

This looked to me like CustomTweenInstance was extending the wrong class (TweenEffectInstance). So, I tried changing it to extend AnimateInstance. That led to a compile error on the onTweenUpdate function which is not a member of AnimateInstance. So, I changed that method name to animationUpdate, which is the corresponding method in IAnimationTarget (which is implemented by AnimateInstance), but then the passed-in parameter was wrong. I fixed that. One more step forward, one more step back.  Now, I had a compile error in the CustomTweenInstance play function.

Long story short, I ended up completely rewriting the Cookbook’s two sample classes so that they look almost nothing like the originals. To see an example of creating a custom tween/animate effect see my post “Creating a Custom Animation effect in Flex 4.”

Before I started all this debugging I checked the book’s download & errata pages on the O’Reilly website. However, the latest download available was dated June, 2010—the same version I already had. And there was nothing in the book’s errata page about these problems. It appears O’Reilly has taken the approach of having its customers become alpha testers. But even with a public alpha/beta test one can hope that eventually the software will be debugged. Unfortunately, the Flex 4 Cookbook, with a release date of May, 2010, seems to be stuck somewhere around V0.8 as of the end of 2010.

Update 7/20/11

A reader emailed me to tell of the problems he was having while trying to use the DataGrid examples in chapter 9. Indeed, these examples are a mess. Here are the changes I had to make to example 9_1_b to get them working:

1. Create a project in Flash Builder and copy the sample files into it.
2. Rename the MXML file to start with a non-numeric character.
3. Remove the “oreilly.cookbook.flex4” package on the DataGrid’s itemrenderer property.
4. Copy the file example.mxml from the parent directory of the samples into the Flash Builder project directory.
5. Change the URL on the HTTPService to point to example.mxml instead of assets/homesforsale.xml.
6. Change the mx: namespace declaration to xmlns:mx="library://ns.adobe.com/flex/mx"

It’s really a shame that these examples were so thoughtlessly packaged. If you can get over these hurdles the sample code is actually quite good. But someone trying to learn Flex might easily be overwhelmed and give up.