May 07, 2008

Ruth G. Chamberlain

In memoriam...

Ruth Chamberlain

Early in the morning of April 28, 2008, my mother, Ruth Chamberlain, passed away. She was 89 years old and suffered from emphysema.

My mother often worked two jobs while I was growing up and it was while she was working that she was most happy. She managed to work until she was 86 and was, at the time, the oldest employee of A.C. Moore. I think I take after her in that respect.

I am not writing this article for your sympathy, but to be another voice and to challenge you and remind you of the effects of smoking. You see, my mother smoked most of her adult life. She quit smoking in her 60s, but still, 20 years later, it caught up with her.

She spent her last years in a nursing home because of her breathing. She had to be on oxygen all of the time and took medication several times a day. Toward the end her breathing became more and more difficult until she couldn't do it any longer.

If you smoke - STOP NOW. For yourself, for those you love and who love you. STOP NOW for your friends and co-workers. STOP NOW for your pets too.

My mother was fond of St. Jude's Children's Hospital. If you care to make a donation I know they would love it.

Thanks to my mom for raising me and giving me the opportunity to work and do what I love to do best.

Posted by pent at 03:06 PM

Return to Normal

Our blogging server is back and my blog, along with a bushel of others, have been restored.

Now I can work on my back-log of articles.

Posted by pent at 03:02 PM

April 09, 2008

Adobe Media Player

,

Adobe's just released a new product- the Adobe Media Player. This application is built upon AIR using the Flex 3 SDK. The AMP is a new type of video player.

As I write this I'm watching an episode of Star Trek: The Original Series from January 1968. It looks terrific and streams smoothly. There are a dozens of shows to choose from.

I personally think this is paving the way for the future of home entertainment. Why be at the mercy of the cable or satellite companies when the content you want to watch is available when you want to watch it. Right now you can download movies from iTunes and Amazon Unbox. NBC and FOX have the Hulu joint venture with movies and TV shows. I haven't rented a movie at a movie rental store in who-knows-how-long.

For me, the problem is making the interface to these services as easy as bringing up the guide on my TiVo and as simple to connect all the boxes together.

Here's an excerpt from the announcement:

It [AMP] provides high quality video playback of streamed, downloaded, or locally stored Internet TV shows and video podcasts. Users can subscribe to Internet television shows and other online video content, have them download automatically in the background, and later view them on demand. AMP's user interface optimizes the user experience, allowing users to easily enjoy finding and viewing their favorite shows.

AMP represents a tool that is not only important to consumers, but publishers who want to monetize advertisements.  The last couple of months we have been working very hard to get the top broadcasters signed to provide content through AMP. We have successfully signed CBS, MTV and Food Network as just a few that will be part of our launch.

Download Adobe Media Player today!

Posted by pent at 05:38 PM | Comments (0)

April 02, 2008

itemRenderers: Part 5: Efficiency

,,,

If you are displaying a large number of itemRenderers - either in the DataGrid or AdvancedDataGrid - your application's performance may be adversely affected if you do not code these itemRenderers effeciently. Here are some tips that might help:

  • Limit the number of columns using itemRenderers. Do you really need to have every column be a custom itemRenderer? Sometimes you do, but is all that glitz overwhelming the user?
  • Try not to change the style of the elements in your itemRenderer too frequenty. If you need to switch styles (eg, green for positive values, red for negative values), consider having 2 controls preset with those styles and making one visible. Changing styles is one of the more time-consuming tasks in Flex.
  • Do not use Containers as the basis for your itemRenderers. Containers have a lot of overhead. They are fine for limited use, but it would be more efficient to write your itemRenderers based on UIComponent.

Switching Styles

Here's an itemRenderer which switches components depending on the value of the data field.

<mx:Canvas>
    <mx:Script><![CDATA
        private function lessThanZero() : Boolean {
           return data.price < 0;
        }
    ]]></mx:Script>
    <mx:Label text="{data.price}" color="#FF0000" visible="{lessThanZero()}" />
    <mx:Label text="{data.price}" color="#00FF00" visible="{!lessThanZero()}" />
</mx:Canvas>

This will be faster than setting the style. Some other things to keep in mind:

  • Avoid data binding to styles. Not only is changing styles slower than most operations, adding data binding code on top of it just makes it worse.
  • Use a Canvas or extend ListItemRenderer or as the root of the itemRenderer. This allows you to place controls on top of each other.

Extending UIComponent

By far the most efficient way to write an itemRenderer is to extend UIComponent using an ActionScript class. You'll have complete control of the code and the renderer will be as efficient as possible.

Let's start with the example above, switching styles, and write a simple itemRenderer extending UIComponent. 

package renderers
{
	import mx.controls.listClasses.IListItemRenderer;
	import mx.core.UIComponent;

	public class PriceItemRenderer extends UIComponent implements IListItemRenderer
	{
		public function PriceItemRenderer()
		{
			super();
		}
		
	}
}

You'll notice that not only did I write the class to extend UIComponent, I also have it implementing the IListItemRenderer interface. It is necessary to do this because a list control will expect any renderer to implement this interface and if you do not, you'll get a runtime error as the list attempts to cast the renderer to this interface.

If you read the documentation on IListItemRenderer you'll see that is an amalgamation of many other interfaces, most of which UIComponent implements for you. But there is one interface extended by IListItemRenderer that UIComponent does not implement: IDataRenderer. This requires you to add the code to give the itemRenderer class the data property you've been using all along.

If you attempt to use this class without implementing IDataRenderer you'll get these errors when you compile the code:

1044: Interface method get data in namespace mx.core:IDataRenderer not implemented by class renderers:PriceItemRenderer.
1044: Interface method set data in namespace mx.core:IDataRenderer not implemented by class renderers:PriceItemRenderer.

Edit this class and change it to the following:

package renderers
{
	import mx.controls.listClasses.IListItemRenderer;
	import mx.core.UIComponent;
	import mx.events.FlexEvent;


	public class PriceItemRenderer extends UIComponent implements IListItemRenderer
	{
		public function PriceItemRenderer()
		{
			super();
		}
		
		// Internal variable for the property value.
	    private var _data:Object;
	    
	    // Make the data property bindable.
	    [Bindable("dataChange")]
	    
	    // Define the getter method.
	    public function get data():Object {
	        return _data;
	    }
	    
	    // Define the setter method, and dispatch an event when the property
	    // changes to support data binding.
	    public function set data(value:Object):void {
	        _data = value;
	    
	        dispatchEvent(new FlexEvent(FlexEvent.DATA_CHANGE));
	    }
		
	}
}

