Understanding the PureMVC Open Source Framework _ Activetuts+

8/7/2019 Understanding the PureMVC Open Source Framework _ Activetuts+

1/45

Advertise Here

Ahmed Nuaman on Dec 30th 2010 with 82 comments

Tutorial Details

Difficulty: Intermediate

Libraries: TweenLite, PureMVC

Twice a month, we revisit some of our readers favorite posts from throughout the history of Activetuts+.This tutorial was first published in May, 2009.

Now and again you may be asked to work on a project which requires a lot of coding and/or collaboration with

colleagues. Its safe to say that frameworks are often the best choice regarding structure, semantics and

productivity.

Understanding a framework can take a lot of time, but once youre happy with your knowledge, you can literally

code at the speed of thought. PureMVC is a great framework for AS3; some may say its a bit difficult to get

your head around, but youll be happy you did.

As you can see from the demo, what were working towards is pretty simple, but its enough to give you an

understanding of how PureMVC works.

Before we Start

Before we begin Id like to make sure the following bases are covered. This is a tutorial for intermediate to

advanced Actionscripters, but dont be intimidated if youre neither, theres no time like the present to start

learning!

rstanding the PureMVC Open Source Framework | Activetuts+ http://active.tutsplus.com/tutorials/workflow/understanding-the-pu

5 3/1/2011


2/45

This example is built using Flex Builder. You can go to Adobes web site and download yourself a copy

(60 day free trial!). However, itll happily work in an IDE of your choice, whether it be FlashDevelop,

FDT, or good ol TextMate.

1.

Like Ive said, this tutorial is for intermediate to advanced Actionscripters, so Im going to skip the

mundane parts such as setting up your project in your chosen IDE, etc

2.

Its worth noting that next time you go to do your business, its advisable to first print off a copy of

PureMVCs best practices. Its fairly heavy, but youll be glad you read it.

3.

Step 1: Set Up

It would be wise to grab yourself a copy of the project .zip file. Within it, you will see the basic set up for this

tutorial. Fire up your IDE (mine is Flex Builder) and create a new project. The next thing youll need to do is set

up the Flex compiler to use the "src" folder for the source path, the "debug" folder for the debug bin and the

"deploy" folder for the release bin. Simple.

Secondly, Ive included two additional libraries within the "src" folder:Greensocks TweenLite ("src/gs") and

PureMVC ("src/assets/swc"). Youll notice that Ive used a .swc for the PureMVC library rather than the source

folder, this is because I prefer using .swc files. Make sure that both these libraries are set to compile when youdebug and eventually deploy. Below is a screenshot of the target layout for the project. Although youre more

than welcome to import the project and go through it file by file, Im going to tell you how to write each file so

you end up with a project similar to the example.

Step 2: Fundamentals

The concept of PureMVC may make the best of us shy away, but once youve got your head around the bare

fundamentals, youll soon be flying your way around it. PureMVCs structure means that notifications are used


5 3/1/2011


3/45

to run certain commands whether they be within models, views or controllers. These notifications consist of the

name and an optional body. The body parameter allows you to send data from the view (such as which button

was clicked on) to a controller that can then pass it to model which then returns the relative data.

This notion of notifications means that PureMVC has a very definite structure to how the source files are set up:

Proxies(model):

A proxy is simply a model. A model, to those who may not know, is a class that handles all data

transactions such as loading XML data, storing it and retrieving it. Unlike mediators or commands, proxiesnever listen to or handle notifications; they only ever dispatch them. This means that in order for a

command or a mediator to get a hold of some data, the data will have to either be passed back to the called

via a notifications body or by retrieving the instance of the proxy from the facade. Proxies store their data

within public classes called VO (value objects). They are just simple classes that have public variables

where we can keep our data for retrieving and updating via our proxies.

Mediators and their views(view):

A mediator is a class that acts on behalf of a view. Within your application you may have several views

and all these views will be extending a DisplayObject class (otherwise they wouldnt be views). A

mediator will be the class that adds your view to your base (the "viewComponent"; its the first argument

thats passed to a mediator) and it will also handle all incoming and outgoing notifications relating to that

view. This means that the mediator is in charge of notifying your application if the user has triggered an

event in the view (such as by clicking a button) and will also be in charge of passing data from a proxy to

the view in order to update it. A mediator listens and handles notifications itself and is able to register new

mediators into the facade when theyre needed rather than loading them all at once.

Commands(controller):

A command is simply a controller. Although it doesnt listen to notifications itself, it does have

notifications piped to it from the facade. This means that a command has to run a conditional statement to

