http://github.com/jfox015/FoxR

After almost six months of dormancy, I have a few ideas for some small updates for a 0.3 release, then I think it’s time make some demos already to show off just how FoxR can help achieve the goals I’ve outlined for it. It should be a busy summer for me, but I hope to squeeze in as much as I can to keep things moving forward.

Everyone to their bases – Flash is under attack!
Jens C Brynildsen at Flash magazine
http://www.flashmagazine.com/community/detail/everyone_to_their_bases_-_flash_is_under_attack/

Flash is Dead… Long Live Flash
Devon O. Wolfgang at onebyoneblog
http://blog.onebyonedesign.com/?p=421

And some further looks at the points levied against Flash:

http://blogs.adobe.com/jnack/2010/01/sympathy_for_the_devil.html

And another breakdown of why Flash will lead the charge and HTML 5 (and more importantly the browsers that serve it) will always play catch-up:

http://richardleggett.co.uk/blog/index.php/2010/02/01/the-world-is-moving-to-html5

and a look at HTML 5 video support and it’s current issues

http://createdigitalmotion.com/2010/02/html5-and-a-brave-flash-free-open-world-uh-not-so-fast/

I think these taken together form good support for the theory that

1. Change in the way interactive on the web works is well under way, but has a long way to go. Still never a bad thing to be at the head of the pack that bringing up the rear
2. Flash will move forward past it’s current incarnation into something no one might yet see, but something we the Flash Developers should be on the lookout for
3. IE does and always will suck the life out of all of us (just wanted to throw that in)

One more maintenance/bug release, 0.3, is expected to occur in January before the Public beta in February. If using FoxR you find any bugs or would like to request features, please do so on the Google Code Issue List page.

Ever since I started working with ActionScript 3 way back in the summer of 2007 and for the entire two plus years that I’ve been working on FoxR, I have had considerable trouble generating AsDoc API documentation.

Not that making AsDocs has ever really been easy, but back when I was working prominently in ActionScript 2, there was a handy and ridiculous simple program As2Doc that provided a simple and intuitive way to generate clean and professional looking API documents.

Sadly, I have yet to see a program like As2Doc for ActionScript 3. The good news is, however, that Adobe does provide an AsDoc application as part of both the Flex/Flash Builder platform install and the free Flex SDK packages. Simply called asdoc.exe, this nifty little app will take you AS3 files and generate the same style documentation as those found at Adobe LiveDocs.

The one major drawback of this program is that it’s a command line tool. To get it to compile your AsDocs properly, you have to write one heck of a long command string. And if you mess up one character, you have to keep tweaking it until you get it right. When you work in a fast paced and agile environemnt like I do, this is not a good solution. I knew there had to be a better way. So I did some Googling and finally came across one.

Compile AsDocs with an Ant Build script

I’ve been familiar with Apache Ant since back in my days with Starwood Hotels where our individual development sandboxes were compiled and managed by numerous ant build scripts. If you’re not familiar with them, they consist of one XML based file usually called build.xml and one or more optional files that defined a number of target tasks like compiling JAR files in Java or running the asdoc.exe for AsDoc compilation.

Doing Google searches I came across numerous examples of these Ant build scripts to compile ASDocs. But once again, Ant is a command line tool and I wanted a way to steamline both the editing and running of these scripts (otheriwse I’d just run asdoc.exe from the command line itself). I found numerous references to the ease of using Eclipse’s built in support for ant and chose to go that route.

The one major hurdle that I never could see to figure out was how to get my install of Eclipse Gallileo (which I downloaded with the PHP Development Tools plugin) to support both editing and running Ant scripts automatically. Out of the box, Eclipse was not providing me with the Ant Editor or Ant Builder tools I’d seen so many people referencing in their blog posts and tutotials. So I was stuck until I finally struck blog paydirt.

The solution turned out to be mind numbingly simple, but somehow took me a long time to dig. For Eclipse to automatically support Ant within the editor, you need to download the Java Development Tools (or JDT) plugin. A quick guide to performing this update in Flex 3 (which works the same across all Eclipse and Eclipse based Flex/Flash Builder IDEs) is available on gunua.com and I am Josh.com.

