Author Archive: Stephen Gilson

New Doc on Flex Gumbo Containers and Item Renderers Available

Here is new documentation on Flex Gumbo containers, including item renderers.

Download the PDF: Spark Containers

 

Stephen Gilson
Flex Doc Team

New Doc on Flex Gumbo States Available

Here is new documentation on Flex Gumbo view states, including the new syntax for defining states in Gumbo.

Download the PDF: Using States

New Doc on Flex Gumbo Efffects

Here is new documentation on Flex Gumbo effects. You can use these effects with all Flex components.

Download the PDF:Using Spark Effects

Updated Doc on using the Flex ASDoc Tool

Here is the updated documentation on the Flex Gumbo ASDoc tool. This documentation includes information on using ASDoc to process MXML files, and has many new examples showing how to run the tool.

Download the PDF: Using ASDoc

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 Gumbo API Reference available

The ASDoc API reference for Flex Gumbo, the next version of Adobe Flex, is now available at http://livedocs.adobe.com/flex/gumbo/langref/. We will be updating this reference approximately every other week.

Please use the Adobe Forums to comment on the API reference.

For general information about Gumbo, see the Gumbo page.οΎ 

Building Adobe LiveCycle Data Services ES Beta 2 Applications

Adobe LiveCycle Data Services ES Beta 2 applications consist of two parts: client-side code and server-side code. Client-side code is a Flex application written in MXML and ActionScript and deployed as a SWF file. Server-side code is written in Java and deployed as Java class files or Java Archive (JAR) files. You can develop Adobe LiveCycle Data Services ES applications in Flex Builder, or in your own IDE. This article describes how to set up your development environment to compile, debug, and deploy LiveCycle Data Services ES applications.

Download the PDF: Building and Deploying LiveCycle Data Services ES Applications

Adding Java Development Tools to Flex Builder Standalone

Many Flex, Adobe AIR, Adobe BlazeDS, and Adobe LiveCycle ES developers choose to use the Eclipse plug-in configuration of Flex Builder so that they can develop Java code in the same IDE that they use to develop the MXML and ActionScript code. While the standalone version of Flex Builder does not contain tools to edit Java code by default, you can install them as Eclipse plugins. That lets you use the standalone version of Flex Builder to edit Java code.

To install the Java development tools in the standalone version of Flex Builder:

1. Use the Help > Software Updates > Find and Install menu command to open the Install/Update dialog box

2. Select Search for new features to install.

3. Click Next.

4. In the results, choose Europa Discovery Site.

5. Click Finish.

6. Select the Java Development package to install.

7. Click Next.

8. Accept the license.

9. Click Finish.

Note: You might be prompted to install additional plugins required by the Java Development package.

To change perspective:

1. Use the Window > Perspective > Other to access all perspectives.

You can also click the Open Perspective button in the upper-right corner of the workbench window, then select a perspective from the pop-up menu.

2. Select Java from the list of perspectives.

 

Stephen Gilson
Flex Doc Team

Creating ASDocs for Custom Adobe AIR Components

The Flex ASDoc tool parses one or more ActionScript class definitions to generate API reference documentation for all public and protected methods and properties, and for all [Bindable], [DefaultProperty], [Event], [Style], and [Effect] metadata tags. By default, the ASDoc tool links in all of the Flex SWC files required to compile custom Flex components. However, to use ASDoc to generate documentation for custom Adobe AIR components, you must link in the necessary AIR SWC files.

For example, you create a custom component named MyAirComboBox that extends the AIR mx.controls.FileSystemComboBox component. The directory location of your custom component file is:

C:\myApplication\myComponents\MyAirComboBox.as

Use the following ASDoc command to generate API reference documentation for MyAirComboBox:

..\bin\asdoc -doc-sources C:\myApplication\myComponents\MyAirComboBox.as -library-path+=..\frameworks\libs\air -main-title "My AIR API Documentation" -window-title "My AIR API Documentation" -output air-asdoc

This command assumes the following:

  • You run the command from the directory C:\Program Files\Adobe\Flex Builder 3\sdks\3.0.0\asdoc in your Flex Builder installation directory structure. If you are using the Flex SDK, or have installed Flex Builder on another operating system, modify the paths in this command as necessary.
  • The AIR SWC files are installed in the directory C:\Program Files\Adobe\Flex Builder 3\sdks\3.0.0\frameworks\libs\air. This is the default directory location for a Flex Builder installation.This command uses the library-path option to the ASDoc tool to specify the directory location of the AIR SWC files. The”+=” operator to the -library-path option specifies to append the AIR SWC files to the Flex SWC files.
  • The ASDoc tool writes the output to the directory C:\Program Files\Adobe\Flex Builder 3\sdks\3.0.0\asdoc\air-asdoc.

If you have created multiple AIR components, you can use the following ASDoc command to generate documentation for an entire package:

..\bin\asdoc -doc-sources C:\myApplication\myComponents -library-path+=..\frameworks\libs\air -main-title "My AIR API Documentation" -window-title "My AIR API Documentation" -output air-asdoc

See the Flex 3 documentation for more information on the ASDoc tool.

 

Stephen Gilson
Flex Doc Team

Measuring Message Processing Performance in BlazeDS

One place to examine application performance is in the message processing part of the application. To help you gather this performance information in BlazeDS, you can enable the gathering of message timing and sizing data.

When enabled, information regarding message size, server processing time, and network travel time is available to the client that pushed a message to the server, to a client that received a pushed message from the server, or to a client that received an acknowledge message from the server in response a pushed message. A subset of this information is also available for access on the server.

Download the new chapter’s PDF: Measuring Message Processing Performance