64x64 icon dark hosting
Choose a hosting plan here and get a free year's subscription to Tuts+ (worth $180).
Advertisement

Look Up Movies With Flash and the Rotten Tomatoes API

by
Gift

Start a hosting plan from $3.92/mo and get a free year on Tuts+ (normally $180)

For some time now I've used Flixter and Rotten Tomatoes to find out which movies were worth watching. Today Rotten Tomatoes is my number one source for obtaining information about a particular film. When I discovered that Rotten Tomatoes had an open API, I knew that this was a perfect opportunity to demonstrate Flash's capabilities to connect with remote services. In this tutorial you will learn how to interact with the Rotten Tomatoes API, as we put together an efficient library that is easy to use and can quickly be expanded.


Final Result Preview

To use the demo below, immediately click the try button to use the default API key provided, or type in your own API key if the default key returns an error.

Type in a keyword and click Go to search; results are displayed within a draggable window. Click a movie poster to maximize its parent window.

For a larger view, click here.

In this tutorial, I'm not going to explain how to build the UI above (although all the code for the UI is provided); I'm going to explain how to use the Rotten Tomatoes API to obtain movie data that you can use in any UI or Flash app.


Prerequisites

This tutorial assumes that you have already registered as developer at the Rotten Tomatoes website and that you understand the concept of inheritance in Flash. You will also need to download the AS3 Core Library if you have not already done so. We will be using this library to parse JSON data returned by Rotten Tomatoes.

Another utility that you will need to run the demo application is the MinimalComps library. This library allows our application to provide a graphical user interface that visualizes data and adds user interaction.


Step 1: The DataLoader Class

We are going to start off with a blank application and then begin filling our application with data. Both the base and the complete applications are available in the source download.

At the time of this writing the Rotten Tomatoes API is currently only available in JSON format. We will need a base class that can prepare and handle different types of data loaded from the internet. Here is a list of formats that this class will handle.

  • JSON
  • XML
  • URL
  • Text

If Rotten Tomatoes updates their API to render XML data, for example, this class will make it easy to swap between formats. The developer can choose the format in which a particular DataLoader object should handle. Every class that loads data from Rotten Tomatoes will extend this class.

Create a new class called DataLoader. The class should extend flash.events.EventDispatcher. Also import the following classes:

Define the following properties.

You'll see the purpose of these properties in a bit. For now just create the constructor.

The loader object will load data into Flash. The _source object is a String that represents the location of the data to load. The _format object is also a String which represents how the loaded data should be handled or parsed.

Create the load method.

The load method does exactly what you expect it to: it loads the data from its source. We listen for the COMPLETE, IO_ERROR, and PROGRESS events to be dispatched from the loader object so that the corresponding methods can be called upon the event. If the vars object exists we want to apply the object to the new URLRequest object (req) that we just created. Finally we reset the _percentLoaded property to zero and call the load method from our Loader instance passing the URLRequest object to the parameter.

Now we'll create the event handler methods.

The onComplete method is called when the COMPLETE event is dispatched. The first thing we do is remove the event listeners on the loader since we no longer need to listen for them. The try block contains a call to the handleData method and a call to the parseData method. (We have not created these methods yet but will do so in a moment.)

If either one of these methods produces an error, that error is caught but a DataLoaderErrorEvent is dispatched in its place. (We will also create the DataLoaderErrorEvent class in a moment.)

Finally, we dispatch e, which is the COMPLETE event. There is no need to create a new Event object; we can just recycle the old one since it is no longer being used.

Just as we did in the onComplete method, remove all of the event listeners from the loader within the onIOError method. Then dispatch e which is the IO_ERROR event.

The onProgress method calculates a percentage based upon the amount of bytes that have been loaded and the number of bytes in total.


Step 2: Handling Data

Create the handleData method.

The handleData method decodes the loaded data. More specifically, it converts the loaded data to an Object. The type of Object is entirely based on the format.