So with the JDT plug-in installed, I finally was able to edit my build.xml file within Eclipse by right clicking and choosing Open With… > Ant Editor and then running it via Run As… > Ant Build . A few bug fixes to some error found in the code while compiling and Wha-Lah, at long last I had FoxR Api Docs.

The Ant script that I ended up using (with obviuos changes for my library and local paths) was found at Ruben’s Blog. I’ve posted a copy of his script Zip file in the Appendix of this post for convineince.

I hope this post is helpful to anyone who might be strugglign with getting set up as I was.

Appendix: Downloads

Ruben’s Ant Build Files Zip

Welcome back to part two of lesson one, your first FoxR movie. In part one we took the time to download the FoxR library and the default project template and set up new projects in the most popular Flash IDEs.

Here in part 2, we’ll now dive into the code itself, making changes to both the textural, style and display content properties of our first project. This lesson will cover in depth:

• An overview of FoxR’s predefined visual architecture
• The Element.addElement() method
• Modifying the content of a FoxR view class and incorporating custom FoxR objects into the view
• Assigning styles to components, text and graphical elements via CSS and the CSSProxy
• Adding text content via the CopyProxy

So without further ado, let’s jump in.

The FoxR Visual Architecture

By default, FoxR let’s you tap into a strong yet flexible visual architecture which I’ve come to code name "The Stack". The stack is essentially a set of predefined view classes that have corresponding mediators to allow loosely coupled communication between the movies other view elements as well as FoxR’s wide array of supporting classes.

Each of the layers is based off the global Element class. Element extends the AS3 Sprite class and adds a large number of helpful shortcut methods to help you get coding fast and write ultra compact, clean code. The Element class is truly worthy of it’s own tutorial so we’ll leave further analysis of this class for the next lesson.

FoxR Visual Architecture Diagram. Click to view full sized.

The diagram above displays what the stack looks like visually. As the name implies, it is literally a stack of empty containers that can be used to build a clean consistent set of layers with which to separate and manage your content at run time.

For the purpose of this tutorial, we will be focusing our efforts within the pages layer. This layer forms the basis for probably 95% of the content you’ll add to a FoxR movie.

The Pages class is a special container class that defines a mechanism to load an unlimited number of child pages within it. These pages are based on the com.fox.display.Page class which features several methods for managing their display effects as you navigate through the project.

Pages are changed by sending a APPLICATION.CHANGE_PAGE notification and passing the name of the page. Child pages are defined in the com.foxr.data.GlobalConfig.as file. An in depth look at this process will be covered in a future tutorial.

Modifying the content of a view class

Now that we have a basic understanding of the way the visual architecture is structured, let’s dive right in a start making some changes that we can see in our movie. if you followed all the steps in the first tutorial, you should have ended up running the project and seeing a movie that looks like this:

Not really all that exciting to look at is it? So let’s see if we can’t spice it up a little.

Our first task will be to add both an Image and button objects to accompany the default text field located in the view. As mentioned earlier, the FoxR Element class contains a number of short cut methods to help you simplify your code.

The Element.addElement method

The most important of these functions (and the one you’ll see used the most within the libraries visual elements) is the addElement method. This method take two required and two optional arguments:

• Instance Name – The name of the new Element instance. This value is assigned to the name attribute of the new object so that it can be called using the Sprite.getChildByName() method.
• Class Name – The name of the class being invoked.
• Parameter Object (OPTIONAL) – An object containing key/value pairs of setter values.
• CSS Object (OPTIONAL) – An object derived from the CSSProxy.getStyle() method.

Here’s an example of the method and it’s arguments in use:

var btnTop:ScrollbarButton = null;
btnTop = ScrollbarButton(addElement('btnTop',ScrollbarButton,{x:0,direction:'up'},gpm.css.getStyle('scroll_button')));

Notice that I cast the object returned by addElement to a ScrollbarButton as I assigned it to the btnTop variable. This is because addElement returns all created instances as simple Element objects. Without casting, you wouldn’t be able to access the special attributes and methods that the ScrollbarButton class includes.

Adding Elements to the View

Armed with this knowledge we can now add two new objects to the default view class. The HomePage class is the default view class object that comes with the 0.2 Project Template. It is located in in flash/com/foxr/views/pages/HomePage.as. Open this file in your project IDE. Here is what the HomePage.as class looks like out of the box:

