Live Previews are SWF files that you can embed in your components so that they accurately show any customizing the developer has done. Live Preview makes your component a lot more useable in most cases; it gives feedback to the user giving them an idea of how changes in component parameters affect the component. It's also valuable in making sure everything is up to standard without publishing the movie. If you are making a component that you suspect will be widely used, you should consider a Live Preview.

Key Elements of a Live Preview

In the Live Preview file there is a special variable on _level0 named xch. This holds the values that the developer has entered in the Component Parameters panel. There is also a special event which is called, onUpdate(). This is called whenever xch has been updated with new properties from the component parameters. If you used custom UI’s in Flash 5 you will recognize xch. In Flash 5 you would have to have an empty movieclip named xch and the data would be put in it, in Flash 6 xch is an object that is automatically created for you.

Usually the Live Preview will be your actual component. Yep, it's that easy--you can just create a SWF with your component in it, add a few hooks for setting its properties, and surprise; you have an accurate Live Preview.

To start, you MUST put these two lines at the top of your Live Preview FLA file if you want the preview to be accurate.

Stage.align = "TL";
Stage.scaleMode = "noScale";

This will make sure the alignment and scaling are correct.

onLoad
This is a standard event fired by Flash when the movie loads (or MovieClip) this is perfect for you to use to set the defaults of your Live Preview. Usually you will just retrieve the current Stage.height and Stage.width dimensions here and size your component to that size.

function onLoad(){
   myComponent.setSize(Stage.width, Stage.height);
}

onUpdate
This event is called whenever xch has been updated with new properties. You can use this event to update the UI when the properties change. The push button’s component Live Preview most likely looks something like this:

function onUpdate(){
   var label = xch.label;

   pushPreview.setLabel(label);
}

pushPreview is the push button component.

onResize
This event is not provided by the Live Preview, but is needed. onResize() is an event used by Stage listeners. You will want to resize your component to fit the size of the stage when this event is fired. When the developer resizes your component in the IDE your Live Preview’s stage will change size to match. Below is what the push button’s onResize() probably looks like:

Stage.addListener(this);

function onResize(){
   pushPreview.setSize(Stage.width,Stage.height);
}

You can look at the LivePreview.fla for a complete example.

Creating the Live Preview

There is a very simple source file that you can look at that is a Live Preview. You can find it in the source zip under the filename LivePreview.fla This source file takes one of the standard components and recreates the Live Preview by just adding a few hooks.

To test this file you can create a new movie and drag the push button onto the stage.

1. In the library right-click on the push button component and select Component Definition.
   
2. You will see a field named Live Preview, Click on the Set button and find the LivePreview.swf.

You will notice it looks exactly the same, in a few lines code it was very easy to recreate the push button’s Live Preview. Even the most advanced components can be easy to add a preview too since the preview is simply the component itself with a couple hooks. The next section will walk you through a slightly more complicated example.

Exercise – Recreating the Message Box Component’s Live Preview

The Message Box component is available in the freely distributed Flash UI Component Set 2. The Message Box has seven component parameters that can be shown in the Live Preview.

• Title – The title of the Message Box
• Message – The center text in the Message Box
• Icon – The Icon on the Message Box
• Buttons - An array of strings that represent each button in the Message Box
• Button Width – The width of each button set in the buttons array
• Title Bar Height – The height of the title bar
• Visible – If it is visible at start or not

The only preview item that will not hook into the component is the Visible parameter. You wouldn’t want to hide the component completely so you can just do something to indicate that it will be invisible at runtime. The original Live Preview for the Message Box component changed the component’s _alpha property to make it somewhat transparent. Below are the steps to recreating the Live Preview for this component, if you have trouble with any of the steps you can open the source file MessageBox_preview.fla for help.

1. Open Flash MX and make a new movie called MessageBox_preview.fla
2. Drag the Message Box component onto the stage at coordinates 0,0.
3. Set the stage size to 320x200, this makes it the same size as the default size of the component.
4. Give the component an instance name of preview_mb.
5. Name the layer that the component is on “Preview” and create a new layer “Actions”.
6. On the actions layer you will want to start with your Stage initializations. Put the code:
   
   Stage.align = "TL";
   Stage.scaleMode = "noScale";
   Stage.addListener(this);
   
   function onResize(){
      preview_mb.setSize(Stage.width,Stage.height);
   }
   
   The first two lines set the alignment and scale mode so that your Live Preview does not scale or change alignment from the top-left. After those lines you add a listener to the Stage object. When the Stage resizes it fires the event of onResize() you catch this and change the size of your component to reflect it. The size of the stage in a Live Preview happens when the component is resized in the authoring environment.
   
7. And last but most important its time create an onUpdate function to hook into preview_mb.
   
   function onUpdate(){
      preview_mb.setTitle(xch.title);
      preview_mb.setMessage(xch.message); preview_mb.setIcon(xch.icon);    preview_mb.setButtons(xch.buttons); preview_mb.setButtonWidth(xch.buttonWidth);    preview_mb.setTitlebarHeight(xch.titleBarHeight);
   preview_mb._alpha = (xch._visible) ? 100 : 20;
   }

As you can see above all you have to do is to hook into the component for the preview, except for the last line. Instead of making the component invisible you give an indicator that it will be by setting its _alpha property to 20%.

When creating your own components and Live Previews you can follow these same steps. The Live Preview is a regular SWF that runs in the IDE. That is why you can use your component as the Live Preview itself. It’s that simple! If you have any issues be sure to look through the example, if you are still having trouble feel free to email me at gburch@squarelabs.com.