Flex comes with a full spectrum of components, but once in a while you get hit with a request to do something that is difficult to shoehorn into what already exists, but seems even more difficult to do as a custom component. For instance, one of my clients recently asked me to have something that is essentially a master/detail view, where the master view looks like a DataGrid and the detail view also looks like a datagrid "flyout" to the right, vertically centered on the item that was clicked with a "triangle" pointing from the master to the detail.

I showed him a prototype using an AdvancedDataGrid, but he had a very clear vision of his requirements, and it didn't look like an AdvancedDataGrid. This left me with a thorny problem. Yes, I could create a custom component to try to do all this, but a DataGrid is a complicated animal. I couldn't imagine trying to provide enough custom properties to set up and lay out two of them–not because it was beyond my capabilities, but because when I needed to consume it I didn't want to be sitting there with my documentation trying to feed all that stuff in. This is especially true since DataGrids are pretty simple to set up in MXML. Why would I duplicate what Adobe has already done?

Enter Template Components

First, what is a Template component? A Template component is a component that provides certain base functionality, but is designed to also have components added into it either in MXML or ActionScript. A perfect example of this is DataGrid. If you just give a DataGrid a dataProvider, it does a pretty good job at displaying it, but if you add DataGridColumns to it, it does an even better job.

At this point, I have a guilty confession to make. About 18 months ago, I made my first try at template components and failed miserably. I knew enough about the Flex Component LifeCycle to suspect that the template component example provided in the docs should probably override createChildren() rather than using a handler on the initialize event (which happens between createChildren and commitProperties), but I found that when I did this that I couldn't get the children I added through MXML to show up on the stage. So, I mentally marked template components as "something to figure out when I have to."

So, of course, this situation seemed to be a case where creating a template component would solve a lot of problems. It was, and it made several things I hadn't thought ahead to easier as well.

Advantages of Template Components

1. Simplifies the addition of child components, especially in MXML (this one is obvious)
2. Child components have access to the parent scope. For example, I used my Datagrid_withStyle component for this implementation. I was able to specify not only the dataProvider and columns in MXML, but I was also easily able to attach a styleFunction to both DataGrids without doing anything special. You could also take advantage of this to add effects to the child components as well.
3. If you're extending a container, you can add other objects into your custom component with no special effort. This can be a bit unsettling, since it might break something in your component, but it allows you to add objects you don't need to control in code into your custom container, just as you would for any container. If you look at the screen capture of my custom component, the Date Completed/Start and Target Date/End graphics are just standard Flex components in HBoxes, which are not managed in any way by the custom logic of my component (which extends Canvas).

Things to remember when making a Template Component

1. If you're extending a Container and overriding createChildren(), remember to call super.createChildren(). When you're extending UIComponent, this matters less, but Containers work their magic through having a bunch of children you're encouraged not to think about. This is why my first attempt at a template component failed.
2. If you have any required components, be sure to provide defaults so that the component works even if the developer using your component doesn't specify those in AS or MXML.
3. Unless you're 100% certain that your component will always be used from MXML, be sure to provide an alternate path for your "subcomponents" to be initialized through their setters + the invalidation cycle. This is to account for the possibility that someone adding your component in ActionScript might call addChild on your component before setting those properties, which would then have no way to be refreshed.
4. When using a Template Component from MXML, remember that its properties will be prefixed by the same namespace as the main component, even if the value of the propert is a Flex Component or a component in some other namespace.

What about you? Have you created a template component? If so, please share your thoughts on what you learned.

Read more from Amy Blankenship.