package com.foxr.view.pages
{
	import com.foxr.display.Page;
	import flash.events.Event;
	/**
	 * Home
	 * Main page in the application project.
	 *
	 * @author		Jeff Fox
	 *
	 */
	public class HomePage extends Page {

		/*--------------------------------------
		/	VARIABLES
		/-------------------------------------*/

		/*--------------------------------------
		/	CONSTRUCTOR
		/-------------------------------------*/
		/**
		 * C'TOR
		 * Construct a new Home instance
		 *
		 */
		public function HomePage() { 

		} // END function
		/*--------------------------------------
		/	SET/GET FUNCTIONS
		/-------------------------------------*/

		/*--------------------------------------
		/	PUBLIC FUNCTIONS
		/-------------------------------------*/
		/**
		 * 	OBJECT READY.
		 * 	Fired when the object is added to the stage. Place all your objects to be rendered to the
		 *  stage within this method, NOT the constructor.
		 *	@since	1.0
		 */
		public override function objReady(e:Event):void {
			super.objReady(e);
			txt.text = gpm.copy.getCopyString('global.home.body');
			txt.applyProperties( { x:150, y:200, alpha:1.0, visible:true } );
			txt.style = gpm.css.getTextFormat('general_copy');

		}
		/*--------------------------------------
		/	PRIVATE FUNCTIONS
		/-------------------------------------*/
	} // END class
} // END package

The important part of this class to note is the objReady function. This is a function inherited from Element which is called automatically once the object has been added to the stage and is part of the active view list. You should place any code that should only be run after the object has been added to the stage within or following this functions execution (by calling other methods within in).

So let’s get to adding some stuff. The first thing we need to do is import the classes and set up our variables that will let us reference our new objects directly. We place them in the variable section of the class.

	import com.foxr.display.Page;
	import com.foxr.display.content.Image;
	import com.foxr.display.buttons.StandardButton;

	import flash.events.Event;

		/*--------------------------------------
		/	VARIABLES
		/-------------------------------------*/
		private var img:Image = null;
		private var btn:StandardButton = null;

Next, using addElement, we add the two new objects to the view.

		public override function objReady(e:Event):void {
			super.objReady(e);
			txt.text = gpm.copy.getCopyString('global.home.body');
			txt.applyProperties( { x:150, y:200, alpha:1.0, visible:true } );
			txt.style = gpm.css.getTextFormat('general_copy');

            img = Image(addElement('img', Image));
			btn = StandardButton(addElement('btn', StandardButton));
		} // END function

You’ll notice I added these elements within the objReady function. This is because we’ll want to take advantage of the gpm property of the Page class (inherited from Element) later in the process. You’ll see it is already being used to provide content to the txt text field that is included in the Page class by default.

Adding styles via the CSSProxy

Now we have an image and button object in our view. If you were to run the movie though, nothing would show up on the stage. This is because we need to add some visual display properties to our new elements.

The traditional way to add properties to objects is to apply them individually as such:

		img.x = 125;
        img.y = 150;
        img.src = 'flash_logo.png';

As you can imagine, if you have a large number of objects being instantiated and styled in your view, your AS file can get quite long and quite full with lots of these individual properties being added. More over, if you had the same type of element across a number of files, you end up repeating this same code again and again. While Flash does a code job compressing file sizes when compiling, this still can begin to add up.

FoxR provides you a shortcut in this situation using Web standard CSS. Here is how you achieve the same effect in FoxR using the CSSProxy:

CSS Code

img {
	x: 125px;
    y: 150px;
    src: flash_logo.png;
}

FoxR AS3 Code

	img = Image(addElement('img', Image,null,gpm.css.getStyle('img')));

Not only did we combine four lines of AS3 code (including the instantiation of the object) down to one, but we also turned the image properties into a CSS class that can be reused (or even better yet extended!) across multiple instances. And since it’s CSS, if I wanted to override the src property for a successive element, I could simply put the following into a separate class within the same or separate CSS file:

CSS Code

img {
    src: alt_image.png;
}

We use of the CSSProxy by tapping into a powerful Proxy class called the GlobalProxyManager. This "super proxy" contains the following global proxy (model) class objects:

