|
|
Step 4: Creating Reference Panel Documentation
Writing documentation may seem like a boring chore to some people but I actually enjoy it. In fact, writing good documentation is a rare art. As a new feature in Flash MX, we can now install our own documentation in the Reference Panel so that it can be accessed from within the Flash authoring environment. Doing this, as you're about to see, is not hard at all. If you have XML phobia, however, you may want to count slowly up to ten and take a large breath before continuing!
- Fire up your favorite text editor and start a new document. (Or open up the finished version, very_simple_docs.xml, to follow along.) Here's the first batch of XML:
<customactions>
<actionspanel>
<folder version ="6" name="Very Simple Button"
id="VerySimpleButton" index="true"
tiptext = "Very Simple Button">
<folder version ="6" id="Parameters"
name="Parameters"
tiptext = "Very Simple Button Parameters">
<string name = "textFont"
object ="VerySimpleButton"
version = "6" text = ""
tiptext = "" />
<string name = "textSize"
object ="VerySimpleButton"
version = "6" text = ""
tiptext = "" />
<string name = "textLabel"
object ="VerySimpleButton"
version = "6" text = ""
tiptext = "" />
<string name = "changeHandler"
object ="VerySimpleButton"
version = "6" text = ""
tiptext = "" />
</folder>
<folder version ="6" id="Methods"
name="Methods"
tiptext = "Very Simple Button Methods">
<string name = "getLabel"
object ="VerySimpleButton"
text = ".getLabel ()"
version = "6"
tiptext = "Returns the label of the
Very Simple Button."/>
<string name = "setLabel"
object ="VerySimpleButton"
text = ".setLabel (% label %)"
version = "6"
tiptext = "Updates the label of the
Very Simple Button with the passed label."/>
</folder>
</folder>
</actionspanel>
- We're not done yet but this is a good point to stop and explain what the above markup does. The XML we've written so far defines the structure of the documentation as it will appear in the Reference Panel. We have defined a root folder for our component called Very Simple Button and two sub-folders, called Parameters and Methods. The
<string> tags define the actual documentation entries that will appear within the folders. Since their attributes are pretty much self-explanatory, I'm going to move along so we can actually write the documentation entries for our component's parameters (properties) and methods. Thus we add the following XML to the listing above:
<!-- Reference Help -->
<reference path = "VerySimpleButton">
<p class = "titleStyle">Very Simple Button</p>
<p class = "subTitle">About</p>
<p>Using the Very Simple Button component, you can create very simple buttons! You can customize the button's label, including the font and fontsize. </p>
<p class = "subTitle">Credits</p>
<p>Designed and developed by Aral Balkan (<a href="mailto:aral@onRelease.org">aral@onRelease.org</a>)</p>
<p class = "subTitle">Copyright</p>
<p>"Very Simple Button", "Very Simple Button Component" and the Tornado logo are trademarks of Aral Balkan and Bits And Pixels, Ltd. The Very Simple Button Component is Copyright © 2002, Aral Balkan. Copyright © 2002, Bits And Pixels, Ltd. All Rights Reserved. This version of the component is only for distribution with Flash MX Most Wanted.</reference>
<!-- getLabel() -->
<reference path = "VerySimpleButton/Methods/getLabel">
<p class = "titleStyle">getLabel</p>
<p class = "subTitle">Usage</p>
<p class = "codeStyle"><I>myVerySimpleButton_vsb.getLabel()</I></p>
<p class = "subTitle">Parameters</p>
<p>none</p>
<p class = "subTitle">Returns</p>
<p>(string) The current label of the Very Simple Button instance.</p>
<p class = "subTitle">Description</p>
<p>Returns the current label of the Very Simple Button instance.</p>
<p class = "subTitle">Example</p>
<p>The following code demonstrates the use of the getLabel() method, assuming that you have an instance of the Very Simple Button on Stage with an instance name of myButton_vsb.</p>
<p class = "codeStyle">
// get the label of the button<br />
var theLabel = myButton_vsb.getLabel();<br />
trace ("The label of the button is: " + theLabel);<br />
</p>
<p class = "subTitle">See Also</p>
<span class = "codeStyle"><a href="reference:VerySimpleButton/Methods/setLabel">setLabel method</a></span><br />
</reference>
<!-- setLabel() -->
<reference path = "VerySimpleButton/Methods/setLabel">
<p class = "titleStyle">setLabel</p>
<p class = "subTitle">Usage</p>
<p class = "codeStyle"><I>myVerySimpleButton_vsb.setLabel( label )</I></p>
<p class = "subTitle">Parameters</p>
<p><I>label </I>(string) The label to set for the button</p>
<p class = "subTitle">Returns</p>
<p>none</p>
<p class = "subTitle">Description</p>
<p>Sets the label of a Very Simple Button instance.</p>
<p class = "subTitle">Example</p>
<p>The following code demonstrates the use of the setLabel() method, assuming that you have an instance of the Very Simple Button on Stage with an instance name of myButton_vsb.</p>
<p class = "codeStyle">
// set the label of the button<br />
myButton_vsb.setLabel("An interesting label, indeed!");<br />
<p class = "subTitle">See Also</p>
<span class = "codeStyle"><a href="reference:VerySimpleButton/Methods/getLabel">getLabel method</a><br />
</reference>
- Here you can see that we've actually started to enter the documentation entries. Each documentation entry is written within a
<reference> tag. Within this tag, you can use a subset of HTML, as well as some built in CSS classes (e.g. titleStyle, subTitle, codeStyle). You link a reference entry to the correct <string> tag within a <folder> by specifying an absolute path to it in the form VerySimpleButton/Methods/setLabel (that is why the IDs of your folders and string elements are very important.) You also use these paths to reference documentation entries from with other entries. For this, you create a link in the form reference:VerySimpleButton/Methods/setLabel.
In the examples above, I've followed the Macromedia standard for Reference Panel documentation. You are, of course, free to format your documentation as you please (however keeping with platform conventions is considered a best practices method.) The help for the component's parameters (properties) is very similar to that for its methods:
<!-- PARAMETERS -->
<!-- textFont -->
<reference path = "VerySimpleButton/Parameters/textFont">
<p class = "titleStyle">textFont</p>
<p class = "subTitle">Usage</p>
<p class = "codeStyle">
<I>initObj.textFont = string</I></p>
<p class = "subTitle">Description</p>
<p>Sets the font to use for the button's label.</p>
<p class = "subTitle">Example</p>
<p class = "codeStyle">
initObj.textFont = "Impact";</p>
</reference>
<!-- textSize -->
<reference path = "VerySimpleButton/Parameters/textSize">
<p class = "titleStyle">textSize</p>
<p class = "subTitle">Usage</p>
<p class = "codeStyle">
<I>initObj.textSize = number</I></p>
<p class = "subTitle">Description</p>
<p>Sets the font size to use for the button's label.</p>
<p class = "subTitle">Example</p>
<p class = "codeStyle">
initObj.textSize = 24;</p>
</reference>
<!-- textLabel -->
<reference path = "VerySimpleButton/Parameters/textLabel">
<p class = "titleStyle">textLabel</p>
<p class = "subTitle">Usage</p>
<p class = "codeStyle">
<I>initObj.textLabel = string</I></p>
<p class = "subTitle">Description</p>
<p>Sets the button's label.</p>
<p class = "subTitle">Example</p>
<p class = "codeStyle">
initObj.textLabel = "Another interesting label!";</p>
</reference>
<!-- changeHandler -->
<reference path = "VerySimpleButton/Parameters/changeHandler">
<p class = "titleStyle">changeHandler</p>
<p class = "subTitle">Usage</p>
<p class = "codeStyle">
<I>initObj.changeHandler = string</I></p>
<p class = "subTitle">Description</p>
<p>Sets the button's changeHandler.</p>
<p class = "subTitle">Example</p>
<p class = "codeStyle">
initObj.changeHandler = "myChangeHandler";</p>
</reference>
- That's it, we're done with the Reference Panel documentation. You've probably noticed, however, that we haven't closed the
<customactions> tag yet. That's because we're going to add a bit more XML to our document in the next two steps to implement Code Hints and Syntax Highlighting.
|
|
Download PDF file of this tutorial 
go to previous step