I took the code directly from the Flex documentation for IDataRenderer, so you don't even have to type it yourself.

With that out of the way we can add in the two labels.

  1. Add variables to hold the two labels. 
    		private var posLabel:Label;
		private var negLabel:Label;
  2. Modify the set data function to call invalidateProperties(). This is important because the change of the data has to make the text in the labels change AND to change their visibility. 
    	    public function set data(value:Object):void {
	        _data = value;
	    
	    	invalidateProperties();
	        dispatchEvent(new FlexEvent(FlexEvent.DATA_CHANGE));
	    }
    Calling invalidateProperties() tells the Flex framework to call the commitProperties() function at the apppriate time.
  3. Override createChildren() and create the labels, adding them to the display list of the component. Notice that in addition to creating the labels, their styles and visible are also set. 
    		override protected function createChildren() : void
		{
			super.createChildren();
			
			posLabel = new Label();
			posLabel.visible = false;
			posLabel.setStyle("color", 0x00FF00);
			addChild(posLabel);
			
			negLabel = new Label();
			negLabel.visible = false;
			negLabel.setStyle("color", 0xFF0000);
			addChild(negLabel);
		}
  4. Override commitProperties() to set the labels' text and visibility. In the past you've been overriding set data to make this type of change, and you can do that in this class, too, if you prefer. 
    		override protected function commitProperties():void
		{
			super.commitProperties();
	        posLabel.text = data.price;
	        negLabel.text = data.price;
	        
	        posLabel.visible = Number(data.price) > 0;
	        negLabel.visible = Number(data.price) < 0;
		}
  5. Override updateDisplayList() to size and position the labels. You must size the labels because their default size is 0x0. This is another thing a Container class will do for you. Since this is a pretty simple itemRenderer you can just set the labels' size to match the size of the itemRenderer. 
    		override protected function updateDisplayList( unscaledWidth:Number, unscaledHeight:Number ) : void
		{
			super.updateDisplayList(unscaledWidth, unscaledHeight);
			
			posLabel.move(0,0);
			posLabel.setActualSize(unscaledWidth,unscaledHeight);
			
			negLabel.move(0,0);
			negLabel.setActualSize(unscaledWidth, unscaledHeight);
		}

All this probably seems a bit complicated just to do this, but keep in mind that using a container will add a lot more code than this.

UIComponent Notes

The UIComponent class is the basis for all visual Flex components - controls and containers. Here are some tips about using UIComponent as your itemRenderer.

  • UIComponent imposes no layout restrictions on its children (unlike a Container). You have to position and size the children yourself.
  • It is also possible to draw graphics and position children beyond the size specified in updateDisplayList().
  • If you plan on using variableRowHeight in your list, you should also override the measure() function to give the list an idea of how big the itemRenderer is.
  • To use UIComponent as an itemRenderer you must implement IDataRenderer.
  • To use the listData property you must implement IDropInListItemRenderer; that was covered in a previous article of this series.


Posted by pent at 11:50 AM | Comments (4)

March 27, 2008

itemRenderers: Part 4: States and Transitions

,,,

Communicating the with the user of your application is what your itemRenderer does best. Sometimes that communication is as simple as presenting a name; sometimes more elborately using colors; and sometimes with interactivity.

itemEditors are truely interactive controls, but they are not the focus of this article. In these examples we'll look at itemRenderers that change their visual appearance based on either the data itself or the user's actions.

States

The Flex <mx:State> is a very good way to change the appearance of an itemRenderer. States are easy to use, and when combined with Transitions, give the user feedback and pleasent experience.

In this example we'll create a new MXML itemRenderer (and remember, you can do this completely in ActionScript if you prefer) for the List. All this shows is the image, title, author, price, and a Button to purchase the book.

<?xml version="1.0" encoding="utf-8"?>
<mx:HBox xmlns:mx="http://www.adobe.com/2006/mxml" >

	<mx:Image id="bookImage" source="{data.image}" />
	<mx:VBox height="115" width="100%" verticalAlign="top" verticalGap="0" paddingRight="10">
		<mx:Text text="{data.title}" fontWeight="bold" width="100%"/>
		<mx:Label text="{data.author}" />
		<mx:HBox id="priceBox" width="100%">
			<mx:Label text="{data.price}" width="100%"/>
			<mx:Button label="Buy" />
		</mx:HBox>
	</mx:VBox>
</mx:HBox>

What we want however, is if the book is not in stock (the data has <instock> nodes which are either yes or no) for the price and Book to be invisible. I've made things a bit convenient for myself here because I gave the HBox parent of the price and Button an id. This allows me to change the visibility of both of those items by changing the visibility of the HBox, priceBox.

You can do this by overridding the set data function, which we'll do, but instead of directly changing the visibility of priceBox, we'll use this state defintion:

	<mx:states>
		<mx:State name="NoStockState">
			<mx:SetProperty target="{priceBox}" name="visible" value="false"/>
		</mx:State>
	</mx:states>

    Place this just below the root tag.

This example is a bit far-fetched in that it is overly complicated to do a simple task, but it shows how to use states. There are 2 states:

  • The base state - this is the normal state of a component. Components that do not use states simply have this base state. In this example, the base state has the priceBox visible property as true (the default). This is the case when instock is "yes".
  • The NoStockState - this is the state when the value of nostock is "no". When this state is active the SetProperty instructions are carried out. The target determines which member of the class is in question, the name property is the name of the property to change on the target, and value is the new value for the property.

The set data function determines which state to use by looking at the value of instock:

		override public function set data( value:Object ) : void
		{
			super.data = value;
			
			if( data )
			{
				if( data.instock == "yes" ) 
					currentState = "";
				else
					currentState = "NoStockState";
			}
		}

The currentState is a property of all UIComponent controls. It determines which State is the active one. When switching between states the Flex framework begins with the base state and then applies the rules for the given state.

Remember that itemRenderers are recycled, so you must always restore values; never leave an if without an else in an itemRenderer.

If you are feeling adventurous, you can do away with the set data override in this example. Instead, set currentState directly in the root tag by using data binding expression: 

<mx:HBox xmlns:mx="http://www.adobe.com/2006/mxml" width="400" 
       currentState="{data.instock == 'yes' ? '' : 'NoStockState'}" >

The currentState's value is set by examining data.instock right inline with the root tag. A nice trick, but it might be harder to maintain.

Adding Elements

In this itemRenderer the price and Buy button appears only if the instack value is yes. You could do this without a state of course, but if your itemRenderer has more controls to be added or removed, a state will make more sense as their appearance is controlled simply by setting the itemRenderer's currentState property.

Instead of just removing the price and Button, we'll have the state add a label telling the user the item is out of stock. Here's the modified state:

	<mx:states>
		<mx:State name="NoStockState">
			<mx:SetProperty target="{priceBox}" name="visible" value="false"/>
			<mx:AddChild relativeTo="{priceBox}" position="before">
				<mx:Label text="-- currently not in stock --" color="#73DAF0"/>
			</mx:AddChild>
		</mx:State>
	</mx:states>

The <mx:AddChild> tag says to add the Label into the priceBox. In addition to setting the priceBox's visible property to false, a friendly message replaces it.

Again, you could add this label in the set data function - or add it initially and just set its visibility to false and change it to true in the set data function. But I think you can see the value of the State: if the requirement for the instock being no condition gets more complex, all you need to do is adjust the NoStockState; the ActionScript code which switches the state remains the same.

You can modify states in Flex Builder's Design View.

Expanding List

This example does not work well for list controls but does perform nicely for a VBox and Repeater. This question of expanding an item in place becomes dicy when the list has to be scrolled. Imagine this: you've got a list of items will all the same height. Now you exand the height of item 2. So far so good - item 2 is taller than the other visible items. And there's the catch: the visible items. Now scroll the list. Remember that itemRenderers are recycled. So when item 2 scrolls out of view, its itemRenderer will be moved to the bottom of the list. You've got to reset its height. OK, that can work pretty simply. Now scroll the list so item 2 is back in view. You would expect it to be the expanded height. How does the itemRenderer know to do that? From previous articles you know that information either comes from the data itself or from some external source.

I think a resizing itemRenderer is too complex and not really worth the effort. I believe there is a better way to do this using VBox and Repeater. However, the catch with Repeater is that every child will be created. If you have 1,000 records and use a Repeater you will get 1,000 instances of your itemRenderer.

For this example you'll still write an itemRenderer but will use it as the child of a VBox.  The elements of a list look pretty simple: the name of a book and its author. But click the itemRenderer and it expands in place. This is accomplished using:

  • The itemRenderer has a state which includes the additional information.
  • The itemRenderer uses a Resize transition to give a smoother expansion and contraction of the itemRenderer.

The base state of the itemRenderer is pretty simple: 

	<mx:HBox width="100%">
		<mx:Label text="{data.author}" fontWeight="bold"/>
		<mx:Text  text="{data.title}" width="100%" fontSize="12" selectable="false"/>
	</mx:HBox>

The ExpandedState adds the additional elements which contribute to the itemRenderer's height:

	<mx:states>
		<mx:State name="ExpandedState">
			<mx:AddChild position="lastChild">
				<mx:HBox width="100%">
					<mx:Image source="{data.image}"/>
					<mx:Spacer width="100%"/>
					<mx:Label text="{data.price}"/>
					<mx:Button label="Buy"/>
				</mx:HBox>
			</mx:AddChild>
		</mx:State>
	</mx:states>

Getting the itemRenderer to change size is as simple as adding a Transition:

	<mx:transitions>
		<mx:Transition fromState="*" toState="*">
			<mx:Resize target="{this}" />
		</mx:Transition>
	</mx:transitions>

    Place this below the <mx:states>

The Transition is applied whenever the state changes because its fromState and toState properties are wildcards. Now all you have to do is add event handler for clicking on the itemRenderer (add a click event to the root tag) and change the state:

	<mx:Script>
	<![CDATA[
		
		private function expandItem() : void
		{	
			if( currentState == "ExpandedState" )
				currentState = "";
			else
				currentState = "ExpandedState";
		}
	]]>
	</mx:Script>

Summary

States are a great way to make a number of modifications to the visual appearance of the itemRenderer. You can group the changes in a State and simply make it all happen by setting the currentState property of the itemRenderer.

In the next article we'll look at writing more efficient itemRenderers by extending UIComponent.

Posted by pent at 04:22 PM | Comments (0)

March 25, 2008

Viewing PDFs with AIR

,,,

One of the nice things AIR allows is the ability to view both HTML and PDF content. Here's a little app that shows how you can view PDF documents on the local computer.

The key is the flash.html.HTMLLoader class. This is a FLASH class and cannot be directly used with Flex components as it extends Sprite and does not implement the Flex IUIComponent interface.

This is easy to remedy though. Just create a new class that extends UIComponent (I called mine PDFViewer) and include an HTMLLoader member. Override createChildren() to make a new HTMLLoader instance and add it to the UIComponent's display list. Then override updateDisplayList to size and position it.

The main AIR application uses a FileSystemTree to allow the user to navigate to their PDF files and select one. The file's URL is passed to the PDFViewer which then loads it and displays it.

And that's pretty much it. There are some caveats to use PDF with AIR which you can read in the documentation, but if you want to use PDFs for help/documentation on your product or to display a PDF generated by a server (eg, ColdFusion), it is pretty easy to do.

Download Example Code

Posted by pent at 10:30 AM

March 14, 2008

itemRenderers: Part 3: Communication

,,

In the previous article of this series I showed you how to make external itemRenderers in both MXML and ActionScript. In the examples I've been using there is a Button which dispatches a custom event - BuyBookEvent - so the application can react to it. This article covers communication with itemRenderers in more detail.

There is a rule I firmly believe must never be violated: you should not get hold of an instance of an itemRenderer and change it (setting public properties) or call its public methods. This, to me, is a big no-no. The itemRenderers are hard to get at for a reason which I talked about in the first article: the itemRenderers are recycled. Grabbing one breaks the Flex framework.

With that rule in mind, here are things you can do with an itemRenderer:

  • An itemRenderer can dispatch events via its list owner (you've seen bubbling, this is a better practice which you'll see below).
  • An itemRenderer can use static class members. This includes Application.application. If you have values stored "globally" on your application object, you can reach them that way.
  • An itemRenderer can use public members of the list which owns it. You'll see this below.
  • An itemRenderer can use anything in the data record. You might, for example, have an item in a record that's not for direct display but which influences how an itemRenderer behaves.

