 |
|
|
| |
|
| 
|
The Macromedia 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
Macromedia Flash MX 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 Macromedia
Flash components and seamlessly integrate them
into the Macromedia 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 Macromedia Flash MX Help Files
To integrate your component help into Macromedia
Flash MX, you are required to create at least
one XML file that contains the help text and
code hints. Macromedia 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:
|
· |
Code Hint
File |
|
· |
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 Macromedia
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 Macromedia 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'll discuss 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 Macromedia
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 Macromedia Flash MX component help, not
on creating components. Let's imagine you have created a simple
Macromedia 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
<customactions> and contains several sub elements as
described below:
|
|
<actionspanel> |
is used to
group and define the folders and items that will be
placed into the Macromedia Flash Actions Toolbox (see
Figure 1). |
|
<colorsyntax> |
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). |
| <codehints> |
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. Let's begin by creating
the skeleton of the Code Hint XML file. |
| |
 |
| |
| Let's
create the <actionspanel> 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 <folder> tag
and items are defined using the <string>
tag. The following entry creates a folder for FSimpleClass. |
| |
 |
| |
| The
following is a description of each attribute used to define
the folder named Simple: |
| |
|
· |
VERSION |
indicates the intended version of the player this component
was written for. |
|
· |
id |
should have
a similar value as the name attribute. |
| · |
index |
indicates
that items within this folder should be displayed within
the index section of the Actions Toolbox (see figure
6). |
| · |
name |
display name
that will be visible within the Actions toolbox |
| · |
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 <string> tag. |
| |
 |
| |
| The
following is a description of each attribute used to define
the items within the Methods subfolder: |
| |
|
· |
OBJECT |
references the object to which a method or property
belongs. |
|
· |
TEXT |
refers to
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
|
displays
the name of the item. |
| · |
tiptext
|
refers to
the 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 <identifier> element is
used to define the syntax coloring for FSimpleClass and its
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 <codehints>
tag. Only objects are specified within this element.
The purpose of this section is to provide a way for Macromedia
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 |
references the name of the object to be used when the
pattern is matched. |
|
· |
pattern |
refers to
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 Macromedia Flash MX to display
both code hint styles (menu and tool-tip) and color identifiers
for FSimpleClass. |
| |
 |
| |
Step
3: Create the Reference Help File
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 <customactions>
and it contains one sub element <reference>. |
| |
|
· |
<reference> |
contains the help text for a method or property of an
object (see Figure 4). |
|
| |
| Let's
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: |
| |
|
· |
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, to make it
look like the rest of the help within Macromedia 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 will 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, as in
the example below: |
| |
<a
href=”reference:Simple/Methods/displayMessage”>displayMessage</a> |
| |
| To
make a link to external content, use the appropriate protocol
and URL, such as: |
| |
<a
href=”http://www.cybersage.com”>CyberSage</a> |
| |
| or |
| |
<link
href=”file://c:/myhelp.htm”>Related Topics</link> |
| |
| Either
example above will launch the default browser and display
the specified link. |
| |
Step
4: Install the help files
Macromedia 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 Macromedia 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 Settings\User\Application Data\Macromedia\Flash
MX\Configuration\ActionsPanel\CustomActions |
| |
Windows
98 and ME
C:\Windows\Application Data\Macromedia\Flash MX\Configuration\ActionsPanel\CustomActions |
| |
Windows
NT
C:\WinNT\Profiles\User\Application Data\Macromedia\Flash MX\Configuration\ActionsPanel\CustomActions
|
| |
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:
|
| |
Maintaining
your help files
Creating help to be integrated into Macromedia 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 the
authors |
| President/CEO,
Paul Gubbay has a fifteen-year background in the software
industry and specializes in conversion and delivery of legacy
data through the Internet. In various roles as lead architect,
developer and project manager he has been a key technical
decision maker in several Internet strategy, information
sharing and business conversion efforts for companies including
EDS, Alltel and OAN Services.
Paul has spent the last several years building the
vision and infrastructure of CyberSage Software. His understanding
of the issues that face today's customers and the development
tools that are available to solve them has played a key
role in the direction of the company. CyberSage focuses
on emerging technologies such as XML, Java and Flash to
deliver superior consulting services and leading edge product
offerings.
Jason Williams has been a software developer for over
thirteen years in all areas of software development, varying
from multi-tier commercial banking systems to neural networks
and compiler design. Mr. Williams is an expert in e-commerce
enabling technologies, software tool and engine design.
He has been working with XML since the first parser was
available. His skills and intimate knowledge of XML/XSLT
technologies earned him a seat on the customer advisory
board for RainingData (RDTA), providing technology and feature
set direction for the soon to be released native XML database.
Mr. Williams is an Inprise certified trainer and has
served as a member of the technical advisory board for Inprise
and Borland. He is a published writer in the ACM SIGCE proceedings
for compiler design and neural networks. Jason graduated
from San Jose State University with a BS in Computer Science
with special focus on computer graphics algorithms and animation
techniques.
|
| |