• CSSProxy Loads, stores and provides access to global CSS styles
• CopyProxy- Loads, stores and provides access to global XML based copy strings
• ConfigProxy – Global configuration manager
• VisualConfigProxy – Global visual configuration settings manager
• AnalyticsProxy – Global Analytics interface manager
• LOG – Global external logging/trace manager

The gpm property is instantiated during the framework’s startup and is available to all Element and Element subclasses so you need not do anything to access the gpm property other than be sure you only call it within or following the objReady function within your display classes.

To get access to the global instance of the CSSProxy object, you simply type gpm.css and then call the method you need to access. In the AS3 example above, we used the getStyle method which takes one String argument, the CSS selector name.

FoxR CSS Stylesheets are located in the deploy folder of the project template in /deploy/media/css. The default CSS file that comes with the project is global.css. We’ll open global.css, add the img class above and also add a second class with styles for our StandardButton object.

CSS Code

btn {
	width:100px;
    height:24px;
    x:400px;
    y:90px;
    background-color:#FFFFCC;
    border-width:1px;
    border-color:#000000;
}

If you save the updated global.css file and compile your movie, you should now see the new view elements displaying in your default project movie.

Adding Text Content with the CopyProxy

So we now have our image and button displaying in our movie, but we want to add some instructions to the button. While we could simply add text to the button using the text property within HomePage.as, that’s not exactly keeping with the MVC principles of the project.

Once again, FoxR provides a standard and built-in mechanism for applying copy to your project using the CopyProxy. As with the CSSProxy, the CopyProxy is available as a property of the GPM. It utilizes one or more standard copy XML files located in the deploy/xml folder. The default copy XML file included with Foxr is called global.xml.

Opening this file reveals that the copy is structured in several main blocks of copy organized by their usage including a general, home page and login block. You notice that the copy displayed in text field in the main content area, "Hello World! I’m here" is located in the global/home/body node.

Since we want to add copy to our button on the home page, we are going to create a new node within the home block and call it "button". Within the button node we add the copy "Click Me!".

XML Code

	
		Click Me!
	

To apply the copy to the button we use the standard FoxR text property called string. The string property is derived from the FoxR TextElement class and provides a shortcut to accessing copy xml values that are loaded and stored by the CopyProxy object. When the CopyProxy loads copy XML files, it uses the FoxR utility class XMLObjectOutput to convert the XML into a standard key/value object whose structure matches that of the original XML. String values are thereby accessed using standard object notation.

To access the value of our new button string, we add the following command to our button instantiation code: string:'global.home.button'. Our amended addElement code for the btn object therefore looks like this:

FoxR AS3 Code

	btn = StandardButton(addElement('btn', StandardButton, gpm.css.getStyle('btn'), {string:'global.home.button'}));

If you compile and run the movie you should now see…no text in the button? Wait? What gives? This is because we have to apply a text style to the button as well to tell it how to render the text. Because we already have a general text style called general_copy defined in the global.css file, we’ll simply apply that style to the button using the StandardButton’s textStyle property. textStyle is inherited from the CompoundObject class as is used by any of it’s subclasses that includes a TextElement object by default.

Because text styles are applied to TextElements as standard AS3 TextFormat objects rather than the simple key/value attribute objects that are returned by the CSSProxy’s getStyle method, we use another CSSProxy method called getTextFormat. This method returns the CSS class as a standard AS3 TextFormat object

FoxR AS3 Code

	btn = StandardButton(addElement('btn', StandardButton, gpm.css.getStyle('btn'), {string:'global.home.button',textStyle:gpm.css.getTextFormat('general_copy')}));

Compiling and testing the movie with the text style applied now renders the text in the button as expected.

Putting it all together

In this tutorial we covered how to use the Element.addElement method as a shortcut to not only adding elements to our movie’s page display objects, but also utilizing the built in Copy and CSS Proxy classes to apply text and style attributes to them in a general way that supports the MVC philosophy of separating content and style from the logical code.

From here, you can continue to add other FoxR elements and manipulate styles in the global.css file or change copy within the global.xml file. Save and compile your project each time to see how changes affect the display of the movie.