Dynamically Changing the itemRenderer

Here is the MXML itemRenderer from the previous article used for a TileList. We're going to make it bit more dynamic by having it react to changes from an external source (I called this file BookItemRenderer.mxml):

<?xml version="1.0" encoding="utf-8"?>
<mx:HBox xmlns:mx="http://www.adobe.com/2006/mxml" width="250" height="115" >
	
	<mx:Script>
	<![CDATA[		
	]]>
	</mx:Script>
	
	<mx:Image id="bookImage" source="{data.image}" />
	<mx:VBox height="115" verticalAlign="top" verticalGap="0">
		<mx:Text text="{data.title}" fontWeight="bold" width="100%"/>
		<mx:Spacer height="20" />
		<mx:Label text="{data.author}" />
		<mx:Label text="Available {data.date}" />
		<mx:Spacer height="100%" />
		<mx:HBox width="100%" horizontalAlign="right">
			<mx:Button label="Buy" fillColors="[0x99ff99,0x99ff99]">
				<mx:click>
				<![CDATA[
					var e:BuyBookEvent = new BuyBookEvent();
					e.bookData = data;
					dispatchEvent(e);
				]]>
				</mx:click>
			</mx:Button>
		</mx:HBox>
	</mx:VBox>
	
</mx:HBox>

