UML, Stub Code and ASDocs
I have recently started using Enterprise Architect (EA) for creating UML diagrams for Actionscript and Flex projects. This is an outstanding product that is reducing my development time and helping me to create self documenting code following AsDoc formatting rules. If you have never created a UML diagram or used UML software, the concept can seem a little overwhelming but let me assure you, your time spent learning how to do so will be time very well spent.
In it's simplest form UML software allows a person to visually layout and architect a project before ever doing any actual coding. You can create your classes, document the properties and functions you intend to use, organize them and relate them (for either implementing or extending). At this point you are probably wondering why you would want to do that when you could just fire up your IDE of choice and start coding. Before I started using Enterprise Architect I only had one really good reason, it makes you think through the solution and plan before you start coding, so you can attack the project with a well defined plan. Now I have another reason, that I think is just as important as the first, EA can generate all your UML'd classes in either AS2 or AS3 in ASDoc friendly format. All your stub code is generated in seconds, perfectly formatted and compilable. This is an absolutely huge time and effort saver. By using UML you can create a well structured plan for your project and using the code generation in EA allows you to export all that planning effort into perfectly formatted Actionscript. I have created a sample project to demonstrate just how nicely this solution works and hopefully show why you may want to consider this approach for your projects. I will walk you through how to create a simple UML diagram in EA, how to export the diagram into AS3 files, and how to run the AS3 code through ASDoc to create project documentation.
You can download all my source files for this sample here.
Step 1 - Configure EA for Actionscript projects
Download the trial version of Enterprise Architect. Once you have it installed a few adustments need to be made. First, select the 'Tools/Options' menu and click the 'Source Code Engineering' node, set the 'Default Language for Code Generation' to 'Actionscript'. Click on the 'Actionscript' node and set the 'Default Version' to whichever AS version you are working in. Second, the templates that generate the AS code need some tweaks (just a few minor things that EA appears to have missed). You have two options, import the template updates I created or do it manually. To import my adjustements, download this file, unzip it, in EA, open the 'Tools' menu and select the 'Import Reference Data' item. Browse to the 'actionscript_code_templates.xml' file, select and open it, select the 'Actionscript_Code_Template' and click 'Import'. To do it manualy open the 'Settings' menu and select the 'Code Generation Templates' item and then make these two changes.
- Select the 'Class' template, change the entire section to
%ImportSection%\n %ClassNotes% %ClassDeclaration% %ClassBody%
This puts the import statements after the package declaration but before the class declaration in the as files. - Select the 'Operation Declaration' template, find this block of code (near the top)
%PI=" "% %opStatic == "T" ? "static"% %if genOptActionscriptVersion=="3.0" and opTag:"namespace"!=""% %opTag:"namespace"% %else% %CONVERT_SCOPE(opScope)% %endIf%
and change it to this%PI=" "% %opStatic == "T" ? "static"% %if genOptActionscriptVersion=="3.0" and opTag:"namespace"!=""% %opTag:"namespace"% %elseIf elemType=="Interface"% %else% %CONVERT_SCOPE(opScope)% %endIf%
This ensures that functions in Interfaces can not be declared Public, Private etc, which will throw a compiler error.
Step 2 - Create a UML diagram
Open EA and create a new project. In the project browser you can setup your package structure. For this sample I will keep it really simple and add a few packages 'com.dgrigg.vo', 'com.dgrigg.view'. The next step is creating the diagram. You can drag Class and Interface (to name a few) elements onto the diagram to begin creating your class structure. As you add new elements, you are prompted to enter the class properties. Enter information in the 'Notes' field to explain what the class is for. A few things to note when you are creating elements.
- As you create Classes, Interfaces etc. and add Operations and Attributes (functions and properties) to each, be sure to enter a description in the 'Notes' field, this will get exported in your code and also be used by ASDocs.
- When you create a new class you must create a constructor for it in the Operators list, for some reason EA does not do this for Actionscript projects.
- If you add an Operator that has return value, be sure to enter a return line in the 'Initial Code' field on the 'Behavior' tab. This will set a 'default' return value in the code and allow ASDoc to properly execute and also not throw any compiler errors.
- If the element you are working with needs to import '.as' files, right click on the element in the 'Project Browser', select 'Generate Code' and enter your import statements in the second 'Import(s)/Header(s)' field, click the 'Save' button.
When you are all done your diagram it will look something like this.
Step 3 - Generate the AS file
In the Project Browser right click on the 'com' folder, or whatever you root package folder is, and select 'Code Engineering/Generate Source Code'. Set the path you want to export to, check the 'Include all Child Packages' options, and click the 'Generate' button. Below is a sample of a generated AS file, straight from EA with no editing.
///////////////////////////////////////////////////////////
// ProductList.as
// Macromedia ActionScript Implementation of the Class ProductList
// Generated by Enterprise Architect
// Created on: 14-Sep-2006 5:08:46 PM
// Original author: Derrick Grigg
///////////////////////////////////////////////////////////
package com.dgrigg.view
{
import com.dgrigg.vo.ProductVO;
import flash.text.TextField;
import mx.controls.DataGrid;
import flash.events.Event;
import com.dgrigg.vo.ProductVO;
import com.dgrigg.view.IView;
/**
* Displays a DataGrid of products, lets the user select and view a product.
*
* @see com.dgrigg.vo.ProductVO
* @author Derrick Grigg
* @version 1.0
* @updated 14-Sep-2006 7:38:22 PM
*/
public class ProductList implements IView
{
/**
* displays the list of products
*/
private var products_dg: DataGrid;
/**
* display the selected product's name
*/
private var name_txt: TextField;
/**
* display the selected products' description
*/
private var description_txt: TextField;
/**
* display the selected product's sku
*/
private var sku_txt: TextField;
/**
* Constructor
*/
public function ProductList()
{
}
/**
* add a product to the displayed product list
*
* @param product product to add to the product list
*/
public function addProduct(product:ProductVO): Boolean
{
return true;
}
public function getSelectedProduct(): ProductVO
{
return new ProductVO();
}
/**
* handle the event that is triggered when a user selected a row in the data grid
*
* @param event event dispatched from DataGrid
*/
public function handleSelectedProduct(event:Event): void
{
}
}//end ProductList
}
Step 4 - Generate the ASDoc files
Download and install the ASDoc tool from Adobe. I have created a little bat file I use with ASDoc just to make is easier to recreate the files whenever I need to without having to remember my settings, you can download it here. Run ASDoc to create your files. Click here to see the final ASDocs files.
Conclusion
If you develop Actionscript projects of any size and/or complexity, and you need some documentation done along the way, the steps I have outlined above are any excellent way to quickly generate both the stub code you need to begin your development and some project documentation, which as we all know is a hassle to create but invaluable to have. Enjoy
Search
About
Archives
Recent Posts
Links
Feeds