In lesson 1, we covered a lot of ground in terms of setting up your first FoxR movie and customizing the content, but we’ve still barely scratched the surface. Stay tuned for more in depth tutorials covering numerous aspect of this powerful MVC based framework.

Appendix: Downloads

Download the files featured within this tutorial.

Download FoxR

Download Tutorial Files

For the first FoxR tutorial, we’ll start with downloading and installing both the framework and the Quick Start Project Template using both to creating an advanced “Hello World” movie. I say advanced because the Project Template includes everything you’ll need to get a compiling project setup fast, including the standard “Hello World” message.

You can find links to download all the tools featured in this tutorial in the appendix section.

Step 1: Download FoxR and the Project Template

Download the latest release of the FoxR library and the accompanying Project Template.

Download FoxR

Download Project Template

Step 2: Extracting your files

I’m going to break this out into a separate step because I think it’s important to note that since FoxR is designed to be a generic, reusable framework, it is best to keep the main library files for FoxR separate from your individual projects. This way you can use FoxR over multiple projects.

As a matter of personal work flow, I always sub categorize my code libraries (AS3, JS, PHP, etc) into release folders. I.E. I create a FoxR directory then a “0.1 Alpha”, “0.2 Alpha”, etc. This allows me to safely upgrade code libraries without breaking legacy projects that might be tightly tied to specific features that may have changed, been removed or cause serious conflicts. For the purpose of this tutorial, I’m going to keep things simple and not do this, but a good matter of habit to get into.

Step 3: Setting up your first project

How you set up the project depends mainly on what IDE you will be using to develop your application in. For this tutorial, we will be demonstrating the setup in three of the most popular ActionScript IDE applications:

1. Flash Develop 3
2. Eclipse with the Flash Builder 4 Beta Plug-in
3. Flash CS4

The steps to extract the FoxR files are predominately the same across all these IDE’s, but setting up the project itself is a little different.

Flash Develop 3

Since FlashDevlop 3 is the main tool that I used to build the FoxR library, this is the first of the tools we’ll review.

To set up a new FoxR project with Flash Develop 3:

1. Choose a directory to place your FoxR work. For this demo I’ve created a new folder in my “My Documents” directory called “As3 Projects”.
2. Extract the contents of the FoxR library Zip file into this directory. You should see a folder called “FoxR_Alpha_0.2″ which contains the library and all supporting files.
3. Extract the contents of the FoxR Project Template zip file into the “As3 Projects” folder as well. You will see a folder called “New FoxR Project”

4. Open the “New FoxR Project” folder and you will see three folders (deploy, flash and obj) and a file called MyProject.as3proj.
5. Double click MyProject.as3proj to launch the project in Flash Develop and open the Properties dialog (Project > Properties)
6. In the Output tab, you’ll see that Flash Player 9 is the target player and that the movie compiles to deploy/foxr.swf.
7. On the classpaths tab, assure that the classpaths box contains the “flash” and “..\FoxR_Alpha_0.2″ directories. See Figure 1.

8. If you are going to compile and test your FoxR project within FlashDevelop and have not set FlashDevelop up to do so, see this article on setting up Flash Develop to compile your movie.
9. Otherwise, click Project > Build Project (F8) to test the build. If you receive no compilation errors then click Project > Test Movie (F5) to see the default project SWF.
10. You should see a screen similar to figure 2. If so, your ready to proceed to Step 4.

(Click for larger Image)

Eclipse (with Flex/Flash Builder plug-ins)

The following project setup is for Eclipse based editors such as Flex 3, Flash Builder 4 (still in Beta at the time of this writing) or the standalone Eclipse IDE with one of the aforementioned plug-ins (as opposed to the standalone editors themselves).

For this tutorial I am using the standalone Eclipse with the Flash Builder 4 Beta 2 plug-in, though the steps we’ll be performing are compatible with any Eclipse based Fox tool editor.

