Shortly we’ll look at much of the code in more detail. However, before we do so, you’ll need to understand how the FlickrFlex application handles browser integration (deep linking and the back and forward buttons). The principle is rather simple: all significant state change requests are routed through the BrowserManager class by updating the address fragment. For example, when the user clicks on a Search button, the FlickrFlex application does not directly change the state to the search results screen or immediately make the request to the search method on the Flickr service. Instead, the application updates the address fragment via BrowserManager and waits for BrowserManager to dispatch an event notifying the application to update as necessary. We’ll see a few specific examples of this later on. However, the basic way in which the application manages this behavior depends on a simple infrastructure provided by a few methods in a few of the .mxml files, which we’ll look at now.

The main application .mxml file is Flickr.mxml. This file contains little more than a Style tag and an instance of FlickrController. The FlickrController class is where we start to set up browser integration. Within the initializeHandler() method, we tell the application to listen for changes to the URL via the BrowserManager:

_browserManager.addEventListener(BrowserChangeEvent.APPLICATION_URL_CHANGE,
                                 urlChangeHandler);
_browserManager.addEventListener(BrowserChangeEvent.BROWSER_URL_CHANGE,
                                 urlChangeHandler);

When the URL changes, the first thing we do is parse the fragment into an array, using a forward slash as a delimiter:

var fragments:Array = _browserManager.fragment.split("/");

We then remove the first element from the array and use that to determine what state to set on the view. If, for example, the fragment is search/nature (which is what the fragment would be if the user runs a search using the term nature), the first element in the array will be search, which means we want to tell the view to change to the search screen. In every case, we pass along the remaining fragment to the view:

var topFragment:String = fragments.shift();
if(topFragment == "search") {
    view.setMode(FlickrView.MODE_SEARCH_SCREEN, fragments.join("/"));
}
else if(topFragment == "") {
    view.setMode(FlickrView.MODE_HOME, fragments.join("/"));
}
else if(topFragment == "details") {
    view.setMode(FlickrView.MODE_PHOTO_DETAILS, fragments.join("/"));
}

Within FlickrView’s setMode() method, we change the state and then assign the remaining fragment to the screenFragment property of the corresponding screen if appropriate:

public function setMode(mode:String, fragment:String = null):void {
    currentState = mode;
    if(fragment != null && fragment.length > 0) {
        if(mode == MODE_SEARCH_SCREEN) {
            searchScreen.screenFragment = fragment;
        }
        else if(mode == MODE_PHOTO_DETAILS) {
            photoDetailsScreen.screenFragment = fragment;
        }
    }
}

If the entire fragment was search/nature, the setMode() method would change the state to the search screen state and assign nature to the screenFragment property of searchScreen. Later in the chapter, when we talk about views and controllers, we’ll see how the search screen handles the fragment. However, at this point the specifics of how fragments are ultimately utilized in specific views and controllers aren’t as important as the overall pattern. To summarize and restate: for FlickrFlex we have a hierarchical structure of objects (FlickrController contains FlickrView, FlickrView contains HomeController, etc.). FlickrController listens for URL changes, and when the fragment changes, FlickrController starts to trickle down the fragment updates by notifying FlickrView. FlickrView uses the fragment to decide how to change state, and it then passes along the remainder of the fragment to the controller corresponding to the new state. This pattern could theoretically be continued for as many levels of hierarchy that exist.

The majority of Flex applications utilize a service of one sort or another, whether the services are SOAP services, REST services, AMF (Remoting) services, or any other sort. Elements of the Flex application need to interact with these services. For example, a user may request from a service a list of states or provinces for a given country, or a user may fill out a form in Flex and then submit the form to a service method.

In a naïve approach, the actual implementation that a Flex application uses to interact with a service may be exposed directly to all elements within the Flex application. For example, if a part of the application needs to query a SOAP service for a list of states or provinces, it is possible to allow that part of the application to create an instance of the WebService component with the appropriate operation, and to bind the results of the operation directly to a UI component. This may work, but it is a shortsighted solution that creates fragility.

Instead of the aforementioned solution, you can use a common pattern known as the Business Delegate pattern. A business delegate is a class that serves as a proxy to a remote service, defining an API that the rest of the application can use without having to know anything about the implementation details. That way, the rest of the application only has to know about its contract with the business delegate. If the implementation details change, the rest of the application doesn’t have to change as long as the business delegate API remains the same. For example, an application may initially utilize a set of SOAP web services. Later the services may be migrated over to use Remoting (AMF) instead. If the application doesn’t use a business delegate, many parts of the application may need updating to work with the new services. However, if the application uses a business delegate, only the business delegate needs to change.