allow it to determine which notification its received and what to do next. As well as receiving

notifications, commands are allowed to send them out too. They are also able to register proxies, mediators

and more commands.

Hopefully that should have given you a simple understanding of how PureMVC is set out. For a visual

representation of how notifications can "fly" around your application, check out PureMVCs conceptualdiagram:


5 3/1/2011


4/45

Youll be forgiven if you think thats all very daunting, but once you sit down and plan out what your application

is going to look like, youll soon understand what were going for:

Our base class will fire up the facade1.

The facade will then call the start up command2.

The start up command will register our proxy and application mediator3. The proxy will then reference its value object and wait for further notifications4.

The application mediator will register the progress mediator5.

The progress mediator will create the progress view and then send a notification to load the data6.

The facade will receive this notification and pass it to the data command7.

The data command will then filter the notification and tell the proxy to load the data8.

The proxy will notify the progress view that its loading the data (it will be shown), the progress (it will be

updated) and when its finished (it will be hidden); the mediator will handle all of this

9.

The proxy will then send a notification for the application mediator to handle10.

The application mediator will register the urls view where well create buttons for the user to click11.

The urls view mediator will pass the data from the proxy to the urls view and add the urls view to the stage12.

The user will click on a button, this will then be handled by the mediator and a notification will be sent to

the proxy

13.

The proxy will then again load the data, always relaying the state to the progress view14.

The proxy will then again send a notification for the application mediator to handle15.

The application mediator will then tell the urls view mediator to hide the urls view and then register the

images view

16.

The images view mediator will create the images view from the proxys data17.

That may sound complex, but its just a case of braking down your applications function into small bit-size

chunks.


5 3/1/2011


5/45

Step 3: Everything Starts With the Facade

Whenever you work with PureMVC, you must understand that coding always starts with the facade. The facade

is a layer that links the PureMVC framework, your MVC code and your base Actionscript file; in this case

mines called "App.as". At runtime, App.as will do its business, whether it be setting up the scaling of the stage,

the frame rate and whatnot; and when its ready, itll call upon the facade to start up the application.

Lets create our base Actionscript file. Using your favourite IDE create a new file, name it "App.as" within "src"

and be sure that it extends the Sprite class like so:

Step 4: Setting Up the Base

Now that weve created our base class, feel free to add stuff such as setting the width, height, background

colours and so on. Its also handy to import any assets you may need, such as fonts or images. Once yourehappy with your base class, we can then move on to creating the facade. Below is a preview of my base class:


5 3/1/2011


6/45

Step 5: Setting Up the Facade

In this step we delve straight into the world of PureMVC. Like I said in Step 2, the facade is an important layer

which holds your application together. Create a new class called "ApplicationFacade.as" within "src/com

/flashtuts", make sure it extends Facade and implements IFacade. Note that our facade doesnt have a

constructor as its extending the Facade class. Within our facade were going to have 3 functions with a 4th

optional one. Additionally, were going to have 2 public constants. Below is what well aim to get our facade

class looking like:


5 3/1/2011


7/45

Within PureMVC, events or "notifications" are used to route data and trigger functions to be carried out within

our views or controllers. Therefore since our facade is going to send a notification to a command telling it to start

up the application, we create a unique constant that will be used by the facade to send the command and the

start up function listening to the command:


5 3/1/2011


8/45

Although you dont need to have a constant called NAME, its a good idea to always create it in classes that

have notification constants within them as to keep these notifications unique and less susceptible to human error

(such as spelling mistakes).

Next we come to the first of our required functions, "getInstance()". This is the first and foremost function of the

facade and allows our base class to retrieve an instance of the facade, then fire the start up command (well get

to that):

Now we come to the function which controls the routing of notifications to our controllers, or as PureMVC calls

them, commands:

Its pretty important to keep "registerCommand( STARTUP, StartupCommand );" as without this, the application

wouldnt start. All it basically means is that the facade will pass the notification called "STARTUP" to a

command called "StartupCommand". As you can see, I have two more. They both point to another controller

called "DataCommand" and both notifications are requests to get data.

We now get to our last required function without our facade, "startup()". All this simply does is fire a notification

which is routed to "StartupCommand" via the "registerCommand" handlers:

Finally, last but by no means least, we have our final function. This is an optional function that I like to add when

Im working with PureMVC as it allows me to see what events are being fired and in what order. The function

simply overwrites the "sendNotification()" function which you use within PureMVC to send notifications. As

well as notifying the applications observers, it traces the events for you to see:


5 3/1/2011


