Lets begin by creating the skeleton for our XML file.

The <customactions> node can contain one or more <reference> 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:

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:

To link to other help topics or to external content within your reference help use the <a> or <link> tags with the href attribute. For example, let's say you want to add a ?See also? section with links to other complementary methods within your reference help (see the FSimpleClass example above).? This is done by adding the <a> or <link> with an href attribute that contains a protocol value of ?reference? followed by the ?URI? to the help topic, e.g. :

<a href=?reference:Simple/Methods/displayMessage?>displayMessage</a>

To make a link to external content use the appropriate protocol and URI like:

<a href=?http://www.cybersage.com?>CyberSage</a> OR

<link href=?file://c:/myhelp.htm?>Related Topics</link>

and this will launch the default browser and point it to the link specified.

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.

About CyberSage Software: