The Flash MX component architecture introduces a powerful and flexible way to leverage existing code, both your own and that written by others. The opportunity to develop Flash components to be reused by others is limited only by your imagination. Learning how to use these components, however, should not be left up to your user's imagination. As more components become available it is important that both developers and designers be able to easily make use of them.

This article describes the process required to create help files for custom built Flash components and seamlessly integrate them into the Flash MX environment. In the next sections, you will learn how Flash help files are organized and how to create them for your custom-built components.

The Flash MX Help Files

To integrate your component help into Flash MX, you are required to create at least one XML file that contains the help text and code hints. Flash MX also allows you to place the help definitions into two separate XML files, one for code hints and one for reference help. To keep things simple in this tutorial we will use two files and refer to them as:


a. Code Hint File


b. Reference Help File

Code Hint File

The Code Hint XML file describes the hierarchy of folders and their associated items within the Actions toolbox on the left side of the code pane. Folders may contain one or more subfolders and/or items as shown in Figure 1.





This XML file also contains information that allows Flash to support syntax color highlighting and the enhanced coding feature called code hints.

Reference Help File

The Reference Help file consists of the XML needed to describe the hierarchy of folders and associated items in the Reference Help displayed by Flash MX. Reference Help contains the text that your users will read to gain insight into how to use your components.

Creating Help For a Simple Component

In the following example, we will show you how to create reference help and code hints for a simple object called FSimpleClass. When we have finished, you will be able to use code hints and reference help for FSimpleClass directly within Flash MX.

Step 1: The Simple Component

For the purposes of this tutorial, we do not actually need to create the code for this component. This tutorial is about creating Flash MX component help, not on creating components.

Let's imagine you have created a simple Flash component, FSimpleClass, that contains 2 methods as follows:

Step 2: Create the Code Hint File

The root node of the Code Hint XML file is called and contains several sub elements as described below:

is used to group and define the folders and items that will be placed into the Flash Actions Toolbox (see Figure 1).

is used to define which identifiers (i.e. objects and methods) will display using the color specified for identifiers within the ActionScript editor preferences window (see figure 5).

is used to identify a specific object type within the ActionScript editor and allows the editor to display the menu-style code hint for the object.



Each of these elements can contain sub elements to describe supporting information. We will review each as we create the Code Hint XML file for FSimpleClass. Lets begin by creating the skeleton of the Code Hint XML file.



Let's create the section first. The Actions toolbox consists of folders and/or items, each folder or item may contain subfolders and so on. Folders are defined using the tag and items are defined using the tag. The following entry creates a folder for FSimpleClass.



The following is a description of each attribute used to define the folder named Simple:


a. VERSION � indicates the intended version of the player this component was written for.

b. id � Unknown as of this writing. The standard seems to be to use the same value as found in the name attribute.

c. index � indicates that items within this folder should be displayed within the index section of the Actions Toolbox (see figure 6).

d. name � display name that will be visible within the Actions toolbox

e. tiptext � text that is displayed when the cursor is placed over the item in the Actions toolbox (see Figure 1).




Next, we will group the methods for FSimpleClass by creating a subfolder.



Finally we add the entries for each of the methods of FSimpleClass using the tag.




The following is a description of each attribute used to define the items within the Methods subfolder:

• OBJECT â�� Specifies the object to which a method or property belongs
• TEXT â�� the code to be inserted at the current cursor position within the code pane if the user selects this item from the menu-style code hint.
  
• TYPE â�� defines the type of item (function, procedure, property, event, etc)
  
• VERSION - indicates the intended version of the player this component was written for.
  
• name â�� display name of the item.
  
• tiptext â�� text that is displayed when the cursor is placed over the item in the Actions toolbox (see Figure 1).
  

Next, we need to create the <colorsyntax> section. The element is used to define the syntax coloring for FSimpleClass and it�s methods.



The following is a description of the attributes used:

• text â�� defines the text that will be displayed using the color specified for identifiers within the ActionScript Editor preferences window (see Figure 5).

The final section of the Code Hint XML file contains the tag. Only objects are specified within this element. The purpose of this section is to provide a way for Flash MX to determine what menu-style code hint to display when a user is writing code in the editor. It looks for a pattern in the text being edited and attempts to match that pattern with one of the pattern
attributes within the codehints� typeinfo tag. When a match is found the menu-style code hint is displayed. We would like the menu-style code hint to appear any time the user types in �xxxx_simple�. Here is how we would enter FSimpleClass.



The following is a description of the attributes used:

• OBJECT â�� name of the object to be used when the pattern is matched.
• pattern â�� the text pattern to match against within the code pane.
  

Here is the completed Code Hint XML file for FSimpleClass. This file can now be utilized by Flash MX to display both code hint styles (menu and tool-tip) and color identifiers for FSimpleClass.

Step 3: Create the Reference Help

The Reference Help XML file has a simpler format than the Code Hint XML file but is usually much larger due to the amount of information that it contains. The root node of the Reference Help XML file is called and it contains one sub element <reference>.

* contains the help text for a method or property of an object (see Figure 4).

Lets begin by creating the skeleton for our XML file.



The node can contain one or more nodes. There will be one reference node for each method of an object that you are documenting.

The following example shows the completed Reference Help XML file for FSimpleClass.



The following attributes are used to define a reference help entry:

path � defines the path within the Reference Help to the documentation associated with this item.


As you may note from the previous example there are some predefined styles that can be used to format the help text, so that it will look like the rest of the help within Flash MX. These styles are titleStyle, subTitle and codeStyle. The final rendering of the reference help supports a subset of HTML that allows us to get the job done nicely. It does preserve white space so you can get indentations within source code examples to format correctly. The following are the tags and escape sequences that we know currently work:

Step 4: Install the Help Files

Flash MX needs to access your XML files during startup in order to display the Code Hint and Reference Help within the environment. You must place both of the completed XML files (or just one if they are combined) into the appropriate location for Flash MX to find during startup. The location of these files depends on your operating system. It is stored in a user configuration folder where your operating system stores application data. Here are some examples:

Windows 2000 and XP

C:Documents and SettingsUserApplication DataMacromediaFlash MXConfigurationActionsPanelCustomActions

Windows 98 and ME

C:WindowsApplication DataMacromediaFlash MXConfigurationActionsPanelCustomActions

Windows NT

C:WinNTProfilesUserApplication DataMacromediaFlash MXConfigurationActionsPanelCustomActions

MAC OS X

Hard Drive:Users:Library:Application Support:Macromedia:FlashMX:Configuration:ActionsPanel:CustomActions:

Mac OS 9.x (multi-user)

Hard Drive:Users:User:Documents:Macromedia :FlashMX:Configuration:ActionsPanel:CustomActions:

Simply copy your XML files to the directory for your operating system and restart Flash MX. In our example the newly created help will appear in the Actions toolbox under a new folder called Simple and when you click on the Reference Help icon you will see this same folder displayed.

Maintaining Your Help Files

Creating help to be integrated into Flash MX is a straightforward process and will gain you high marks from developers that use your components. The downside is that it is a very time consuming process to create and maintain the needed XML files by hand.

Keeping the reference help and code hint files up to date can be a daunting task. If you are serious about developing and distributing MX components we recommend that you take a look at FlashDoc. With a few simple comment tags placed in your ActionScript source code, FlashDoc will generate the necessary XML files for you. At the time of this writing, FlashDoc is available as a free web service from www.cybersage.com.