9/45

So thats our facade. Before were finished, we need to apply one more line to our base class. This line will

simply get an instance of our facade and then run the start up command:

Make sure you put this file at the end of whatever your base class is doing. For example, Ive put it under all the

stuff that sets the background gradient for my application:


5 3/1/2011


10/45

Now were ready to get our hands dirty.

Step 6: The Start Up Command

As discussed within Step 4, the facade handles all notification routing to our commands (the controllers). The

first command we have to create is the "StartupCommand". So create a new file called "StartupCommand.as"

within "src/com/flashtuts/controller". Make sure that it extends SimpleCommand and implements ICommand.

Just like our facade, our commands wont have constructors, instead override a public function from the

SimpleCommand class called "execute()":


45 3/1/2011


11/45

Youll notice that within our "execute()" function, theres one argument called "notification". We dont need to

use that as this stage, but this will become something that we do use within our other commands. As this

command is used to start up our application, the first thing it does it register a proxy (a model):

and then our mediator:

So now we have our start up command ready. What well do now is create our proxy and then get on to our

ApplicationMediator.

Step 7: Creating a Proxy

Now that we have our "StartupCommand" registering our proxy, we need to make sure that the proxy exists. So

create a new file called "DataProxy.as" within "src/com/flashtuts/model", and make sure it extends Proxy and

implements IProxy. To start off with were just going to have two functions within our proxy: the constructor and

a "get" function to retrieve the VO (value object):


45 3/1/2011


12/45

As you can see, the first function within our proxy is our constructor where we "super()" two variables: the

proxys name (set by the NAME constant) and the VO. We need to pass the name of the proxy as this will allow

us to retrieve the facades instance of it rather than creating a new instance and losing our VOs data:

The second function is a simple get function that returns our VO. This allows the proxies, commands and

mediators to easily access the VO via the proxy:

Before we finish with our proxy, we need to create our VO, so create a new class called "DataVO.as" within

"src/com/flashtuts/model/vo". Then were going to add three public variables: "dataURL:String",

"urlsArray:Array" and "urlsDataArray:Array". Were going to set the "dataURL" to point to our XML file in

"src/assets/xml" called "data.xml" and for the other two were just going to set them as empty arrays:


45 3/1/2011


13/45


14/45

As you can see, the mediator starts with our old friend the "NAME" constant and its constructor. Back when we

registered the mediator in Step 6, we passed an instance of the stage, our base class ("App.as") as the first

argument. Within our constructor we super the NAME and the first argument, the "viewComponent" as its theviewComponent thats going to allow our mediators to add their views to the stage, our base class.

Now is a good time to start talking about our views. Within my example I have three: a progress view, a url

selection view and an images view. For each view we have a mediator. Since the first thing we want to do is load

the data from our XML file, it seems fitting to create our progress view, then the mediator and then register the

mediator with our "ApplicationMediator".

By extending the class Mediator, it allows us to override a handy function called "onRegister()". This function is

called when the facade registers a mediator, so that seems the best place to get our "ApplicationMediator" to

register the mediator for our progress view:

As you can see, its the same style that we used within the "StartupCommand" and were passing the

"viewComponent" to the mediator so its able to add the progress view to the stage. Your application mediator

should look like this:


45 3/1/2011


15/45

Step 9: Creating Our Progress Mediator and View

Now that weve set our "ApplicationMediator" to register our "ProgressViewMediator", we first of all start by

creating a "ProgressView.as" class within "src/com/flashtuts/view/components". This is a class that simply

extends the DisplayObject, in this case Sprite. I wont go through the code for the view as its pretty standard for

any Actionscripter but I will talk about the interaction between the view and its mediator below:


45 3/1/2011


16/45


45 3/1/2011


17/45

As the mediator does all the talking for the view, its important the view and the mediator can pass information

to one another. The mediator can pass information to the view as the mediator will have an instance of the view

declared within it, but for the view to pass information to the mediator (such as a user clicking on a button) we

rely on events (not to be mixed up with notifications). We simply get our view to dispatch an event and get our

mediator to listen to that event. The mediator can therefore handle the event from the view, digest the

information and run something accordingly. We declared the name of these events by using public constants, so

our view has three events: SHOW, HIDE and UPDATE (much like our facade).

Note: the placing of event names can be placed within the facade ("ApplicationFacade.as" file) or within therelative views. I find it easier and cleaner to keep them within the views, but its up to you which way you think

works better for you.

As you can tell, Ive created a text field that will be used to display the percentage of the data loaded through

our application.

