Wednesday, June 18, 2008

A Reusable Flex Hover Details Window

Update: The source code for this is now hosted on googlecode.

An increasingly common feature in rich web interfaces is when hovering over some piece of information, a window pops up providing more details about that item. An example of this is in the Gmail interface. If you hover over a name in your chat list, you get a popup which displays more details about the person, such as their name, photo and email address. In this short tutorial, I will go over how to do something similar in Flex in a reusable way.

First we start with our simple demo Application.
<?xml version="1.0" encoding="utf-8"?>
  <mx:Application xmlns:mx="" layout="vertical" creationComplete="init()">
    import mx.collections.ArrayCollection;
    private var dataProvider:ArrayCollection = 
                  new ArrayCollection( [ { name: "Leonard Nimoy", image: "nimoy.jpg" }, 
                                         { name: "William Shatner", image: "shatner.jpg" }, 
                                         { name: "Deforest Kelley", image: "kelley.jpg" },] );
  <mx:Panel title="Famous Actors: Hover Over For More Details">
    <mx:List dataProvider="{dataProvider}" 

In this case we are just displaying a set of names in a List component. We create a dataProvider for the list which is a set of persons where each person has a name and image property. We specify the labelField for the List as the name property of a person. Next we create a simple ItemRenderer called PersonRenderer which is used by the List component to display the items.
<mx:Label xmlns:mx="">
    import mx.binding.utils.BindingUtils;

    override protected function createChildren():void

      //Instance the ImageHover object and attach it to
      //the item renderer
      var imageHover:ImageHover = new ImageHover();
      imageHover.parentComponent = this;

      //Create a binding between the image property of the data object
      //and the source property of the ImageHover so it knows which image to display
      BindingUtils.bindProperty( imageHover, "source", this, ["data","image"] );

      //Create a binding between the name property of the data object
      //and the title property of the ImageHover so it knows which title to display
      BindingUtils.bindProperty( imageHover, "title", this, ["data","name"] );        

This renderer is based on the Label component. Since it implements IDataRenderer we can use it almost 'as is' in the List. We override createChildren() where we attach our ImageHover component to the renderer. This component is what actually displays the details window when we hover over the renderer. There are only three properties we set on this component, the title and the source, which we bind to the name and image properties of our person, and the parentComponent which is the component that we want the hover detail window to appear over. Let's look at the ImageHover component to see how it works:
<HoverComponent xmlns="*" xmlns:mx="">
  <!-- Simple extension of the HoverComponent to display
    an image specified by the source property with a title -->

    [Bindable] public var source:String;
    [Bindable] public var title:String;

  <mx:Panel paddingBottom="5"
    <mx:Image id="image" source="{source}"/>

This component is very simple and only consists of a Panel with a title and an Image component inside the Panel. The key thing is that it extends HoverComponent, which provides the hover capabilities. You can modify the ImageHover to do just about anything as long as it extends the HoverComponent. So, finally let's look at the HoverComponent class:
    import flash.geom.Point;
    import flash.utils.Timer;

    import mx.containers.Canvas;
    import mx.core.UIComponent;
    import mx.managers.PopUpManager;

    public class HoverComponent extends Canvas
      public var delay:Number = 1000;
      private var _parentComponent:UIComponent;

      private var timer:Timer;
      private var popped:Boolean = false;

      public function set parentComponent( parentComponent:UIComponent ):void
        _parentComponent = parentComponent;
        if ( _parentComponent != null )
          var thisComponent:UIComponent = this;

          //Detects mouse overs and starts a timer to display the hover
          parentComponent.addEventListener( MouseEvent.MOUSE_OVER, function( evt:MouseEvent ):void
            //Initialize the timer to trigger one time after delay millis
            timer = new Timer( delay, 1 );

            //Wait for the timer to complete
            timer.addEventListener(TimerEvent.TIMER_COMPLETE, function( tevt:TimerEvent ):void
              //move to a position relative to the mouse cursor
              thisComponent.move( evt.stageX + 20, evt.stageY + 20 );

              //Popup the hover component
              PopUpManager.addPopUp( thisComponent, parentComponent );

              //Set a flag so we know that a popup actually occurred
              popped = true;

            //start the timer

          parentComponent.addEventListener( MouseEvent.MOUSE_OUT, function( evt:MouseEvent ):void
            //If the timer exists we stop it
            if ( timer )
              timer = null;

            //If we popped up, remove the popup
            if ( popped )
              PopUpManager.removePopUp( thisComponent );
              popped = false;

      public function get parentComponent():UIComponent
        return _parentComponent;

The HoverComponent class extends the Canvas component. It adds a delay property, which is the amount of time in milliseconds that you need to hover over an item before the window displays. It also adds the parentComponent property which is the item that you want the hover to appear over. The default delay is 1 second. When you set the parentComponent, a mouseOver and mouseOut listener get added to the parentComponent. When you mouseOver, a timer gets started. When the timer completes, the hover component gets positioned and uses PopUpManager to display itself. When you mouseOut, the timer will get cancelled if it is not completed, and the hover window is removed, if it was displayed.

So with the HoverComponent class we have a simple and re-usable way to create custom hover detail windows. Just create your window by extending the HoverComponent and attach it to the component you want it to appear over like we did in the PersonRenderer.

Here is a demo and the source code.

Unable to initialize flash content