Flex and ASDocs

30 01 2009

Flex builder offers a very easy way to generate documentation for your actionscript classes API. There are basically 2 steps involved:

– Comment your actionscript class as per ASDoc guidelines. You can refer the instructions in the Flex documentation.

– Use ASDoc external tool from within your Flex builder to generate the documentation. You can do this using commandline as well. However, I found it much more convenient using Flex builder.

Here’s what I did for my project:

Tool used: Flex Builder 3, SDK 3.2.0

1. Add comments to my custom UniConverter class (plz note this is not the complete class) as follows:

package com.bs.uni
{
	import fl.core.UIComponent;

	/**
	* This component class can be used to convert different
	* special characters to unicode characters for a given string.
	*
	*/
	public class UniConverter extends UIComponent
	{
		private var _strResult:String;

		/**
		* Convert basic latin special characters to unicode for a
		* given string.
		*
		* @param src The source string that contains basic latin
		* special characters which needs to be converted to unicode.
		*
		* @return The source string with basic latin
		* special characters converted to unicode.
		*/
		public function basicLatin(src:String):String
		{
			if (src == null)
			{
				throw("Invalid source string.");
			}
			else
			{
				_strResult = src;
				convert(BasicLatinXML.getXML());

				return _strResult;
			}
		}

2. Select Run > External Tools > Open External Tools Dialog

3. Add a program and name it ASDoc_Uni. You can give any name.

4. Location: field — add C:\Program Files\Adobe\Flex Builder 3\sdks\3.2.0\bin\asdoc.exe

5. Working Directory: field — browse to my project folder. The field shows ${workspace_loc:/UniConverter} which points to my working directory.

6. Arguments: field — add the following command

-source-path "C:\Program Files\Adobe\Adobe Flash CS4\Common\Configuration\Component Source\ActionScript 3.0\User Interface"
${workspace_loc:/UniConverter} 
-doc-classes fl.core.UIComponent
com.bs.uni.UniConverter 
-exclude-classes fl.core.UIComponent
-exclude-dependencies=true
-main-title "Unicode Converter" 
-window-title "Unicode Converter"

The above command adds 2 source paths for the classes that have been used – my project directory and the current actionscript API. It specifies 2 classes – my custom class and the UIcomponent class which it inherits. Now, I only want my custom class in the documentation and not the flash inbuilt UIComponent class. To exclude the UIComponent class, specify it next to -exclude-classes and also set -exclude-dependencies=true. Finally, I just set the documentation title and the window title as “Unicode Converter”. There’s more you can do, just check the ASDoc documentation.

7. Once through, click Run. A new folder named asdoc-output is created in project folder. Open the folder and launch index.html. There you go, documentation is all set.

 

Flex ASDoc Tool

Flex ASDoc Tool





Handle XML with namespaces

29 01 2009

Yesterday, I faced an issue while working with an xml file in Flash. I was unable to parse the xml data using the normal E4X syntax such as xml.node1.node2. It would give an error. The only thing different about this particular xml is that it has a lot of namespaces declared in it. After going through the documentation I found out a way to handle this issue. Check the following code:

var xml:XML = <Workbook xmlns:c="urn:schemas-microsoft-com:office:component:spreadsheet" xmlns:html="http://www.w3.org/TR/REC-html40" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="urn:schemas-microsoft-com:office:spreadsheet" xmlns:x2="http://schemas.microsoft.com/office/excel/2003/xml" xmlns:ss="urn:schemas-microsoft-com:office:spreadsheet" xmlns:x="urn:schemas-microsoft-com:office:excel">
	<ss:Worksheet ss:Name="Sheet1">
	<Table ss:StyleID="ta1">
		<Row ss:AutoFitHeight="0" ss:Height="13.4064">
			<Cell>
				<Data ss:Type="String">Preview</Data>
			</Cell>
			<Cell>
				<Data ss:Type="String">unicode</Data>
			</Cell>
			<Cell>
				<Data ss:Type="String">htmlcode</Data>
			</Cell>
			<Cell>
				<Data ss:Type="String">htmlalt</Data>
			</Cell>
			<Cell>
				<Data ss:Type="String">utfcode</Data>
			</Cell>
			<Cell>
				<Data ss:Type="String">utfalt</Data>
			</Cell>
		</Row>
	</Table>
	</ss:Worksheet>
</Workbook>

namespace ns1 = "urn:schemas-microsoft-com:office:spreadsheet";
use namespace ns1;

trace(xml..*::Table.Row[0].Cell[0].Data); //Preview

Here, I just declared the default namespace for the above xml. Try this code without the namespace statement and you will get an error. The namespace declared without a prefix is the default namespace for the xml. For this xml the default namespace is xmlns=”urn:schemas-microsoft-com:office:spreadsheet”.

In this case what I’ve done is declared the default namespace in actionscript. And to reference a deeply nested node I’ve used “..*::” instead of a simple ” ..”

Also, in case you want to remove all the namespaces mentioned in the xml, you can try doing something like this:

var arNS:Array = xml.inScopeNamespaces();
for each (var item:Namespace in arNS)
{
	xml.removeNamespace(item);
}

However, do note that this will not remove the default namespace.





Flex vs Silverlight vs AJAX vs JavaFX

15 01 2009

Yesterday, I was having this interesting conversation with a couple of  friends regarding which technology will rule the RIA space in the future. I believe, there’s room for all four of these as per my observations and experience. In fact, all these will have a separate domain and overlap at only few places. For example, AJAX is widely popular for creating community building apps,  portals, mashups, and so on. Flex is used for multimedia rich requirements, for example, interactive maps, photo albums, portfolios, games, product websites, etc. Silverlight is a direct competition here but might have more presence in the Enterprise apps market.

Flex has an advantage of running on the Flash platform which has a very wide reach on the internet and an integrated support from other Adobe products such as Photoshop, Flash, Illustrator, Fireworks, After Effects and some upcoming products – Catalyst, Thermo, Cocomo, and more. These are industry leading tools that help in building visually rich images, animations, and videos. AIR version adds value by having a desktop version of an app that is integrated with the online one.

Silverlight has the benefit of a huge community of .Net developers who will not need to learn anything new from scratch and utilize the huge libraries of .Net components available in the framework. It has a seamless integration between desktop and online version as well. Because of this, building enterprise applications will be the area in which Silverlight might edge over others.

AJAX, ofcourse, has two big advantages which has no competition as of now. These are – no plugin required and SEO enabled. That’s why apps like eBay, Amazon, MySpace, Blogs, and many more will continue to be largely based on AJAX with a few widgets/components built on either of the other three technologies.

JavaFX, is a late entry into this domain, although it all started with a Java product only i.e. Applet. Java enthusiasts will definitely lap onto this. It just remains to be seen what kind of value add JavaFX will bring over others. You never know, since it’s Java, the most reliable internet technology when it comes to providing security to user’s data.

There can, maybe, a scenario where a single app (for example eBay) utilizing all the four technologies for its different features.

So, whatever may happen, it’s the user who will benefit the most with a wide array of technologies to choose from. For developers, it will be important to specialize in one and at least have a good understanding of the rest to provide the best solution to a customer.