Archive for November, 2008

Adding ASDoc Comments to Flex MXML files

The Flex ASDoc command-line tool parses one or more ActionScript class definitions and MXML files to generate API language reference documentation for all public and protected methods and properties, and for certain metadata tags. The Gumbo release of Flex adds new features to the ASDoc command-line tool, including support for ASDoc comments in MXML files.

The ASDoc command-line tool is in the bin directory of your Flex Gumbo installation directory.

MXML Comments

The previous release of the ASDc command-line tool processed MXML files as input, but did not support ASDoc comments in the MXML file. In this release, you can now use the following syntax to specify an ASDoc comment in an MXML file:

<!— asdoc comment –>

The comment must contain three dashes following the opening <! characters, and end with two dashes before the closing > character, as the following example shows:

<?xml version="1.0"?>
<!-- asdoc\MyVBox.mxml -->
<!---
The class level comment for the component.
This tag supports all ASDoc tags,
and does not require a CDATA block.
-->
<mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml">
<!---
Comment for button
-->
<mx:Button id="myButton" label="This button has comment"/>
</mx:VBox>

In this example, the first comment is a standard XML comment that is ignored by ASDoc. The second comment precedes the root tag of the component and uses the three dashes to identify it as an ASDoc comment. An ASDoc comment on the root tag is equivalent to the ASDoc comment before an ActionScript class definition. Therefore, the comment appears at the top of the output ASDoc HTML file.

All MXML elements in the file correspond to public properties of the component. The comment before the Button control defines the ASDoc comment for the public property named myButton of type mx.controls.Button.

You can use any ASDoc tags in these comments, including the @see, @copy, @param, @return, and other ASDoc comments.

Specify the input MXML file to the compiler in the same way that you specify an ActionScript file. For example, you can use the -doc-sources option of the compiler to process this file:

flex_dir/bin>asdoc -doc-sources C:\myApp\myMXMLFiles\MyVBox.mxml -output framework-asdoc

The ASDoc command-line tool only processes elements of an MXML file that contain an id attribute. If the MXML element has an id attribute but no comment, the elements appears in the ASDoc output with a blank comment. An MXML element with no id attribute is ignored, even if it is preceded by an ASDoc comment, as the following example shows:

<?xml version="1.0"?>
<!-- asdoc\MyVBoxID.mxml -->
<!---
The class level comment for the component.
This tag supports all ASDoc tags,
and does not require a CDATA block.
@see mx.container.VBox
-->
<mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml">
<!---
Comment for first button appears in the output.
-->
<mx:Button id="myButton" label="This button has comment"/>
<mx:Button id="myButton2" label="This button has no comment"/>
<!---
Comment for button with no id is ignored by ASDoc.
-->
<mx:Button label="This button has no id"/>
</mx:VBox>

You can insert ASDoc comments for metadata tags in the <Script> and <Metadata> blocks in an MXML file. For metadata tags, the ASDoc comments use the same syntax as you us in an ActionScript file. The only requirement is that the ASDoc comments must be within a CDATA block, as the following example shows:

<?xml version="1.0"?>
<!-- asdoc\MyVBoxComplex.mxml -->
<!---
The class level comment for the component.
This tag supports all ASDoc tags,
and does not require a CDATA block.
-->
<mx:VBox xmlns:mx="http://www.adobe.com/2006/mxml">
<!---
Comment for language element - this comment will be ignored.
-->
<mx:Script>
<![CDATA[
import flash.events.Event;
/**
* For a method in an <mx:Script> block,
* same rules as in an AS file.
* @eventType myEvents.EnableChangeEvent
*/
private function handleCloseEventInternal(eventObj:Event):void {
dispatchEvent(eventObj);
}
]]>
</mx:Script>
<mx:Metadata>
<![CDATA[
/**
* Defines the default style of selected text.
*/
[Style(name="textSelectedColor",type="Number",format="Color",inherit="yes")]
/**
* The component dispatches the darken event
* when the darken property changes.
* @eventType flash.events.Event
*/
[Event(name="darken", type="flash.events.Event")]
/**
* Played when the component darkens.
*/
[Effect(name="darkenEffect", event="darken")]
]]>
</mx:Metadata>
</mx:VBox>

Comments before Definition, Library, and Private tags are ignored. Also comments inside a private block are ignored.

New option to the ASDoc command-line tool

By default, the ASDoc command-line tool halts processing and outputs a failure message when an ASDoc comment in an input file contains invalid HTML code. The tool writes error information to the validation_errors.log file.

This release of the ASDoc command-line tool adds the -lenient option that specifies to complete the compilation even when an HTML error occurs. The ASDoc comment that included the error is omitted from the output and the tool writes error information to the validation_errors.log file, but the remainder of the file or files is processed normally.

Flex 3.2: Loading sub-apps

The Flex 3.2 SDK has just been released. This release includes many bug fixes, but also one major new feature: improved support for loading sub-applications. Not only can your main app load and interact with sub-apps that are both inside and outside of its security sandbox, but you can also load sub-apps that were compiled with different versions of the Flex compiler (known as multi-versioning).

A sub-application is any application SWF file that is loaded into a main application SWF file. You load sub-apps if you have a portal web site or a form manager or dashboard that uses content from other sites. Sub-apps are like modules in many ways, except they can be loaded locally or cross-domain.

You might not have control over the the source code, or even the version of the compiler, that is being used to compile that sub-app. When you load the sub-app, you get to choose what level of trust your main app will have with it. This is a very important consideration, because if you don’t have complete control over the source of a sub-app, you should seriously consider loading that sub-app into a separate security sandbox, rather than loading it into the same security sandbox as the main application.

Of course, there are trade-offs. What the new functionality lets you do depends on the level of trust you have between the main application and the sub-application.
If you load a sub-app into the same sandbox as the main app, then you can have a greater level of data sharing and interaction between the two apps. In separate sandbxoes, the apps have less interoperability (but some is still possible).

To load sub-apps, you still use the SWFLoader control. For multi-versioning support, the class has a new property: loadForCompatibility. Set this property to true to indicate that the sub-application might be compiled with a different version of the compiler.

You can get all the links to info about the Flex 3.2 release here:
http://www.adobe.com/devnet/flex/articles/sdk32_fb302.html

The documentation for the loading sub-applications feature is here:
http://www.adobe.com/go/learn_flex_loading_applications_en

Check out the Experience Design team’s re-launched site

Our Experience Design (XD) team just relaunched Inspire, their external site, http://xd.adobe.com. The XD team contains a bunch of terrific designers and developers, and is responsible for most of the look n’ feel in the latest Adobe products.

Honestly, I don’t always agree with everything coming out of XD, but I am always amazed at their creativity, visual sensibility, and app development chops. You won’t regret taking time to poke around this site.