1. Since Eclipse uses work spaces to organize projects, decide if you want your FoxR library within your Workspace directory. For this tutorial, I will be not be doing this, extracting the FoxR library to a folder in “My Documents” called “AS3 Projects”
2. Open Eclipse and launch the Flash perspective (Window > Open Perspective > Other… and Choose Flash
3. Click File > New…
4. In the New dialog, choose Flash > ActionScript Project
5. Name the project “FirstFoxRMovie”, under Project Contents, save it in the default or a custom workspace, under Flex SDK version select use default SDK and click Next >
6. On the Source Path tab, add the FoxR AS library to your project by clicking Add Folder… and browsing to the location of the library (for me this is “My Documents > AS3 Projects > FoxR_alpha_0.2″. Click OK and OK
7. Under the files box, set the Main source folder property to “flash”, Main Application File to “FoxR.as” and the Output folder property to “deploy”
8. Click Finish.
9. Eclipse should have now created your new project. (Figure 3)
   

Flash Builder creates extra files we don’t need so you can safely delete the content of the flash folder. Now using Windows Explorer (or Finder for the Mac folks), browse to the projects directory in the Eclipse workspace. Open the “New FoxR Project.zip” file and extract the contents of the flash and deploy directories into your Eclipse project directory. Overwrite any duplicates. Now, let’s finish the Eclipse set-up.

1. Return to Eclipse, right click on the FirstFoxrMovie project and refresh it. Your new files
   should appear.
2. Under Flash > (default package) delete FirstFoxrMovie.as if it is present.
3. Right click on the FirstFoxrMovie project and choose Properties…
4. Choose “ActionScript Application” and click Add…
5. Select FoxR.as and click OK
6. In the ActionScript Application screen, click FoxR.as and click the Set as default button. Click OK.
7. The main project window, rename “FirstFoxRMovie.html” to “FoxR.html”, open it, search for “FirstFoxrMovie” and replace it with “FoxR”. Save and close the file.
8. Right click FoxR.as and choose Run As… > Web Application. NOTE: If this option does not appear, consult the Flash Builder documentation for help in setting up compiling options for the Flash Perspective.
9. If the Flash movie appears in your default browser, your ready for Step 4

Flash CS4

Must to my own personal chagrin, getting up and running in the Flash IDE is actually the easiest of all the paths. If you leave the defaults you need just extract the files, confirm the settings and compile.

To begin setting up the project:

1. Follow Steps 1-3 of the Flash Develop 3 process.
2. Open the “New FoxR Project” folder and you will see three folders (deploy, flash and obj). open the “flash” folder and you will see the file FoxR.fla.
3. Double click to open this file in the Flash IDE. NOTE: This FLAis saved in Flash CS3 format so Flash CS4 users may receive an upgrade warning if saving this file.
4. Confirm the output and compiler settings are correct by opening the Publish Setting dialog (File > Publish Settings…)
5. Under the formats tab, the file path for the Flash format should be “../deploy/foxr.swf”
6. Under the Flash tab, next to Script, assure “ActionScript 3,0″ is selected and click Settings.
7. Assure that “./” and “../../FoxR_Alpha_0.2″ are listed on the classpaths tab. Click OK.

Flash Classpath Settings

8. Click OK on the Publish Settings dialog.
9. Test the movie (Control > Delete ASO Files and Test Movie).

Step 4: Changing the default movie text

Now that we have our FoxR project up and running, the next step will be to dive in and start customizing the default template. In Part two of lesson 1, we will look under the hood of the project template and see how FoxR handles copy, styles and movie settings. Stay tuned!

Appendix: Asset Downloads

Download the tools featured in this tutorial:

Flash Develop 3

Eclipse

Flash Builder 4 Beta

Flash CS4 Trial

Understanding the PureMVC Open Source Framework

And if you happen to be light on MVC in general, my former colleague Thaylin Burns put together a MVC walk through on his blog as well.

MVC (Model-View-Controller) introduction simplified.

There is also a very simplified lesson by Colin Moock that some might find helpful as well: Colin Moock’s MVC Lecture.

Enjoy and please give these authors feedback on their work.

Despite reading this, I won’t be cutting the cord on PureMVC (seeing how I just switched over to it this summer) because it’s a tag based framework specifically for Flex. But it is good to be informed that there is another fish in the water in case it;s brought to my attention.

This is why I threw this out as an alpha to identify things like this. The 0.2.1 update is committed to SVN at the Google Code site and the 0.2 ZIP has also been updated in the Releases section of the site.

Thanks to Richard for the big heads up.