FlickrFlex uses the Business Delegate pattern. In this application, we define a class called com.oreilly.pf3.flickr.services.FlickrService. This class allows us to define a simple API for the rest of the FlickrFlex application to use without having to know anything about the implementation details. The FlickrService class defines only three methods: searchPhotosByText(), getPhotoDetails(), and getPhotoSizes(). The rest of the application can call these methods without having to know whether FlickrFlex is actually making requests to local XML files or a remote service. However, it turns out that in this example we are going to have the application connect to a remote service.

In the FlickrFlex application, we are connecting to only one service: the Flickr service. We don’t want to get too bogged down in the details of the Flickr service since our primary focus in this chapter is to better understand common Flex application design and development problems and solutions. However, to make sense of the code for the sample application we’ll need to explain just a few things about working with the Flickr service.

For the purposes of the sample application, we’re necessarily using only a small subset of the Flickr API. We’re calling only three Flickr service methods: one to search photos, one to get information about a specific photo, and one to get the different sizes of a specific photo.

The Flickr service uses what is known as representational state transfer, more commonly known as REST. REST uses URLs to access resources. The Flickr service allows us to call methods via resources. In the case of the sample application, there are three methods that we relate to business delegate methods: flickr.photos.search, flickr.photos.getInfo, and flickr.photos.getSizes. Next we need to look at how to access these methods.

You must use the same pattern to access any Flickr resources. You must make an HTTP request to the REST resource along with a query string indicating the method and parameters. The REST resource is http://api.flickr.com/services/rest/. Therefore, you can see that in FlickrService we define a constant called REST_URL as follows:

static private const REST_URL:String = "http://api.flickr.com/services/rest/?";

The query string for Flickr service requests must always include the method name along with the required parameters for that method. The Flickr API documentation lists the required parameters for each method. All methods require the API key. You can see that in FlickrService we define three methods that call REST service methods, each method calling a different service method with different parameters, but each following the same basic pattern. We’ll look at searchPhotosByText(). This method calls the flickr.photos.search method, which requires a text parameter, which is a comma-delimited list of words for which to search.

public function searchPhotosByText(text:String):PendingOperation {
    text = text.split(" ").join(",");
    var method:String = "flickr.photos.search";
    var parameters:Array = new Array();
    parameters.push(new NameValue("api_key", _apiKey));
    parameters.push(new NameValue("method", method));
    parameters.push(new NameValue("text", text));
    var url:String = REST_URL + createQueryString(parameters);
    var pendingOperation:PendingOperation = new PendingOperation(url);
    return pendingOperation;
}

You can see that this method creates an array of NameValue objects, which are simply objects with name and value properties, and then passes that array to createQueryString() to create the query string, which it appends to the REST URL.

If we look next at createQueryString(), we can see that it simply takes all the names and values and strings them together with = and & delimiters:

private function createQueryString(parameters:Array):String {
    var queryString:String = "";
    var i:int;
    for(i = 0; i < parameters.length; i++) {
        queryString += parameters[i].name + "=" + parameters[i].value + "&";
    }
    return queryString;
}

The searchPhotosByText() method then returns a new PendingOperation object, passing it the newly constructed URL. The PendingOperation class simply makes an HTTP request to the specified URL, and it proxies the response, dispatching an event when the response is returned.

package com.oreilly.pf3.flickr.services {

    import flash.events.Event;
    import flash.events.EventDispatcher;
    import flash.events.HTTPStatusEvent;
    import flash.net.URLLoader;
    import flash.net.URLRequest;

    import mx.rpc.events.FaultEvent;
    import mx.rpc.events.ResultEvent;

    public class PendingOperation extends EventDispatcher {

        static public const RESULT:String = "result";
        static public const ERROR:String = "error";

        private var _loader:URLLoader;
        private var _vo:*;

        public function PendingOperation(url:String, vo:* = null) {
            _loader = new URLLoader();
            _loader.addEventListener("complete", resultHandler);
            _loader.addEventListener(HTTPStatusEvent.HTTP_STATUS, errorHandler);
            _loader.load(new URLRequest(url));
            _vo = vo;
        }

        private function resultHandler(event:Event):void {
            dispatchEvent(new ResultEvent(RESULT, false, true,
ParsingUtility.parse(new XML(_loader.data), _vo)));
        }

        private function errorHandler(event:HTTPStatusEvent):void {
            dispatchEvent(new FaultEvent(ERROR));
        }
    }
}

You can see that the PendingOperation class relies on a method of the ParsingUtility class. We’re using this custom ParsingUtility class to determine what type of response the service has returned and convert it to the correct type. For example, when the PendingOperation object is handling the response from a flickr.photos.search method, the ParsingUtility class detects the response as such and converts the XML into an ArrayCollection of Photo objects, which is exactly what the rest of the FlickrFlex application expects.