We can now move on to the mediator, so create a new file called "ProgressViewMediator.as" in "src/com

/flashtuts/view" and be sure that it extends Mediator and implements IMediator. Itll follow the same style as our

"ApplicationMediator" and therefore have a constructor that has one argument (the "viewComponent"), a public

constant called NAME and our friend the overridden "onRegister()". Below is what your mediator should look

like:

The first thing we need to add to our view as a reference into our mediator:


45 3/1/2011


18/45

and now we get the mediator to add our view to the "viewComponent" so we have:

Now that weve got the bare-bones of our mediator, we need to look at what our view is going to do. Well, as

you can probably tell from the constants, our view is going to tell the user how much has been loaded so far,

therefore it has the public constants SHOW, HIDE and UPDATE. Since these are going to be something that

our view will react to (as you can tell by the "show()", "hide()" and "update()" functions within our view), we

need our mediator to handle these notifications and run these functions accordingly.


45 3/1/2011


19/45

Well add two new functions to our mediator: "listNotificationInterests()" and "handleNotification()". The first

function returns an array of all the notifications this mediator is interested in (this is why its so important to stick

these notifications in public constants so theyre easy to reference). The latter actually does something with

them. This mediator is only interested in SHOW, HIDE and UPDATE so thats what we add to the first function

and handle in the second:


45 3/1/2011


20/45


45 3/1/2011


21/45

You can simply see that our "handleNotification()" takes the argument of an INotification, a class that contains

the name and body of a notification. We use a "switch" statement to determine which notification is to be

handled and run the functions accordingly. Simple.

Congratulations! Youve reached the first milestone! Havent we come far? Test your file and you should see the

following:

Milestone

So far weve created our facade, added a command, proxy and application mediator, then created a view and

added it to our application using the views facade.

Step 10: Creating Our URLs View

Now we want to load some data. Before we do this, lets create the view that will be used to display this data. As

were loading three Flickr API feeds, I see it fitting that in our next view we create three buttons which allow the

user to click, at which point our application will return the images from the corresponding feed. Lets then create

a new file called "URLsView.as" in "src/com/flashtuts/view/component" and just like our "ProgressView", this

will extend the Sprite class:


45 3/1/2011


22/45


45 3/1/2011


23/45

Im not going to walk you through this view class, as with all the view classes. Theyre basic AS3 classes and

you should be familiar with them. However, as you can see Ive left the constructor out as we only want to build

the buttons when the data has been loaded by our "DataProxy". Also, take note of the public constants at the top

of the class, mainly DATA_GET and DATA_READY. These are events that will be fired off in order to signal

that the data needs to be loaded, then that the data has loaded and is ready for the view.

We now come to our views mediator, so create a file called "URLsViewMediator.as" within "src/com/flashtuts

/view" and make sure it extends Mediator and implements IMediator. This is just like all mediators within our

application. As with our "ProgressViewMediator" this one has a constructor where it supers itsNAME and the

"viewComponent" and also has the overridden "onRegister" function. Again, just like "ProgressViewMediator",

we declare a new instance of our view:

We now need to think about what our view is going to do. Well, its going to allow the user to click on a button


45 3/1/2011


24/45

within it and dispatch an event (thats what the function "handleContainerClick()" within the view does). We

need to tell our mediator to give our view a listener for that event and handle it accordingly:

Now we need to think about when this mediator will come into use. Remember earlier I said that theres no point

running a mediator before its needed? Well this mediator isnt going to be run before we need it, so were

assuming that when its first registered, the data will be ready for the view to build the buttons, so we update our

"onRegister()" function to send the data to the view, show the view and add it to the stage. Since our data is

stored within our "DataProxy" VO, well need to add another function which allows us to access the facades

instance of the proxy and retrieve data from the VO:


45 3/1/2011


25/45

Finally, as this mediator will be created when the datas ready, we need to tell our "ProgressView" that we no

longer want it to be visible, so we fire a notification called "ProgressView.HIDE" which will be picked up by the

"ProgressViewMediator" and will tell "ProgressView" to hide itself:

Once again, before we can continue, we need to think about which notifications this mediator will need to listen

to. Since were going to make this a usable application, theres no point in not letting the user go back and pick

another Flickr feed url, so it makes sense to allow this view to be shown again. This is where the public const

SHOW comes in to play (youll notice that I have a naming convention when it comes to all my notifications,

this is a good thing and will speed up your development). Just like with our "ProgressViewMediator", we add

"listNotificationInterests()" and "handleNotification()" functions to our class:


45 3/1/2011


26/45


