FlashLit.

One ActionScript Language Reference to rule them all

The Adobe Platform Docs team has released a beta version of the new combined version of the ActionScript Language Reference called the Adobe ActionScript 3.0 Reference for the Flash Platform.

This reference documents the ActionScript packages and classes from Flash CS4, Flex 4 (Gumbo), Flash Player 10, AIR 1.5, ColdFusion 9, and LiveCycle Data Services 3. So if you use more than one of these products you no longer have to jump around from reference to reference. You can find it all in one place.

There is also some nifty filtering logic in place so you can hide content from products or runtimes you're not interested in. You can even step down to previous product versions.

This is still in beta, and there is a feedback link on the site, so please have a look and let the team know what you think.

Here's the official announcement from the Platform Docs blog too.

Use a Flex List control to navigate to URLs

This example shows how to display a list of links in a Flex List control and let the user click on the list items navigate to the links.

A friend of mine recently built a photo gallery application. She wanted to load an external list of URLs representing photo album pages, so she could change the URLs in the future without rebuilding the app. The following technique worked pretty well for her project.

The following code declares a set of links in XML, binds them to a Flex List control, and then opens up each linked page in a new browser window when the user clicks an item in the list.

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" 
    layout="vertical" viewSourceURL="srcview/index.html">
    
    <mx:Style>
    .linkList
    {
        textDecoration: underline;
        color: #ddeef8; 
        rollOverColor: #99aabb;
        textRollOverColor: #eeeeff;
        selectionColor: #8899aa;
        textSelectedColor: #ffffff;
        textAlign: center;
        fontSize: 12;
        backgroundAlpha: 0;
    }
    </mx:Style>
    
    <mx:Script>
    <![CDATA[
          import mx.events.ListEvent;
          
          [Bindable]
          private var itemXml:XMLList = 
          <>
              <item label="Adobe.com" url="http://www.adobe.com" />
              <item label="FlashLit.com" url="http://www.flashlit.com" />
              <item label="FlexExamples.com" url="http://blog.flexexamples.com" />
          </>;
                      
          private function onItemClick(evt:ListEvent):void
          {
              var item:Object = (evt.target as List).selectedItem;
              if (item.@url)
              {
                  navigateToURL(new URLRequest(item.@url), '_blank');
              }
          }
    ]]>
    </mx:Script>
    
    <mx:List id="urlList" 
        labelField="@label"
        itemClick="onItemClick(event)" 
        width="150" 
        height="78"
        dataProvider="{itemXml}" 
        styleName="linkList"/>

</mx:Application>

The interesting bits:

• The links are declared in an XMLList variable. You can enhance this example pretty easily to grab the XML from an external file and use that to populate the list.
• The List control binds directly to the itemXml variable. If you want the List display will change automatically if the XML data changes, put the data into a XMLListCollection variable instead and bind to that.
• The List's itemClick event triggers the onItemClick() method. Note that even though it's listening for "itemClick" the handler method receives a ListEvent object, not an ItemClickEvent object.
• The onItemClick() method grabs the clicked item's url property using the E4X @ operator. Then it invokes the navigateToURL() method to open up that URL in a new browser window.
• The resulting control could be used in an HTML frameset to switch the content in another frame. Just change the value '_blank' in the navigateToURL() method to the name of the appropriate frame.

Here's the little control in action.

ASDoc now works with Flex MXML files

The new Flex 4 SDK is coming along quite nicely over at opensource.adobe.com. All you documentation geeks (there are some of you out there, right?) will be interested in the new ASDoc in MXML feature.

In the past the ASDoc engine could read comments from ActionScript source files, but not from MXML files. That left some big holes in the docs for Flex-based applications.

The new ASDoc engine reads MXML comments and treats them just like ActionScript comment blocks.

Here's an example of how to comment your MXML files:

<?xml version="1.0"?>
<!--- 
   This is the class level comment for the component. 
   This comment supports all ASDoc tags.

   @see mx.container.VBox
-->
<mx:VBox>

 <mx:Script>
  <![CDATA[
  import flash.events.Event;

  /** 
   * For methods, properties, and metadata tags in a Script block,
   * the same commenting rules apply as in an AS file.
   *
   * @eventType com.mydomain.events.EnableChangeEvent
   */
  private function handleChangeEvent(eventObj:Event):void 
  {
   dispatchEvent(eventObj);
  } 
  ]]>
 </mx:Script>

 <!--- 
   This comment describes the following button.
 --> 
 <mx:Button id="awesomeButton" label="Awesome"/>

</mx:VBox>

Note that the XML comment block must start with 3 dashes, not 2 dashes for it to be recognized by ASDoc. For example, this comment block will be processed:

<!--- ASDoc-friendly comment. -->

But this comment block will be ignored:

<!-- Traditional XML comment with 2 dashes, ignored by ASDoc. -->

Have a look at the detailed ASDoc in MXML specification to see more examples.

The good news is that you don't have to wait for the official Flex 4 release to use the new version of ASDoc. It's already available for testing (please let us know if you find any bugs!). Just download a recent nightly build of the Adobe Flex 4 SDK from the Gumbo downloads page. You will find the latest asdoc executable in the bin/ folder.

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.