Suppose you are showing a catalog of items in a TileList. You also have a Slider (not part of the itemRenderer) which lets the user give a range of prices; all items which fall outside of the range should fade out (the itemRenderers' alpha value should change). You need to tell each itemRenderer that the criteria has changed so that they can modify their alpha values.

Your override of set data might look something like this:

override public function set data( value:Object ) : void
{
    super.data = value;
    if( data.price < criteria ) alpha = 0.4;
    else alpha = 1;
}

The question is: how to change the value for criteria? The "best practice" for itemRenderers is to always have them work on the data they are given. In this case, it is unlikely, and impractical, to have the test criteria be part of the data. So that leaves a location outside of the data:

  • Part of the list itself. That is, your list (List, DataGrid, TileList, etc) could be a class that extends a list control and which has this criteria as a public member.
  • Part of the application as global data.

For me, the choice is the first one: extend a class and make the criteria part of that class. After all, the class is being used to display the data, the criteria is part of that display. For this example, I would extend TileList and have the criteria as a public data member. 

package
{
	
	import mx.controls.TileList;
	
	public class CatalogList extends TileList
	{
		public function CatalogList()
		{
			super();
		}
		
		private var _criteria:Number = 10;
		
		public function get critera() : Number
		{
			return _criteria;
		}
		
		public function set criteria( value:Number ) : void
		{
			_criteria = value;
		}		
	}
}

The idea is that a control outside of the itemRenderer can modify the criteria by changing this public property on the list control.

listData

The itemRenderers have access to another piece of data: information about the list itself and which row and column (if in a column-oriented control) they are rendering. This is known as listData and it could be used like this in the BookItemRenderer.mxml itemRenderer example:

override public function set data( value:Object ) : void
{
    super.data = value;
    var criteria:Number = (listData.owner as MyTileList).criteria;
    if( data.price < criteria ) alpha = 0.4;
    else alpha = 1;
}

    Place this code into the <mx:Script> block in the example BooktItemRenderer.mxml code, above.

The listData property of the itemRenderer has an owner field which is the control to which the itemRenderer belongs. In this example, it is the MyTileList - my extension of TileList - which is the owner. Casting the owner field to MyTileList allows the criteria to be fetched.

IDropInListItemRenderer

Access to listData is available when the itemRenderer class implements the IDropInListItemRenderer interface. Unfortunately, UI container components do not implement the interface which gives access to the listData. Control component such as Button and Label do, but for containers you have to implement the interface yourself.

Implementing this interface is straightforward and found in the Flex documentation. Here's what you have to do for our BookItemRenderer class:

  1. Have the class implement the interface. 
    <mx:HBox xmlns:mx="http://www.adobe.com/2006/mxml" ... implements="mx.controls.listClasses.IDropInListItemRenderer">
  2. Add the set and get functions to the <mx:Script> block in the itemRenderer file. 
    		import mx.controls.listClasses.BaseListData;
	
		private var _listData:BaseListData;
		public function get listData() : BaseListData
		{
			return _listData;
		}
		public function set listData( value:BaseListData ) : void
		{
			_listData = value;
		}

When the list control sees that the itemRenderer implements the IDropInListItemRenderer interface it will create a listData item and assign it to every itemRenderer instance.

invalidateList()

Setting the criteria in my class isn't as simple as assigning a value. Doing that won't tell the Flex framework that the data has been changed. The change to the criteria must trigger an event. Here's the modification to the set criteria function:

		public function set criteria( value:Number ) : void
		{
			_criteria = value;
			
			invalidateList();
		}

Notice that once the _criteria value has been set it calls invalidateList(). This causes all of the itemRenderers to be reset with values from the dataProvider and have their set data functions called.

The process then looks like this:

  1. The itemRenderer looks into its list owner for the criteria to use to help it determine how to render the data.
  2. The list owner class, and extension of one of the Flex list classes, contains public properties read by the itemRenderer(s) and set by external code - another control or ActionScript code (perhaps as the result of receiving data from a remote call).
  3. When the list's property is set it calls the list's invalidateList() method. This triggers a refresh of the itemRenderers, causing them to have their data reset (and back to step 1).

Events

In the previous articles I showed how to use event bubbling to let the itemRenderer communicate with the rest of the application. I think this is certainly quick. But I also think there is a better way, one which fits the assumption that an itemRenderer's job is to present data and the control's job is to handle the data.

The idea of the MyTileList control is that it is the visual - the view - of the catalog of books for sale. When a user picks a book and wants to buy it, it should be the responsibility of the list control to communicate that information to the application. In other words:

<CatalogList bookBuy="addToCart(event)" />

The way things are set up right now, the event bubbles up and bypasses the TileList. The bubbling approach doesn't assoicate the event (bookBuy) with the list control (TileList), allowing you to move the control to other parts of your application. For instance, if you code the event listener for bookBuy on the main Application, you won't be able to move the list control to another part of the application. You'll have to move that event handler, too. If, on the other hand you have the event associated with the control you just move the control.

Look at it this way: suppose the click event on the Button wasn't actually an event dispatched by the Button but bubbled up from something inside of the button. You'd never be able to do: <mx:Button click="doLogin()" label="Log in" /> you would have to put the doLogin() function someplace else and that would make the application even harder to use.

I hope I've convinced you, so here's how to change the example from bubbling to dispatching from the list control.

First, you have to add metadata to the CatalogList control to let the compiler know the control dispatches the event:

	import events.BuyBookEvent;
	import mx.controls.TileList;

	[Event(name="buyBook",type="events.BuyBookEvent")]
	
	public class CatalogList extends TileList
	{

Second, add a function to CatalogList to dispatch the event. This function will be called by the itemRenderer instances:

		public function dispatchBuyEvent( item:Object ) : void
		{
			var event:BuyBookEvent = new BuyBookEvent();
			event.bookData = item;
			dispatchEvent( event );
		}
		
	}

Third, change the Buy button code in the itemRenderer to invoke the function:

			<mx:Button label="Buy" fillColors="[0x99ff99,0x99ff99]">
				<mx:click>
				<![CDATA[
					(listData.owner as CatalogList).dispatchBuyEvent(data);
				]]>
				</mx:click>
			</mx:Button>

Now the Button in the itemRenderer can simply invoke a function in the list control with the data for the record (or anything else that is appropriate for the action) and pass the responsibility of interfacing with the rest fo the application onto the list control.

The list control in this example dispatches an event with the data. The application can add event listeners for this event either using ActionScript or, because of the [Event] metadata in the CatalogList.as file, MXML; using [Event] metadata makes it easier for developers to use your code.

Summary

itemRenderers should communicate any actions using events. Custom events allow you to pass information with the event so the consumer of the event doesn't have to reach out to the itemRenderer for any data.

itemRenderers should "react" to changes in data by overriding their set data functions. Inside of the function they can access values in their listData.owner. They could also access data stored in a static class or in the main application via Application.application.

In the next article we'll look at incorporating states into itemRenders.

Posted by pent at 10:25 AM | Comments (3)

March 06, 2008

itemRenderers: Part 2: External renderers

In Part 1 of this series I showed you how to make an inline itemRenderer. That is, an itemRenderer whose MXML tags and ActionScript code are in the same file as the list using the itemRenderer. The code is "in line" with the rest of the code in the file.

You'll also recall that I said you should think of inline itemRenderers are being separate classes. The Flex compiler in fact extracts that inline code and makes a class for you. What we're going to do in this article is make the class ourselves. The benefit of inline itemRenderers is that the code is in the same place as the list, but that's also a drawback when the itemRenderer becomes complex.

Extracting the itemRenderer into an external file has several benefits:

  • The itemRenderer can easily be used in multiple lists;
  • the code is easier to maintain;
  • you can use Flex Builder's Design View to sketch out the initial itemRenderer.

An MXML itemRenderer

From the previous article you saw there was a complex itemRenderer used for a DataGrid:

<mx:DataGridColumn headerText="Title" dataField="title">
		<mx:itemRenderer>
			<mx:Component>
				<mx:HBox paddingLeft="2">
					<mx:Script>
					<![CDATA[
						override public function set data( value:Object ) : void {
							super.data = value;
							var today:Number = (new Date()).time;
							var pubDate:Number = Date.parse(data.date);
							if( pubDate > today ) setStyle("backgroundColor",0xff99ff);
							else setStyle("backgroundColor",0xffffff);
						}
					]]>
					</mx:Script>
					<mx:Image source="{data.image}" width="50" height="50" scaleContent="true" />
					<mx:Text width="100%" text="{data.title}" />
				</mx:HBox>
			</mx:Component>
		</mx:itemRenderer>
	</mx:DataGridColumn>

The itemRenderer is based on an HBox, contains an Image and a Text, and the background color is set according to the pubDate field of the item record. You can write this same itemRenderer as an external file using these steps:

  1. If you are using Flex Builder, create a new MXML Component file (I've named mine GridColumnSimpleRenderer, but use whatever you like) and set the root tag to be HBox. Don't worry about the size.
  2. If you are using the SDK alone, create a new MXML file (call it GridColumnSimpleRenderer.mxml) and set the root tag to be HBox.
  3. With the file open, copy everything between <mx:HBox> and </mx:HBox>, but do not copy those tags since they are already in the file. The result should look something like this: 
    <?xml version="1.0" encoding="utf-8"?>
<mx:HBox xmlns:mx="http://www.adobe.com/2006/mxml" width="400" height="300">
	<mx:Script>
	<![CDATA[
		override public function set data( value:Object ) : void {
			super.data = value;
			var today:Number = (new Date()).time;
			var pubDate:Number = Date.parse(data.date);
			if( pubDate > today ) setStyle("backgroundColor",0xff99ff);
			else setStyle("backgroundColor",0xffffff);
		}
	]]>
	</mx:Script>
	<mx:Image source="{data.image}" width="50" height="50" scaleContent="true" />
	<mx:Text width="100%" text="{data.title}" />
</mx:HBox>
  4. Save the file.

Now modify the DataGridColumn definition by removing the inline itemRenderer and replacing it with this:

<mx:DataGridColumn headerText="Title" dataField="title" itemRenderer="GridColumnSimpleRenderer">

Now run the application. You'll get a surprise.

The surprise is how tall the rows are. That's because of the presence of height="300" on the itemRenderer.

Determining an itemRenderer's width and height

The list control always sets the itemRenderer's width. In this example, the explicit width="400" is ignored. You should write your itemRenderer to assume the width will change as the user changes the column or list's width.

The height is a different matter. If the list has an explicit rowHeight set, it will impose that height on each row, ignoring any height you've set on the itemRenderer. However, if you set the list's variableRowHeight property to true, then the list will seriously consider the itemRenderer's height. In this example, the height is explicitly set to 300, so each row is 300 pixel's high.

To fix this, remove the explict height from the itemRenderer file and the application will work correctly.

Dynamically Changing the itemRenderer

In this example the set data function has been overridden to examine the data and set the itemRenderer's backgroundColor. This is very common. Overriding set data allows you to intercept the time when the data is being changed for a new row and you can you make style changes.

Common mistakes are:

  • Forgetting to call super.data = value; this is VITAL - failure to do this will really mess up your itemRenderer;
  • Forgetting to reset the style(s) if any tests fail. It might be tempting to just set the color when the pubDate is in the future, but you have to remember that itemRenderers are recycled and so the else statement is very necessary.

An ActionScript itemRenderer

Now we'll write another itemRenderer, this time using an ActionScript class. In the previous article there is a TileList with this inline itemRenderer:

	<mx:itemRenderer>
		<mx:Component>
			<mx:HBox verticalAlign="top">
				<mx:Image source="{data.image}" />
				<mx:VBox height="115" verticalAlign="top" verticalGap="0">
					<mx:Text text="{data.title}" fontWeight="bold" width="100%"/>
					<mx:Spacer height="20" />
					<mx:Label text="{data.author}" />
					<mx:Label text="Available {data.date}" />
					<mx:Spacer height="100%" />
					<mx:HBox width="100%" horizontalAlign="right">
						<mx:Button label="Buy" fillColors="[0x99ff99,0x99ff99]">
							<mx:click>
							<![CDATA[
								var e:BuyBookEvent = new BuyBookEvent();
								e.bookData = data;
								dispatchEvent(e);
							]]>
							</mx:click>
						</mx:Button>
					</mx:HBox>
				</mx:VBox>
			</mx:HBox>
		</mx:Component>
	</mx:itemRenderer>

We'll make that into an ActionScript, external, itemRenderer. You'll need to follow these steps:

  1. Create a new ActionScript class. Call it BookTileRenderer.as and make it extend HBox, just like the inline itemRenderer. 
    package
{
	import flash.events.MouseEvent;
	
	import mx.containers.HBox;
	import mx.containers.VBox;
	import mx.controls.Button;
	import mx.controls.Image;
	import mx.controls.Label;
	import mx.controls.Spacer;
	import mx.controls.Text;
	
	public class BookTileRenderer extends HBox
	{
		public function BookTileRenderer()
		{
			super();
		}
		
	}
}
  2. Create member variables to hold the references to the child components. 
    		private var coverImage:Image;
		private var titleText:Text;
		private var spacer1:Spacer;
		private var authorLabel:Label;
		private var pubdateLabel:Label;
		private var spacer2:Spacer;
		private var buyButton:Button;
  3. Override the createChildren() function to create the child components and add them to the HBox. 
    		override protected function createChildren():void
		{
			coverImage = new Image();
			addChild(coverImage);
			
			var innerBox:VBox = new VBox();
			innerBox.explicitHeight = 115;
			innerBox.percentWidth = 100;
			innerBox.setStyle("verticalAlign","top");
			innerBox.setStyle("verticalGap", 0);
			addChild(innerBox);
			
				titleText = new Text();
				titleText.setStyle("fontWeight","bold");
				titleText.percentWidth = 100;
				innerBox.addChild(titleText);
			
				spacer1 = new Spacer();
				spacer1.explicitHeight = 20;
				innerBox.addChild(spacer1);
			
				authorLabel = new Label();
				innerBox.addChild(authorLabel);
			
				pubdateLabel = new Label();
				innerBox.addChild(pubdateLabel);
			
				spacer2 = new Spacer();
				spacer2.percentHeight = 100;
				innerBox.addChild(spacer2);
			
				var buttonBox:HBox = new HBox();
				buttonBox.percentWidth = 100;
				buttonBox.setStyle("horizontalAlign","right");
				innerBox.addChild(buttonBox);
			
					buyButton = new Button();
					buyButton.label = "Buy";
					buyButton.setStyle("fillColors",[0x99ff99,0x99ff99]);
					buyButton.addEventListener(MouseEvent.CLICK, handleBuyClick);
					buttonBox.addChild(buyButton);
		}
     I've indented the code to show the parent-child relationships. Also, make sure you include an event listener on the Buy button.
  4. Override the commitProperties() function and set the user interface controls from the data. 
    		override protected function commitProperties():void
		{
			super.commitProperties();
			
			coverImage.source = data.image;
			titleText.text = data.title;
			authorLabel.text = data.author;
			pubdateLabel.text = data.date;
		}
  5. Add the click event handler for the Buy button. 
    		private function handleBuyClick( event:MouseEvent ) : void
		{
			var e:BuyBookEvent = new BuyBookEvent();
			e.bookData = data;
			dispatchEvent(e);
		}
  6. Modify the TileList in the main application to use the itemRenderer ActionScript class. Simply remove the inlineItemRenderer and replace it with an itemRenderer property right in the tag. 
    <mx:TileList id="mylist" x="29" y="542" width="694" itemRenderer="BookTileRenderer" 
       dataProvider="{testData.book}" height="232" columnWidth="275" rowHeight="135" >

If you are going to use an existing container class, such as HBox, I wouldn't bother doing this in ActionScript. You can see it is more complex than using an MXML file and, quite frankly, there is little performance benefit to it.

Reusable itemRenderers

Here's an example of an itemRenderer that displays a numeric value using the CurrencyFormatter. I call it PriceFormatter: 

<?xml version="1.0" encoding="utf-8"?>
<mx:Text xmlns:mx="http://www.adobe.com/2006/mxml">

	<mx:Script>
		<![CDATA[
			import mx.controls.dataGridClasses.DataGridListData;
			
			[Bindable] private var formattedValue:String;
			
			override public function set data(value:Object):void
			{
				super.data = value;
				
				formattedValue = cfmt.format( Number(data[(listData as DataGridListData).dataField]) );
			}
		]]>
	</mx:Script>
	
	<mx:CurrencyFormatter precision="2" id="cfmt" />
	
	<mx:text>{formattedValue}</mx:text>
	
</mx:Text>

The key to this itemRenderer is shown in red, setting the bindable variable, formattedValue. First, you'll see that <mx:CurrentFormatter> was defined as an MXML tag (you can do this in ActionScript, too, if you prefer) with an id of cfmt. In the example above, the formattedValue is set to the result of calling the CurrentFormatter's format() function.

The function takes a Number as its parameter type, so the value is cast to Number - that's because the dataProvider for the list is XML and everything in XML is text; if you use a Object for your data and you have real numeric values, doing the Number cast will be harmless.

As you know, data is the property which holds the item being displayed by the itemRenderer. Using [ ] notation is another way of accessing the fields of the data item. For example, data['price'] would be the price column. But to make this itemRenderer resuable we cannot code for a specific field, so a more generic way is needed.

That's where listData comes in. All Flex components which implement the IDropInListItemRenderer interface have a listData property.

Most controls such as Text, Label, Button, CheckBox, and so forth, implement IDropInListItemRenderer. Most containers, such as HBox, Canvas, etc. do not implement that interface. If you want to use listData in an itemRenderer that extends a Container you will have to implement IDropInListItemRenderer yourself - I'll cover that in the next article.

The listData given to an itemRenderer contains, among other things, the rowIndex and the control which owns the itemRenderer - the DataGrid, List, or TileList. When you have an itemRenderer being used for the DataGrid, the listData is actually a DataGridListData object - which includes the columnIndex and the dataField associated with the DataGridColumn. Here's the breakdown of the statement above, starting from the inside:

  • listData as DataGridListData - This casts the listData to a DataGridListData object so you have access to its dataField
  • .dataField - the field for the column being rendered. This is what makes this itemRenderer generic. You can use this itemRenderer for multiple columns. In this example the dataField is 'price'.
  • data[ ... ] - This accesses the data for the specific field in the item. In this example it will be the price column.
  • Number( ... ) - This casts the value to a Number because the format() function requires a Number parameter.
  • cfmt.format( ... ) - This formats the value as a currency.

Summary

Use whatever makes you comfortable when implementing itemRenderers. Some people only work in ActionScript which is great when you've got experience with Flex and ActionScript. MXML makes quick work of simple itemRenderers, too.

In a future article we'll look at making more efficient itemRenderers, which are ActionScript classes, but they extend UIComponent. In the next article I'll discuss more communication between itemRenderers and the rest of the application.


Posted by pent at 01:41 PM | Comments (3)

March 03, 2008

itemRenderers: Part 1: inline renderers

,,

I'm starting a new series of articles on itemRenderers. Our documentation team has great examples so please check that information out first. I'm giving you my distillation of it.

Recycling Renderers

One thing many people try to do is access an itemRenderer from outside of the list. For example, you might want to make the cell in the 4th column of the 5th row in a DataGrid turn green because you've just received new data from the server. Getting that itemRenderer instance and modifying it externally would be a huge breech of the Flex framework and component model.

To understand itemRenderers you have to understand why they are what they are and what our intentions were when we designed them. BTW - when I say 'we' I really mean the Adobe Flex engineering team - I had nothing to do with it. Anyway, suppose you have 1000 records you want to show. If you think the list control creates 1000 itemRenderers you are incorrect. If the list is showing only 10 rows, the list creates about 12 itemRenderers - enough to show every visible row plus a couple for buffering and performance reasons. The list initially shows rows 1 through 10. When the user scrolls the list it may now be showing rows 3 - 12. But those same 12 itemRenderers are still there - no new itemRenderers were created, even after the list scrolled.

Here's what we do. When the list is scrolled, those itemRenderers which will still be showing the same data (rows 3 - 10) are moved upward. Aside from being in a new location, they haven't changed. The itemRenderers that were showing the data for rows 1 and 2 are now moved below the itemRenderer for row 10. Then those itemRenderers are given the data for rows 11 and 12. In other words, unless you resize the list, those same itemRenderers are reused - recycled - to a new location and are now showing new data.

If you want to change the background color of the cell in the 4th column of the 5th row, be aware that the itemRenderer for that cell may now be showing the contents of the 21st row if the user has scrolled the list.

So how do you make changes like this?

The itemRenderers must change themselves based on the data they are given to show. If the itemRenderer for the list is supposed to change its color based on a value of the data, then it must look at the data it is given and change itself.

inline itemRenderers

In this article we'll look at the answer to this problem using inline itemRenderers. An inline itemRenderer is one which is written directly in the MXML file where the list control occurs. In the next article we'll look at writing external itemRenderers. The inline itemRenderers are the least complex and are generally used for very simple renderers or for prototyping a larger application. There's nothing wrong with inline itemRenderers, but when the code becomes complex it is better to extract it into its own class.

In all of the examples we'll use the same data: a collection of information about books: author, title, publication date, thumbnail image, and so forth. Each record is an XML node which looks like this:

<book>
    <author>Peter F. Hamilton</author>
    <title>Pandora's Star</title>
    <image>assets/pandoras_star_.jpg</image>
    <date>Dec 3, 2004</date>
</book>

Let's start with a simple itemRenderer using a <mx:List> control. Here, the author is listed followed by the title of the book. 

	<mx:List x="29" y="67" dataProvider="{testData.book}" width="286" height="190">
		<mx:itemRenderer>
			<mx:Component>
				<mx:Label text="{data.author}: {data.title}" />
			</mx:Component>
		</mx:itemRenderer>
	</mx:List>

This itemRenderer is so simple that a labelFunction would probably have been better, but it at least lets you focus on the important parts. First, an inline itemRenderer uses the <mx:itemRenderer> tag to define it. Within this tag is the <mx:Component> tag. This tag must be here as it tells the Flex complier you are defining a component inline. We'll discuss what this really means in a bit.

Within the <mx:Component> tag you define your itemRenderer. For this example it is a single <mx:Label> with its text field set to a data-binding expression: {data.author}: {data.title}. This is very important. The list control gives each itemRenderer instance the record of the dataProvider by setting the itemRenderer's data property. Looking at the code above, it means that for any given row of the list, the itemRenderer instance of its inline itemRenderer will have its data property set to a <book> XML node (such as the one above). As you scroll through the list, the data property is being changed as the itemRenderers are recycled for new rows.

In other words, the itemRenderer instance for row 1 might have its data.author set to "Peter F. Hamilton" now, but when it scrolls out of view, the itemRenderer will be recycled and the data property - for that same itemRenderer - may now have its data.author set to "J.K. Rowling". All of this happens automatically as the list scrolls - you don't worry about it.

Here's a more complex inline itemRenderer using the <mx:List> control again:

	<mx:List x="372" y="67" width="351" height="190" variableRowHeight="true" dataProvider="{testData.book}">
		<mx:itemRenderer>
			<mx:Component>
				<mx:HBox >
					<mx:Image source="{data.image}" width="50" height="50" scaleContent="true" />
					<mx:Label text="{data.author}" width="125" />
					<mx:Text  text="{data.title}" width="100%" />
				</mx:HBox>
			</mx:Component>
		</mx:itemRenderer>
	</mx:List>

This really isn't much different. Instead of a <mx:Label> the itemRenderer is an <mx:HBox> with an <mx:Image>, <mx:Label>, and a <mx:Text> control. Data-binding still relates the visual with the record.

DataGrid

You can use inline itemRenderers on a DataGrid, too. Here's one applied to a column:

	<mx:DataGrid x="29" y="303" width="694" height="190" dataProvider="{testData.book}" variableRowHeight="true">
		<mx:columns>
			<mx:DataGridColumn headerText="Pub Date" dataField="date" width="85" />
			<mx:DataGridColumn headerText="Author" dataField="author" width="125"/>
			<mx:DataGridColumn headerText="Title" dataField="title">
				<mx:itemRenderer>
					<mx:Component>
						<mx:HBox paddingLeft="2">
							<mx:Script>
							<![CDATA[
								override public function set data( value:Object ) : void {
									super.data = value;
									var today:Number = (new Date()).time;
									var pubDate:Number = Date.parse(data.date);
									if( pubDate > today ) setStyle("backgroundColor",0xff99ff);
									else setStyle("backgroundColor",0xffffff);
								}
							]]>
							</mx:Script>
							<mx:Image source="{data.image}" width="50" height="50" scaleContent="true" />
							<mx:Text width="100%" text="{data.title}" />
						</mx:HBox>
					</mx:Component>
				</mx:itemRenderer>
			</mx:DataGridColumn>
		</mx:columns>
	</mx:DataGrid>

As you can see, this is much more complex than the last two, but it has the same structure: <mx:itemRenderer> with <mx:Component> definition inside of it.

The purpose of <mx:Component> is to provide an MXML syntax for creating an ActionScript class right in the code. Picture the code that appears in the <mx:Component> block being cut out and put into a separate file and given a class name. When you look at the inline itemRenderer it does look like a complete MXML file, doesn't it? There's the root tag (<mx:HBox> in this case) and even a <mx:Script> block.

The purpose of the <mx:Script> block in this example is to override the set data function so the background color of the itemRenderer can be changed. In this case, the background is changed from white whenever the publication data for a book is in the future. Remember that itemRenderers are recycled, so the color must also be set back to white if the test fails. Otherwise all of the itemRenderers will eventually turn purple as the user scrolls through the list.

outerDocument

The scope has also changed. What I mean is, variables that you define from within a <mx:Component> are only scoped to that component/inline itemRenderer. Likewise, the content outside of the <mx:Component> is in a different scope, just as if this component were defined in a separate file. For instance, suppose you add a Button to this itemRenderer that allows the user to by the book from an online retailer. Buttons call functions on their click event, so you might define the button like this:

<mx:Button label="Buy" click="buyBook(data)" />

If the buyBook() function were defined in the <mx:Script> block of the file you would get an error saying that buyBook() is an undefined method. That's because buyBook() is defined in the scope of the file, not in the scope of the <mx:Component>. Since this is a typical use case there is a way around that using the outerDocument identifier:

<mx:Button label="Buy" click="outerDocument.buyBook(data)" />

The outerDocument identifier changes the scope to look into the file, or outer document, with reference to the <mx:Component>. Now beware: the function has to be a public function, not a protected or private one. Remember that <mx:Component> is treated as an externally defined class.

Bubbling Events

Let's look at another, even more complex example. This is a TileList using the same data.

	<mx:TileList x="29" y="542" width="694" dataProvider="{testData.book}" height="232" columnWidth="275" rowHeight="135" >
		<mx:itemRenderer>
			<mx:Component>
				<mx:HBox verticalAlign="top">
					<mx:Image source="{data.image}" />
					<mx:VBox height="115" verticalAlign="top" verticalGap="0">
						<mx:Text text="{data.title}" fontWeight="bold" width="100%"/>
						<mx:Spacer height="20" />
						<mx:Label text="{data.author}" />
						<mx:Label text="Available {data.date}" />
						<mx:Spacer height="100%" />
						<mx:HBox width="100%" horizontalAlign="right">
							<mx:Button label="Buy" fillColors="[0x99ff99,0x99ff99]">
								<mx:click>
								<![CDATA[
									var e:BuyBookEvent = new BuyBookEvent();
									e.bookData = data;
									dispatchEvent(e);
								]]>
								</mx:click>
							</mx:Button>
						</mx:HBox>
					</mx:VBox>
				</mx:HBox>
			</mx:Component>
		</mx:itemRenderer>
	</mx:TileList>

The itemRenderer looks like this when the application is run:

This itemRenderer is pretty close to the one used in the DataGrid, but the Buy button's click event doesn't use outerDocument to call a function. In this case the click event creates a custom event which bubbles up out of the itemRenderer, through the TileList, and is received by some higher component in the visual chain.

This is a very common problem: you have an itemRenderer which has some interactive control in it, usually a Button, LinkButton, etc. that is supposed to cause some action to take place when clicked. Perhaps it is to delete the row or in this case, buy the book.

It is unreasonable to expect the itemRenderer to do the work. Afterall, the itemRenderer's job is to make the list look good - period. Event bubbling allows the itemRenderer to pass off the work to something else. A custom event is useful here because the event is related to the data on the row - so why not include that data in the event; the receiver of the event won't have to go hunt it down.

Summary

Using inline itemRenderers is a great and quick way to give your lists a custom look. Consider inline itemRenderers as separate ActionScript classes - afterall, they are scoped as if they were. If you must refer to functions or properties in the containing file, use the outerDocument identifier to change the scope. If you need to communicate information as the result of an interaction with the itemRenderer, use a custom, bubbling, event.

And remember: don't try to get hold of itemRenderers - they are recycled for a purpose. Make them responsible only to the data given to them.

In the next article I'll discuss external itemRenderers.

Posted by pent at 08:26 AM | Comments (10)

February 29, 2008

Migrating from Flex 2 to Flex 3

Check this link before migrating your applications from Flex 2 to Flex 3. In my own experience the issues have been very minor and fixed within a few minutes. But your results will varying depending on what controls you've used and how large your application is.

http://learn.adobe.com/wiki/display/Flex/Backwards+Compatibility+Issues


Posted by pent at 12:05 PM