45 3/1/2011


27/45

Youll notice that Ive added some stuff to the "handleContainerClick()" function. All this function does is

simply pass the index of the button pressed (like 0, 1, 2) with the event name "URLsView.CLICKED". We

will handle this event shortly as this is the event well use to load the Flickr feed the user has picked.

Now that our view is ready for our data, we can proceed to the proxy and load some XML. Whoop whoop!

Step 11: Loading DataAs I mentioned above, our "ProgressViewMediator" fires off a notification called "URLsView.DATA_GET". In

order for our proxy to receive this notification, we need it to go via our facade and then a command that will

then call the proxys function. First then, we need to register the command within our facade, so open up

"ApplicationFacade.as" and add the "registerCommand" function to the "initializeController()" function like so:


45 3/1/2011


28/45


29/45

If you have a sharp eye, youll notice that were facing our friend the INotification class. Just as with a mediator,

this class gives us the name and body of a notification, so we handle it in the same way with a switch:

Since we want that notification to tell the proxy to load some data, we need to get the facades instance of the

proxy and get it to fire a function. We use the same method we used within our mediator and create a get

function:


45 3/1/2011


30/45

Finally, youll see that were calling a function within our proxy called "urlsDataGet()". This will load our data,

so wed better create it. Open up "DataProxy.as" and create a function called "urlsDataGet()" which will load

the data, like so:


45 3/1/2011


31/45


32/45

Youll notice that were making use of our VO here by again creating a get function so that we can use and add

data to it. You should be familiar with loading XML data so I wont walk through the functions; you should be

able to see what they do. You may be wondering why Im running through a loop of the urls from the XML data

and populating an array with an empty string, youll find out later

The main things I will mention are the "handleProgress()" and "handleURLsDataGetComplete()" functions. They

both send notifications to the application, the first sends a percentage of the data load to our progress view

(remember I said a notification is made up of a name and body?) and the latter sends a notification to the

application stating that our first bit of data has finished loading.

Finally, because we only want our "URLsViewMediator" and "URLsView" to be registered when the data is

ready, we need to amend the application mediator to register the mediator when that event is sent:


45 3/1/2011


33/45

That code shouldnt be too unfamiliar, but as you can see were setting which notifications we want it to listen to

and then handling them. In this case registering the "URLsViewMediator" which runs its "onRegister()" function

and builds the view.

Were at the next mile stone! Now we should see that our application will load the XML data and then pass this

data to our "URLsViewMediator" which will in turn tell the "URLsView" to create some buttons ready for the

user to click:


45 3/1/2011


34/45

Milestone

Give yourself a pat on the back as youve achieved a lot! By now you should be familiar with how notifications

play a big part in the application and how the whole structure is brought together by the facade. The next bit will

be a breeze

Step 12: Handling a User Event

As I explained earlier, a view will dispatch a user event, such as mouse move or in this case mouse click. This

event will then be picked up by its mediator which then decides what to do. Since weve set up the function

"handleContainerClick()" within "URLsViewMediator" to send an index of the button, we now need to handle

that event and load the subsequent data. First well need to build our final view and mediator.

Heres the view:


45 3/1/2011


35/45


45 3/1/2011


36/45

All this view does is take the XML data loaded in from the Flickr API, build a grid of images and a back button.

Heres the mediator:


45 3/1/2011


37/45


38/45


39/45


40/45


41/45


42/45


43/45


45 3/1/2011


44/45

Youll notice Ive performed a bit of Actionscript wizardry in the "imagesDataGet()" function. Again, its just

loading some XML, nothing special about that, but itll only load unique data once. This is the beauty of having

VOs and using indexes when buttons are pressed. Essentially what happens is that if the user presses button 2

(the 3rd one), itll check to see if that index has any data bound to it (as the loop when the urls were first loaded

created an array with empty strings). If it has, theres no need to load the data again, otherwise the datas loaded

and using the beauty ofDictionaries, were able to put it into the array.

Finally, this proxy then pushes the notification "ImagesView.DATA_READY" back to our application and to our

view where some magic will happen..

Youve done it!

Theres your first PureMVC application! You should know have an understanding of how PureMVC works and,

most valuably, a skeleton so when it comes to developing more applications you can take this code, rework it or

just use it as reference.

Footnote

PureMVC is a great tool and I use it on many projects, but there are some key differences between using it with

Actionscript 3.0 and MXML. When you use MXML, you add the views using XML, like so:


45 3/1/2011


45/45

Documents

Understanding the PureMVC Open Source Framework _ Activetuts+