Upcoming.org Application

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.

The Application Setup

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.

<?xml version="1.0" encoding="utf-8"?> <mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" creationComplete="init()" width="854" height="670"> <mx:Script> import com.yahoo.webapis.upcoming.*; import com.yahoo.webapis.upcoming.events.*;

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.

[Bindable] public var uevents:Array = new Array(); [Bindable] public var metros:Array = new Array(); [Bindable] public var venues:Array = new Array(); [Bindable] private var myUS:UpcomingService;

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):

public function init(): void { myUS = new UpcomingService("d04007f7c8"); myUS.addEventListener(UpcomingResultEvent.GET_TOKEN, tokenLoaded); login_canvas.visible = true; user_canvas.visible = false; addevent_panel.visible = false; }

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.

public function tokenLoaded(evtObject:Object) : void { myUS.addEventListener(UpcomingResultEvent.EVENT_SEARCH, eventSearch); myUS.addEventListener(UpcomingResultEvent.METRO_GET_MY_LIST, metroList); myUS.addEventListener(UpcomingResultEvent.VENUE_GET_LIST, venueList);

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).

myUS.getMyMetroList(); login_canvas.visible = false; user_canvas.visible = true; user_canvas.y = 142;

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):

myUS.user.addEventListener(UpcomingResultEvent.USER_UPDATED, userUpdated); myUS.user.updateById(); }

The user update event listener updates the user_photo and the user_name:

public function userUpdated (evtObject:Object) : void { user_photo.source = myUS.user.photourl; user_name.text = myUS.user.name; }

The venue, event, and metro list listeners update the respective variables:

public function venueList (evtObject:Object) : void { venues = evtObject.data; } public function eventSearch (evtObject:Object) : void { uevents = evtObject.data; } public function metroList (evtObject:Object) : void { metros = evtObject.data; }

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:

public function addEvent () : void { var ev:uEvent = new uEvent(myUS); ev.name = ev_name.text; ev.venue = ev_venue.selectedItem as Venue; ev.category = new Category(myUS, 1, null, null); ev.start_date = ev_date.selectedDate; ev.personal = true; ev.addEventListener(UpcomingResultEvent.EVENT_ADDED, eventAdded); ev.add(); ev_status.text="Adding event in process..." addevent_panel.visible = false; }

That event listener handles updating the status label after the event has been added:

public function eventAdded (evtObject:Object) : void { ev_status.text="Event added successfully." } ]]> </mx:Script>

Setting Up the Application Interface

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:

<mx:DataGrid y="142" height="486" dataProvider="{uevents}" width="620" x="12"> <mx:columns> <mx:DataGridColumn headerText="Name" width="300"> <mx:itemRenderer> <mx:Component> <mx:Label htmlText="{data.name}"/> </mx:Component> </mx:itemRenderer> </mx:DataGridColumn> <mx:DataGridColumn headerText="Date" width="100"> <mx:itemRenderer> <mx:Component> <mx:Label htmlText="{data.start_date.toDateString()}"/> </mx:Component> </mx:itemRenderer> </mx:DataGridColumn> <mx:DataGridColumn headerText="Venue" width="220"> <mx:itemRenderer> <mx:Component> <mx:Label htmlText="{data.venue.name}"/> </mx:Component> </mx:itemRenderer> </mx:DataGridColumn> </mx:columns> </mx:DataGrid>

This is just a little beautification: a classic Upcoming.org red header, and some labels for controls:

<mx:Canvas y="0" height="90" backgroundColor="#c40005" borderStyle="none" borderColor="#ebe9ed" left="0" right="0"> <mx:Image x="0" y="4" source="http://upcoming.org/images/logo/upcoming_logo2.png" /> <mx:Label x="270" y="31" text="Event Browser" fontFamily="Georgia" fontSize="23" fontStyle="italic" color="#ffffff"/> </mx:Canvas> <mx:Label x="10" y="104" text="Keywords:"/> <mx:Label x="210" y="104" text="Start date:"/> <mx:Label x="384" y="104" text="End date:"/> <mx:Label x="554" y="104" text="Metro:"/>

Some inputs to search for the events:

<mx:TextInput x="72" y="102" width="120" id="keywords"/> <mx:DateField x="275" y="102" showToday="true" id="s_date"/> <mx:DateField x="443" y="102" id="e_date" showToday="true"/> <mx:ComboBox x="599" y="102" id="metros_box" dataProvider="{metros}" labelField="name" width="175"> </mx:ComboBox>

The "Find" button calls the findEvents method with arguments retrieved from the inputs we defined above:

<mx:Button x="794" y="102" label="Find" id="find" click="myUS.findEvents(keywords.text, null, NaN, null, null, (metros_box.selectedItem as Metro), null, null, s_date.selectedDate, e_date.selectedDate, null, 70, 1)" />

Here's an "Add an Event" button that brings up an "Add Event" panel and requests a venue list to display on it:

<mx:Button x="697" y="414" label="Add an Event" id="add_event" click="addevent_panel.visible = true; myUS.getVenueList(metros_box.selectedItem as Metro);"/>

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:

<mx:Canvas x="644" y="142" width="200" height="128" id="login_canvas" borderStyle="solid" borderThickness="1"> <mx:LinkButton x="43" y="10" label="Go to user login" click="navigateToURL(new URLRequest(myUS.getFrobURL()), '_blank')" /> <mx:Label x="35" y="38" text="Then paste frob here:"/> <mx:TextInput x="20" y="59" id="frobtext"/> <mx:Button x="49" y="89" label="Authenticate" id="auth" click="myUS.getToken(frobtext.text)"/> </mx:Canvas>

The user info panel, which is displayed when the user is logged in, displays the user's photo and name:

<mx:Canvas x="644" y="278" width="200" height="128" id="user_canvas" alpha="1.0" borderStyle="solid" borderThickness="1"> <mx:Image id="user_photo" horizontalCenter="0" top="12" /> <mx:Label y="85" text="Logged in as" horizontalCenter="-1" /> <mx:Label y="104" horizontalCenter="-1" id="user_name" /> </mx:Canvas>

Finally, here's the "Add event" panel, which allows the user to fill in event information and add it to the database

<mx:TitleWindow x="205" y="294" width="281" height="179" layout="absolute" id="addevent_panel" showCloseButton="true"> <mx:Label x="8" y="10" text="Event name:"/> <mx:Label x="8" y="42" text="Event venue:"/> <mx:Label x="8" y="76" text="Event date:"/> <mx:Button x="201" y="107" label="Add" click="{addEvent()}"/> <mx:TextInput x="91" y="8" id="ev_name"/>

Notice that this ComboBox is populated by the venues variable:

<mx:ComboBox y="40" id="ev_venue" selectedIndex="0" dataProvider="{venues}" labelField="name" width="160" x="91" enabled="true"> </mx:ComboBox> <mx:DateField id="ev_date" x="91" y="74" width="160" showToday="true"/> </mx:TitleWindow> <mx:Label x="644" y="455" id="ev_status" textAlign="center" width="200"/> </mx:Application>

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.

Screenshot:

View this example live in your browser.

Download the Yahoo! ASTRA Web APIs library to access full source code for this example.

Summary

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