The JSON format will create a dynamic primitive Object. Use the decode method of the JSON class to decode the json data; this returns a native Object. The XML format creates an XML object; the URL format creates a URLVariables object; and the Text format is simply a String representation of the loaded data.

If the format is set to none, the data will not be packaged or prepared at all.


Step 3: Parsing Data

Create the abstract method, parseData.

The parseData function has no implementation because it is a protected method that is meant to be extended and implemented by a subclass. This method is generally going to be used to by a subclass to serialize packaged data into a strict non-dynamic object so that it can be used to by other code more efficiently. This method can even be used to correct specific values or convert dates into the current timezone and so forth.


Step 4: Wrapping Up the DataLoader

All of the private properties of the DataLoader class that begin with an underscore (_), will need some type of access from outside code. Of course this will be accomplished with getter and setter methods. Create the following getters and setters.

When the format property is set, we check to if the value provided is valid. If it isn't valid an error is thrown.


Step 5: The DataLoaderErrorEvent Class

Now that we have completed the DataLoader class we must create the DataLoaderErrorEvent class before we can move on.

Instead of dispatching a simple ErrorEvent we created this class to dispatch a specific type of ErrorEvent. One that is related to parse error that occurrs in the DataLoader class.


Step 6: Loading Data

Since our DataLoader class is finished, we might as well load some data. Add the following code to the document class of your project:

Note: Remember to apply your own API_KEY to the above code.

When this code is executed it loads data from the URL http://api.rottentomatoes.com/api/public/v1.0/lists/dvds/upcoming.json. The following GET variables are sent with the request using the URLVariables class (or the vars property of the DataLoader object):

  • apikey - the API Key that was assigned by Rotten Tomatoes for your application.
  • country - the user's country.
  • page - a number that represents the current page of the returned results.
  • page_limit - an integer that specifies how many search results should be displayed per page.

When the above code is executed, the following output is produced by tracing out the rawData from the loader which is accessed as e.target in the onDataLoaded method.

(Note: Your results may vary.)

For those of you that find this data to be like an alien language, the returned data is in the JSON format or JavaScript Object Notation (read more about this here). This is probably not how you want your users to see the data. This is where the as3corelib comes into play.

In the example above, we traced the rawData. Now try changing the line of code within the onDataLoaded method to trace loader.data.total.

The total property of the JSON object is the number of results that were returned by Rotten Tomatoes. We'll utilize most of the data returned in later steps. Next we're going to begin extending the DataLoader class to better fit the needs of our application.


Step 7: Loading Tomatoes

Now that we know how to load data using the DataLoader class, let's improve our implementation. Create the TomatoLoader class.

Let me summarize this class's implementation. This class simplifies that process of loading data from Rotten Tomatoes. This class should also be treated as abstract, meaning it is meant to be extended. Here we have removed the ability to set the format property, since at the time of this writing the API only exists in the JSON format - but this restriction can be removed later.

The following properties are related to GET variables that are to be sent with the request to the Rotten Tomatoes API:

  • _pageLimit
  • _pageNumber
  • _country

We've already seen how their corresponding GET variables are used, as well as the total property from the JSON Object. All we are doing here is storing their values in instance properties so that they can be manipulated easily.

The _limit property is new to us. This property represents a limit on the number of results that should be returned by Rotten Tomatoes. (Note: This property may not apply to all requests, as only some API methods support it.)

We have overriden the abstract parseData method and have added some extra implementation. In the parseData method the number of pages (or _numOfPages) is calculated. The number of pages is equal to the total number of results divided amount of results per page.

We also override the load method so that we can make sure that our GET variables are being sent along with the request.

The TomatoLoader class dispatches the TomatoLoaderErrorEvent, which we'll create next.


Step 8: The TomatoLoaderDataEvent

Create the TomatoLoaderDataEvent class.

There isn't much to explain here. The message property is read-only and represents the error message that is returned from the Rotten Tomatoes API.


