Throughout this book, you’ve learned about all the pieces comprising Flex. But you haven’t seen how these pieces come together to create a working application. An academic knowledge of Flex is essential to successfully building Flex applications, but that knowledge is of little value unless you also have a concrete understanding of how to use what you’ve learned in practice. In this chapter, we’ll look at how to build a Flex application using everything you learned in the first 21 chapters of the book. We’ll walk through building a sample application to illustrate important concepts, and to give you practical experience building a Flex application.
In this chapter, we’ll take a look at a sample application that illustrates the key points we discuss in the chapter. The sample application is a simple photo viewer that uses the Flickr API from the popular photo-sharing service, Flickr (http://www.flickr.com), to allow users to search for photos via keywords and then view photo details. We call this application FlickrFlex.
Figure 22-1 shows the application’s home page, which displays a random photo and a search form.
The entire application runs in a web browser, and it supports the browser’s back and forward buttons as well as deep linking directly to a search result or to a specific photo’s details.
Throughout this chapter, we’ll take a look at key parts of the application. What we will not do is go line by line through the code and build the application step by step. Instead, we highlight what we think are important concepts, and then we are leaving it to you, the reader, to download the sample application and review the code in more detail. You may also find that you will gain the most from this chapter if you read it more than once.
Once the user searches for photos, the results are shown in a tile grid (see Figure 22-2).
The user can click a thumbnail to view the photo details screen, as shown in Figure 22-3.
Even though FlickrFlex is a relatively simple application, we think it is complex enough that it encompasses many of the common requirements of Flex web applications. For example, FlickrFlex has to solve problems related to making requests to remote services, which is a very common problem for Flex applications. Also, FlickrFlex has to solve the problems related to browser integration, which is quite a common requirement for Flex applications. By looking at FlickrFlex, we think you’ll be able to see ways to solve common problems that you are likely to find in many of your own projects. The purpose of our discussion of FlickrFlex is to look at larger themes and patterns; strategies for solving common application design problems. Therefore, rather than building the entire application one line of code at a time, we’ll highlight the important features and patterns.
Every project starts with the basics. You always have to configure the environment, get access to services, and create projects files. In the next few sections, we’ll look at the steps required to get started.
The sample application runs off the Flickr service. To follow along you will need to have a Flickr account and an API key. Both are free.
To apply for a Flickr account, go to http://www.flickr.com/signup. Flickr is owned by Yahoo!, and a Flickr account is synonymous with a Yahoo! account. If you already have a Yahoo! account, you don’t need to apply for a Flickr account because you can use your existing account.
Once you have logged in with the Flickr account, go to http://www.flickr.com/services/api/keys/apply to apply for a new Flickr API key. The Flickr API requires the API key. To follow along with this sample application, you should apply for a noncommercial key.
Once you’ve created a Flickr API key, you can continue to the next section. You’ll next get the source code for the application, and you’ll need to edit a configuration file with your Flickr API key.
Rather than trying to walk you through the steps for writing all the code for the sample application, we’ve opted to simply provide you with complete, working source code. You can then spend less time typing code from listings in the book and more time reading about why the code is written the way it is.
To distribute the source code for the sample application, we’ve created a Google Code project for FlickrFlex. You can view the project site at http://code.google.com/p/flickrflex/. From the Google Code project site, you can download the application source code in one of two ways: using Subversion or as a .zip file.
We recommend using Subversion to download the source code. You can use any Subversion client to check out the project by using the following repository URL: http://flickrflex.googlecode.com/svn/trunk/flickrflex-read-only. This URL will work only with a Subversion client, and not in a web browser.
If you're not comfortable using Subversion (though we highly recommend that you learn how to use it), you can instead download the FlickrFlex application as a .zip file from the project’s download page, at http://code.google.com/p/flickrflex/downloads/list.
Regardless of how you download the project files, we assume that you have downloaded (and extracted, if necessary) all the project files before continuing with the rest of the chapter. Although you can read this chapter and learn much from it without downloading and using the project files, it is likely that you will gain much more if you do follow along with the project files.
Note
Subversion is a version control system. Using a Subversion client and the preceding URL you can download a read-only version of the FlickrFlex project from the Google Code Subversion server. A detailed description of what Subversion is and how to use it is beyond the scope of this book. However, if you want to learn more about Subversion you can read the entirely free Subversion book, Version Control with Subversion, at http://svnbook.red-bean.com. You can also find a list of Subversion client programs at http://subversion.tigris.org/links.html#clients. Using most of these clients is rather simple, especially when checking out a read-only version of a project, and you can generally find instructions for how to check out a project in the documentation for each client.
If you are using Flex Builder 3, you can simply import the Flex
project, as we’ve included all the Flex Builder project files along with
the source code. If you are not using Flex Builder, you will need to
compile the application using mxmlc,
as you learned how to do in Chapter 2. Flickr.mxml is the main application .mxml file for FlickrFlex, and TestRunner.mxml is the main .mxml file for running the unit tests for the
project.
The code for the FlickrFlex application is complete and working exactly as downloaded. However, you will need to provide your Flickr API key and secret, both of which you can find at http://www.flickr.com/services/api/keys/. You should locate and edit the assets_embed/xml/flickrconfig.xml file in the application project files. The file contains the following:
<configuration>
<apiKey>Your API key</apiKey>
<secret>Your API secret</secret>
</configuration>You should replace your API key and your API secret text with the correct values from the Flickr page.
Now that you’ve downloaded and configured the FlickrFlex project, the next step is to compile it. This is a straightforward step since there is nothing particularly unusual about the project. If you are using Flex Builder and you’ve imported the Flex project, you’ll probably note that two of the .mxml files are set to be compilable: TestRunner.mxml and Flick.mxml. The Flickr.mxml file is the file you want to compile, and in Flex Builder the compilation step is automatic unless you’ve disabled automatic builds for the project. That means all you need to do is run the Flickr.mxml file to compile and launch it.
If you’re using the Flex SDK without Flex Builder, you will need
to compile Flickr.mxml using
mxmlc. FlickrFlex does not require
any additional libraries or any unusual compiler options.
When you have successfully followed the preceding steps, you should be able to compile and run the application. You’ll know the application is working correctly when you can verify the following user stories:
The user sees a random “nature” photo on the home page.
The user can enter a search term on the home page and request search results.
When search results are returned, the user sees thumbnails and titles for all search results displayed in a scrollable grid.
When the user clicks on a thumbnail in the search results, she is taken to that photo’s details screen in which she sees a large version of the photo along with the title and description (if any exist).
From the details screen the user can click a button to return to the previous screen.
From the details screen the user can click Next and Previous buttons to navigate through details of the search results.
The user can navigate back and forward between viewed pages/screens by using the back and forward web browser buttons.
The user can copy the address from the browser address bar at any point and paste it into another browser window to see the same page/screen (a process known as deep linking).