FlashLit.

ActionScript 3.0 Coding Standards

As part of the open source release of the Adobe Flex 3 SDK, Adobe has also posted the ActionScript 3.0 Coding Conventions that the engineers used while developing the framework.

It's been hard to find a good set of AS3 coding standards in the past but this fits the bill. It's pretty thorough even though there are a few sections still marked TBD. It covers naming standards, language usage, file organization, and code formatting.

The standards all seem pretty reasonable too, unlike some other standards documents I've seen elsewhere. I'd say it's about a 95% match with my personal AS3 coding preferences.

Even if you don't agree with all the standards, this is a great starting point for any project team that's embarking on a big Flex, Flash, or ActionScript project. You can just use the Adobe standards as a baseline and tweak as necessary.

Getting ASDoc to recognize Adobe AIR classes

Now that AIR 1.0 is official, some people are having trouble getting the ASDoc utility that ships with Flex Builder 3 to recognize the new AIR classes. Here's a quick way to do it.

Use the -library-path option on the ASDoc command line to include the folder that contains the airframework.swc and airglobal.swc files. For example:

asdoc -source-path . -doc-classes myComponents.MyFileManager  -library-path+=..\frameworks\libs\air

Notice the += after in the -library-path value. That appends the location of the AIR SWC files to the default list, which includes the Flex Framework SWCs.

Of course you will also need to change the path to the \frameworks\libs\air folder relative to the location from which the asdoc utility is running.

The simplest Apollo web browser

It's official. Apollo Alpha 1 has launched!

Before you jump too far into Apollo coding, have a scan through the online Apollo docs and avail yourself of the freely downloadable PDF of the Apollo for Adobe Flex Developers Pocket Guide.

One of the coolest Apollo features is the new HTML rendering control and its Flex framework sibling, the HTML component. This post would feel naked without some kind of code snippet, so here's a super-simple but functional web browser in just three lines of code (or a few more if you count line breaks and closing tags :) ).

<?xml version="1.0" encoding="utf-8"?>
<mx:ApolloApplication xmlns:mx="http://www.adobe.com/2006/mxml" 
   layout="vertical">

   <mx:TextInput id="urlTxt" 
      width="100%" 
      enter="html.location=urlTxt.text;"
      text="http://www.adobe.com/go/apollo" />

   <mx:HTML id="html" 
      width="100%" height="100%"
      location="http://www.adobe.com/go/apollo" />

</mx:ApolloApplication>

That example creates a single text field for entering a URL and an HTML component for loading the HTML and JavaScript content. When you press the Enter key in the text field, it sets the location property of the HTML control to the value of the text field, and then web page loads and displays.

You'll notice that most of the buttons and controls you expect to see in a real web browser -- Back and Next buttons, and so on -- don't come pre-packaged with the HTML component. We'll deal with that issue in the next post.

Apollo Camp in progress

We're midway through the Apollo Camp event here at the Adobe office in San Francisco. The level of customer interest is high. It's a very high-energy event, in spite of the late hour on a (mostly) work day.

It's great to see real-time blog posts popping up during the event. Ryan Stewart, Renaun Erickson, Josh Tynjala, Lee Brimelow, Mims Wright and others have already published posted great descriptions of the lead up to the event, the early talks (including Kevin Lynch's keynote), and of course the schwag. (It's great to see the the Apollo for Adobe Flex Developers Pocket Guide was part of the goodie bag. That way at least a few people will read it. :) )

Use ASDoc to drive new processes

The ASDoc tool that comes with Flex Builder and the Flex 2 SDK generates great looking docs from your ActionScript and MXML code, but it can drive other types of documents, reports, and processes too. All you need are these undocumented command-line parameters...and of course mega programming skills.

Here are some undocumented command-line parameters you can use with the ASDoc tool to make it even more useful.

-keep-xml

ASDoc initially generates an XML file that contains all the metadata and documentation comments from your code. Then it applies XSL stylesheets to that XML to generate all that attractively formatted HTML output. Then it deletes the interim XML file.

If you use the -keep-xml option though it will save the interim XML file, which is named toplevel_classes.xml. The data in this file can be amazingly useful. We have used it many ways at Adobe, including:

• Converting to XMI files for input to UML modeling tools
• Generating code colorizing and hinting files for Flash 9
• Generating test scripts
• Experimenting with Flex-based documentation browsers

Even if your source code has no comments all the basic structural information about your code, covering things like packages, classes, methods, properties, and events, is output to the toplevel_classes.xml file as nice, structured XML.

-skip-xsl

The -skip-xsl parameter stops the ASDoc process before it generates the HTML output. It goes hand in hand with the -keep-xml parameter. When you use them in combination ASDoc will generate the toplevel_classes.xml file and then stop. This parameter isn't necessary, but it speeds up the build process if you don't care about generating the HTML.

-show-actionscript-warnings=false

If your source code generates a lot of warnings, you can use this parameter to stop them from cluttering the console.

The parameters above were added to ASDoc too late to get into the official documentation, but I do recommend you check out that documentation to learn how to run ASDoc and write good doc comments.

If you end up using the ASDoc XML to develop something new and interesting, please let me know!