We’ve designed the FlickrService and PendingOperation classes in this way so that the rest of the application needs to know nothing about the implementation details. As far as the controllers and views and the rest of the application are concerned, it makes no difference whether the Flickr service is a REST service. If Flickr decided to change to an AMF service at some point, we could adapt the application with little to no changes to any of the code outside the services package.

The Model-View-Controller (MVC) architectural pattern is utilized across many languages and platforms. If you have experience building software of any sort, chances are MVC is familiar to you. Volumes have been written about this pattern, and we won’t try to repeat much of what has already been said. Instead, we’re primarily concerned with the usefulness of the pattern in Flex applications and the nuances of how to implement it practically in Flex. However, if you aren’t already familiar with this pattern, we’ll outline it briefly.

The principle concern of MVC is to effectively separate the business logic and the user interface code such that they interact with one another only through well-defined programming interfaces. The idea is that this approach reduces fragility because you can make changes to one without having to necessarily make changes to the other.

As the name implies, this pattern typically uses three parts—model, view, and controller:

Although it’s possible to write models, views, and controllers in a 1:1:1 ratio, it’s also possible that a controller could be used with many different views and that a model could likewise be used by many different views and controllers.

You can implement the MVC pattern in many different ways at many different levels. At one level, it is possible to create one model and one controller for an entire application (which uses many different views). It is also possible to implement the pattern at a more granular level, creating controllers, models, and views for all components. How you implement the pattern will depend on the complexity of the application and your preferences as a developer. In the FlickrFlex application, we have opted for a more granular approach.

Next we’ll look at creating models, views, and controllers in Flex applications.

private var _id:String;
private var _owner:String;
private var _secret:String;
private var _server:String;
private var _farm:String;
private var _title:String;
private var _thumbnailUrl:String;
private var _description:String;
private var _tags:ArrayCollection;
private var _imageMediumUrl:String;
private var _imageLargeUrl:String;

public function get id():String {
    return _id;
}

[Bindable(event="descriptionChanged")]
public function set description(value:String):void {
    _description = value;
    dispatchEvent(new Event("descriptionChanged"));
}

public function get description():String {
    return _description;
}

static public function parseFromXml(xml:XML):Photo {
    var id:String = xml.@id;
    var owner:String = xml.@owner;
    var secret:String = xml.@secret;
    var server:String = xml.@server;
    var farm:String = xml.@farm;
    var title:String = xml.@title;
    return new Photo(id, owner, secret, server, farm, title);
}

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="vertical"
xmlns:views="com.oreilly.pf3.flickr.views.*" xmlns:controllers="com.oreilly.
pf3.flickr.
controllers.*" backgroundColor="#4F5050">
    <mx:Style source="assets_embed/css/FlickrFlex.css"/>
    <controllers:FlickrController/>
</mx:Application>

<mx:HBox width="100%" height="45" backgroundColor="#212122" verticalAlign="middle">
    <mx:HBox styleName="green" height="100%">
        <mx:Label text="tags" />
        <mx:TextInput id="searchTermInput" text="{_searchTerm}" />
        <mx:Spacer width="10" />
        <mx:Button id="searchButton" label="Search for Photos"
            styleName="green" height="100%"
            click="dispatchEvent(new PhotoSearchEvent(searchTermInput.text));" />
    </mx:HBox>
</mx:HBox>
<mx:TileList id="photoList" width="100%" height="100%"
    itemRenderer="com.oreilly.pf3.flickr.views.renderers.PhotoRenderer"
    dataProvider="{_dataProvider}"
    change="dispatchEvent(new PhotoSelectEvent(photoList.selectedItem.id));" />

<screens:SearchScreen id="view" photoSearch="photoSearchHandler(event);"
photoSelect="photoSelectHandler(event);" />

private function photoSearchHandler(event:PhotoSearchEvent):void {
    BrowserManager.getInstance().setFragment("search/" + event.searchTerm);
}

private function photoSelectHandler(event:PhotoSelectEvent):void {
    BrowserManager.getInstance().setFragment("details/" + event.photoId);
}

public function set screenFragment(value:String):void {
    value = unescape(value);
    ApplicationModel.getInstance().searchTerm = value;
    if(_searchTerm != value) {
        view.searchTerm  = value;
        searchForPhotos(value);
    }
}

private function searchForPhotos(searchTerm:String):void {
    _searchTerm = searchTerm;
    view.isSearching = true;
    var pendingOperation:PendingOperation = _service.searchPhotosByText(_searchTerm);
    pendingOperation.addEventListener(PendingOperation.RESULT,
                                      searchForPhotosResultHandler);
}

private function searchForPhotosResultHandler(event:ResultEvent):void {
    var photos:ArrayCollection = event.result as ArrayCollection;
    ApplicationModel.getInstance().searchResults = photos;
    view.dataProvider = photos;
    view.isSearching = false;
}