Upcoming.org Event Browser
by Allen Rabinovich, Flash Platform Engineer
Yahoo!'s Upcoming.org is a popular social event calendar, with an open API for editing and retrieving event data. Yahoo!'s Upcoming.org API makes it trivially easy to access the Upcoming.org data and modify it. In this example, you'll build a "browser" application that will allow the user to search for events, and add events of their own.
In this simple example, we'll demonstrate how to use the Upcoming.org API within Flex Builder 2. The application will allow the user to search for events within their Metro areas by entering some keywords, and a date range. In addition, the user will be able to add an event of their own, by specifying an event name, the date when it takes place, and a venue in one of their metro areas. Finally, the application will also retrieve the user's personal data - namely their profile photo and name, and display it.
Connecting to the Upcoming.org Web API has never been easier. After obtaining the API Key and adding the Yahoo! ASTRA Web APIs library to your project (check with the "What you need" section above if you are missing either of these steps), let's go on and import the required libraries for use in the application.
Now, let's set up a few container variables to use for retrieving data. We'll make them bindable, to ensure that the interface components can draw data from them.
Note that we set the creationComplete for the application above to init(). Now, let's define this function. The first thing we'll do in it is initialize a new UpcomingService with an API Key, and add an event listener for an event that's dispatched when an authentication token is issued. We'll also set some initial visibility values for three interface elements: the login panel (initially visible), the user info panel (initially invisible), and the "add event" dialog (initially invisible):
Now, let's define the function that's called when an authentication token is issued. Note that in it, we define three more event listeners: one that waits for results of an event search, one that waits for a list of metro areas, and one that waits for a list of venues.
Then, we request the user's metro list, and change the interface visibility settings (the login panel now disappears, and the user information panel becomes visible).
When we got the authorization token, we got some information about the user, but not all of it. To update the user with the latest information, we set an event listener waiting for the user update, and then call for a user update by id (the id has been filled in by the token authentication):
The user update event listener updates the user_photo and the user_name:
The venue, event, and metro list listeners update the respective variables:
Finally, let's include some logic for adding an event. Notice that before the add() method is called on the new event, we provide it with an event listener to check that the event addition is complete:
That event listener handles updating the status label after the event has been added:
We're almost there! We already built all the logic for communicating with the API, and now all we have left to do is to add all the necessary interface elements. Let's look at what we have here. First, there's a dataGrid with three columns: event name, event date and event venue. Notice that we are using an itemRenderer for the columns to make sure HTML text is rendered properly. The fields are bound to the appropriate fields in the variables we set up:
This is just a little beautification: a classic Upcoming.org red header, and some labels for controls:
Some inputs to search for the events:
The "Find" button calls the findEvents method with arguments retrieved from the inputs we defined above:
Here's an "Add an Event" button that brings up an "Add Event" panel and requests a venue list to display on it:
This is the login panel. It allows the user to bring up the authentication URL, retrieve the authentication frob there, and paste it back into the application:
The user info panel, which is displayed when the user is logged in, displays the user's photo and name:
Finally, here's the "Add event" panel, which allows the user to fill in event information and add it to the database
Notice that this ComboBox is populated by the venues variable:
And that's all there is to it ! We now have a working application. Of course, there's other important things we can do, like error-checking and validation, but the gist of it is all here.
View this example live in your browser.
Download the Yahoo! ASTRA Web APIs library to access full source code for this example.
This application only taps the surface of what can be done with Upcoming. Imagine complex calendar applications, event tag clouds, mashups with Yahoo! Maps, Answers and Weather, event attendance visualization apps built with charting components -- there isn't a limit to the space of great applications that can be written with Flex and Yahoo!'s Upcoming API. Now -- the ball's in your court. Build it and show it to the world!
Also see: Answers Browser example