First FoxR Movie Part 2: Editing content
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
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