Step 9: Loading Movies

Our new DataLoader, the TomatoLoader, is going to be useful, but our application requires more. We now need to create one more abstract class that extends the TomatoLoader class, and is specifically for loading movie information.

Create the MovieLoader class.

This class adds implementation that further parses data about movies. TomatoMovie objects are generated from the data property and are added to the movies Array. When this class dispatches the COMPLETE event, we will have a complete list of movies for a particular page.


Step 10: Links

You should have noticed that there was a links property which was of the type TomatoLinks. We're going to create this object now.

The parse method parses the JSON Object into a TomatoLinks object. We have read-only access to all of the properties using getter methods.


Step 11: The TomatoMovie Class

The TomatoMovie object will consist of properties and objects that represent data about a particular movie, serialized into a static Object (static meaning the opposite of dynamic).

The parse method parses the JSON Object into a TomatoMovie object. It is very, very basic. The TomatoMovie class is just a more organized and well-defined collection of the JSON data. Unlike the JSON Object, which is generated at runtime, the TomatoMovie object is compiled. In other words it is more exclusive.

You're probably wondering why we created the TomatoMovie object and the TomatoLinks object if their corresponding JSON Object contains the same data. I have an answer for you: we want to provide read-only access to the data. We don't want the developer to accidently set (overwrite) any data.

If this seems foolish or unlikely to you I have another answer... code hinting. Many Flash IDEs like FlashDevelop and Flash CS5 Professional contain a code hinting feature, which lets us see which methods and properties exists on an object and what data types they are. By encoding this in an actual AS3 object, we can know exactly what data to expect before we compile our application.


Step 13: The Actors

Create the TomatoMovieActor class.

We use the parse to parse the JSON Object as we did before.


Step 14: Dates, Posters, and Ratings

Create the TomatoMovieDates class.

Create the TomatoMoviePoster class.

Create the TomatoMovieRatings class.


Step 15: Filling an Empty App

Now we have code that is efficient enough to begin filling in our application with data. Let's take another look at our empty application.

(Remember, this empty project is available in the source download. I'm not going to explain how to create it in this tutorial.)

First let's load and trace data from the objects that we have already created. Try loading movies currently in the Box Office with your application and displaying the first movie returned. You can find the method to load from the Rotten Tomatoes API Documentation. You can either use your own application with its own GUI or you can use the application provided in the source. Here's what my code looks like.

Below is the result of the following code.


Step 16: Performing Movie Searches

Performing a movie search with the Rotten Tomatoes API is just as simple as loading a movie from the box office. The only additional step is that you must submit the query with the request. Lets create a simple class to make this process easier for us. Create the TomatoMovieSearch class.

Now we can perform searches. Try adding an input textfield component and a Go button to your application if you haven't done so already. Again, here's my code.

I added the search event handler method to the application. This method is called when goBtn dispatches the CLICK event. The text from the input textfield is used to search the API with the provided query.


Step 17: Upcoming Movies

Let's create a simple class that will be dedicated to loading Upcoming Movies.


Step 18: Top Rentals

Next let's make a class that's dedicated to loading Top Rentals.


Step 19: Opening Movies

Finally let's make a class that is dedicated to loading Opening Movies.


Step 20: Displaying Options

Now let's give our users the different options to choose from. Try displaying multiple categories to the user through a combo box, then when the user selects an option, the option that they have selected is loaded and displayed. Here's my code again.

Each option's value is a private method that corresponds to the method that should be loaded from the API.

You can now see options with the combo box.


Step 21: Additional Options

You can follow the steps above to make more options. Try adding an In Theaters option, or an Upcoming DVDs option.


Conclusion

The DataLoader class can also be used with other APIs such as the Facebook Graph API and the Twitter API. You can also continue to extend the TomatoLoader class to expand our library to load more data. Try making classes that implement other methods in the Rotten Tomatoes API. I hope you learned a lot from this tutorial. See you next time.

Advertisement