Advertisement

Build a Desktop Flickr Uploader with AIR

by

In this tutorial, you will build a desktop Flickr image uploader using the AS3/FlickrAPI and exporting the application as an AIR app.


Step 1: Create a New Flex Project

Start out by opening Flex Builder and creating a new project by hitting "File > New > Flex Project". Go ahead and give your project a name and location. The main thing you need to worry about here is the "Application Type", make sure that is set to "Desktop (runs in Adobe AIR)".


Step 2: Download Necessary Libraries

Before we begin programming, we need to download the libraries we'll need for this project. Those libraries include the corelib by Adobe and of course the Flickr AS3 library

You'll need to get the latest build of the Flickr AS3 API via SVN because there is a problem with the "upload" function of the released builds that hasn't been fixed yet.


Step 3: Move Libraries to Project Folder

With your libraries downloaded, we need to move them into our project folder. Unzip the "corelib" and navigate to the "com" folder inside of the "src" folder. Now open your project folder in a new window and open the "src" folder. Drag the "com" folder to your project's "src" folder.

Inside of the Flickr API folder, you'll find a similar file structure as the "corelib" folder. Drill down into the "src > com > adobe > webapis" folder and grab the "flickr" folder. Move that folder over to the project folder into this directory "src > com > adobe > webapis".

Head back to Flex Builder and refresh your Package Explorer. You should now see the libraries you downloaded showing up inside of your project folder.


Step 4: Set Up the User Interface - Part 1

We'll not only be uploading images to our Flickr account, but the Title, Tags, and a Description as well, so we'll need the proper fields.

Set your document size to 320x400. Right-click on your Flex Project Folder and select "properties". Scroll down to the Flex Compiler panel and enter the following code into the "additional compiler arguments" field, "-default-size 320 415".

Switch to Design view, open the Components panel and drag out an Image component. Make sure to give the Image component an id titled "imagePreview", set its height to 205 pixels and constrain its proportions to be 10 pixels from the left, right, and top of the view in the Layout panel.

Next, drag out two TextInput components to the stage and stack them on top of one another with a padding of 10 pixels between them constraining them both to 10 pixels from the left and right. Give the first field an ID of "imageTitle" and set the text value to "Image Title". Give the second field an id of "imageTags" and a text value of "Tags".


Step 5: Set Up the User Interface - Part 2

So far we have a preview area for our selected image, fields to enter a title and tags for our image. One more piece of data is missing, a description. Go to the Components panel and drag a Text Area component out and place it below the Tags field. Set the height to 70 pixels and constrain the width to 10 pixels from the right and left. Give the Text Area an id of "imageDesc" and text value of "Image Description".

Now all we need now is a Select button, an Upload button and a progress bar to monitor our upload progress. Go ahead and drag two buttons to the display area and a progress bar. Place the first button 10 pixels from the left and constrain it to that position. Give it an id of "selectBtn" and set its label to "Select". Place the second button 10 pixels from the right and constrain it to that position as well. Set its id to "uploadBtn" and label it "Upload". Position the progress bar in the middle of the two buttons and constrain it to the middle of the application. Let's give it an id of "pBar".

Your application should look like the image below:


Step 6: Tab Index

Switch to code view inside of Flex Builder and find the input fields you just created. The three fields you'll need are the "Title", "Tags" and "Description" fields. Click inside of each one and add this code tabIndex="n", replacing "n" with a sequential number, like so:

<mx:Image x="10" y="10" width="298" height="205" id="imagePreview"/>
<mx:TextInput x="10" y="223" id="imageTitle" width="298" text="Image Title" tabIndex="1"/>
<mx:Button x="10" y="364" label="Select" id="selectBtn" click="selectImageFile(fileToOpen)"/>
<mx:Button x="243" y="364" label="Upload" id="uploadBtn" click="uploadFile(event)"/>
<mx:ProgressBar x="91.5" y="360" width="135" id="pBar"/>
<mx:TextInput x="10" y="253" width="298" text="Tags" id="imageTags" tabIndex="2"/>
<mx:TextArea x="10" y="283" width="298" height="69" text="Image Description" id="imageDesc" tabIndex="3"/>

Step 7: Sign Up For A Flickr API Key

First, head on over to Flickr and sign up for an API key.

Flickr will ask you to name your application and give it a description.

Once you fill in the proper information and agree to the to the terms and conditions, click submit and then Flickr will direct you to a screen with your API Key and the Secret Key for your app. Keep the API Key and Secret handy, you'll need them soon.


Step 8: Create a Class to Connect to Flickr

Now let's create a new ActionScript Class that will serve as our connection to Flickr. Head back into Flex Builder and create a new ActionScript Class from the File > New menu; name it FlickrConnect.

Go ahead and paste in these "import" commands and I'll explain their purpose.

package
{	
	import flash.net.SharedObject;//needed to set system cookies
	import flash.net.URLRequest;
	import flash.net.navigateToURL;//opens the authorization window in the browser
	import mx.controls.Alert;//we'll use two alert windows in our app
	import mx.events.CloseEvent;//Detects when the alert window is closed
	
	//Import all the the Flickr API classes to make sure we have everything we need
	import com.adobe.webapis.flickr.*;
	import com.adobe.webapis.flickr.events.*;
	import com.adobe.webapis.flickr.methodgroups.*;

With this class, we're going to pass Flickr our API key and the app's secret key and in return we'll get an authentication token which we'll store as a cookie on the user's system. When our app sends the key to Flickr it will open a browser window asking the user to authenticate the application with their Flickr account, once they choose "authorize" and they return to the app they will be be greeted by an alert window asking them to click "OK" once they have authorized the app with Flickr. Doing this will then send off for the security token and set the cookie storing that token locally in order to bypass the authentication process every time the app is opened.


Step 9: Create Flickr Instance and Initialize the Service

public class FlickrConnect
{
	public var flickr:FlickrService;
	private var frob:String;
	private var flickrCookie:SharedObject = SharedObject.getLocal("FlexFlickrUploader");//store Flickr Token in a cookie
	
	public function FlickrConnect()
	{
		flickr = new FlickrService("xxxxxxxxxxxxxxxxxxxxxxxxxxxx");//enter Flickr API key
		flickr.secret = "xxxxxxxxxxxxxxxx";
		if(flickrCookie && flickrCookie.data.auth_token)//if cookie AND Auth Token exist, set token
		{
			flickr.token = flickrCookie.data.auth_token;
		}else//if not, get authentication
		{
			flickr.addEventListener(FlickrResultEvent.AUTH_GET_FROB, getFrobResponse);
			flickr.auth.getFrob();
		}
}

In the code above we start by declaring 3 variables that we'll be using in this class. The "flickr" variable is set as public because we'll reference this object from within the parent application, the other two variables are private because they are specific to this class only.

In the class constructor, initialize the flickr object by setting it equal to a "new FlickrService" and passing in your Flickr API key as a string. Underneath, set the secret key of our newly created service to the key given to you by Flickr when you applied for an API key.

Underneath our declarations, we first check to see if our system cookie exists and if an "authentication token" has been set. If both of those arguments equal true, we go ahead and set the "token" property of our flickr service equal to the authentication token stored in our cookie. If either of those arguments are not true, we continue the process of authenticating the application.

Add and event listener to the flickr service. The type is of "FlickrResultEvent" and we're listening for "AUTH_GET_FROB". Enter the function name "getFrobResponse". Start a new line and execute the "getFrob()" function of the Flickr API.


Frob

Flickr doesn't define the term "frob" in their API documentation, however a brief explanation is listed below.

A 'frob' is just a hex-encoded string that the Flickr servers hand out as part of the authorization process; a more conventional term for it would be a 'nonce'.

A more detailed definition can be found here.


Step 10: Get Frob

The function getFrob() will send our API key to Flickr and if the key is valid, Flickr will return a string to us. The frob will be passed to another function that will construct a login URL that we'll direct the user to to login into their Flickr account and give our app permission to upload photos.

private function getFrobResponse(event:FlickrResultEvent):void
{
	if(event.success)
	{
		frob = String(event.data.frob);
		var auth_url:String = flickr.getLoginURL(frob, AuthPerm.DELETE);//generates a login URL
		navigateToURL(new URLRequest(auth_url), "_blank"); //opens the browser and asks for your verification
		Alert.show("Close this window AFTER you login to Flickr", "Flickr Authorization", Alert.OK, null, onCloseAuthWindow);
	}
}

Once we get a response back from Flickr with a frob, we check to see if the response returned a "success". Once it's determined a frob was returned, we assign the data returned to a String variable, create another String variable that will be the authentication URL, and then use one of the Flickr AS3 API built in functions that will generate our login URL and assign its value to our "auth_url" string.

The next part should be familiar to anyone who's worked in Flash for a while. Use Flash's built in "navigateToURL" function to open Flickr in the browser and prompt the user to log in and give permission to our app to access their account. As part of this process we'll be asking Flickr for "DELETE" permission which is the highest access level an app can have. With that level of access, we'll be able to upload, edit, add, and delete. This is a bit overkill, but I chose to keep it at this level as a reference for your own projects.

At the same time we're being directed to Flickr's login page, our app is generating an alert window. This window will include the message "Close this window AFTER you login to Flickr". When the user has logged into Flickr and returned to the app, they will hit "OK" which will call another function that will retrieve an access token from Flickr.


Step 11: Get Access Token

public function onCloseAuthWindow(event:CloseEvent):void
{

	flickr.addEventListener(FlickrResultEvent.AUTH_GET_TOKEN, getTokenResponse);

	flickr.auth.getToken(frob);

}

This function simply asks Flickr for an access token, Flickr will see that our app (as identified by our frob) has been authorized and will return the token.


Step 12: Set Access Token and System Cookie

private function getTokenResponse(event:FlickrResultEvent):void
{
	if(event.success)
	{
		var authResult:AuthResult = AuthResult(event.data.auth);
		flickr.token = authResult.token;
		flickrCookie.data.auth_token = flickr.token;
		flickrCookie.flush();//set cookie on local computer
	}
}

The last function in our FlickrConnect class will accept the token sent from Flickr and store it in a system cookie. Start by again checking to make sure the event was successful. If we were successful in retrieving a token from Flickr, create an instance of "AuthResult" and assign it to a variable called "authResult". Set the value of the variable equaled to the "auth" value of the returned data. Set the "token" property of our FlickrService to the "token" property of our "authResult" variable.

Next, assign a property of "auth_token" to the cookie we created at the beginning of the class (flickrCookie) and equal it to the "flickr.token". All that is left is to set the cookie on our local computer, we do so by using the "flush()" function of the SharedObject in AS3.

Now that we have a class to connect to Flickr and set our authentication and permissions, we can start coding the main part of our application.


Step 13: Imports and Variables

In our main script, we'll import three classes; the class we just created, the built in Flex Alert class, and the Upload class of the Flickr AS3 API.

Of the four variables we're going to need, the first one we need to create is an instance of the FlickrConnect class we just created, name that class "flickrLogin". Create a variable called "uploader" with an instance of "Upload" and pass in the flickr instance from our FlickrConnect class. Create two more variables, both of the "File" type. One of those variables, we'll call "file", the other "fileToOpen".

import FlickrConnect;
import mx.controls.Alert;
import com.adobe.webapis.flickr.methodgroups.Upload;

private var flickrLogin:FlickrConnect = new FlickrConnect();
private var uploader:Upload = new Upload(flickrLogin.flickr);
private var file:File;
private var fileToOpen:File = File.documentsDirectory;


Step 14: Initialize and Image Select Function

Now that we have our imports and variables set up, we need to initiate our application. During the initialization process, set the progress bar (pBar) to invisible. We only want the bar to be visible when we're uploading an image.

The next function is to open the file browser for the user to select an image.

private function init():void
{
	pBar.visible = false;
}
private function selectImageFile(root:File):void 
{
	var imgFilter:FileFilter = new FileFilter("Images", "*.jpg;*.gif;*.png");
	root.browseForOpen("Open", [imgFilter]);
	root.addEventListener(Event.SELECT, fileSelected);
}


Step 15: Read File Information and Update Input fields

Create a function named "fileSelected" which will fire when the user selects an image. This function will also read that image's file name and url. Update the "Title" input field with the selected file's name and target the "Image Preview", setting it's URL to the URL of the file selected.

private function fileSelected(event:Event):void 
{
	imageTitle.text = fileToOpen.name;
	imagePreview.source = fileToOpen.url;
}


Step 16: Upload File and Track Progress

Create two more functions, one to handle the upload of the image to Flickr and the other to track its progress via the progress bar.

Name the first function "uploadFile" with a type of "MouseEvent". Inside of that function, set the variable that we created earlier, "file" to type "File" and pass in the URL of the image selected by the user. Add two listeners to that variable. The first listener will be a "DataEvent" listening for upload complete and its target function will be called "uploadCompleteHandler". The second listener will be a progress event and its target will be the function "onProgress".

Create the second function and name it "onProgress". Inside of the function set the progress bar to visible and set its source to that of "file".

private function uploadFile(event:MouseEvent):void
{
	file = new File(fileToOpen.url);
	file.addEventListener(DataEvent.UPLOAD_COMPLETE_DATA, uploadCompleteHandler);
	file.addEventListener(ProgressEvent.PROGRESS, onProgress);
	
	uploader.upload(file, imageTitle.text, imageDesc.text, imageTags.text);
}
private function onProgress(event:ProgressEvent):void
{
	pBar.visible = true;
	pBar.source = file;
}


Step 17: Upload Complete

Once the upload is complete, Flickr will send a response back to our app letting us know the upload has finished. Flickr's response back to us will be in the form of XML, we'll need to parse that XML and determine the response whether it be an "ok" or something else. All we need to know is if the response is "ok" then launch an Alert window stating that the upload succeeded or if the response if anything else, it means that the upload failed and we need to let the user know.

private function uploadCompleteHandler(event:DataEvent):void
{
	pBar.visible = false;
	trace("upload done");
	var xData:XML = new XML(event.data);
	trace(xData);
	if(xData[0].attribute("stat") == "ok"){
		Alert.show("Upload Successful", "Upload Status");
	}else {
		Alert.show("Upload Failed", "Upload Status");
	}
}


Step 18: Call Functions and Initiate Application

At this point, if you test your application nothing will happen. That's because we haven't added click functions to our buttons and more importantly, we haven't initiated our application.

Inside of your main application's code, scroll down and find the code for the buttons we created using the GUI at the beginning of this tutorial. We'll need to add "Click" handlers to each button to tell them which function to execute when they are clicked.

The select button will call selectImageFile(fileToOpen) with the variable fileToOpen passed into it.

<mx:Button x="10" y="364" label="Select" id="selectBtn" click="selectImageFile(fileToOpen)"/>

The upload button will call uploadFile(event) and will pass in an event into it.

<mx:Button x="243" y="364" label="Upload" id="uploadBtn" click="uploadFile(event)"/>

Now all we need to do is initiate our application. We do this by adding some code to the top of our file under the "WindowedApplication" element. All we need to do is add call the function init() with this applicationComplete. It should look like this:

<mx:WindowedApplication xmlns:mx="http://www.adobe.com/2006/mxml" layout="absolute" applicationComplete="init()">


Step 19: Test Your Application

Once you've finished coding your application, it's time to test it to make sure it works.

Click "debug" in Flex Builder to deploy the application.

The application will alert you to only click "OK" after you log in to Flickr and give permission to the app to access your Flickr account.


Step 20: Select An Image To Upload

After clicking "OK" you'll see your blank application waiting for input.

Click "Select" and navigate to an image on your local computer. Once selected, click "Open". You should now see a preview of the image you selected. Go ahead and give it a title and a description. Think of some tags that go along with the image and enter them into the "tags" field, separated by commas. Click "Upload".

If you were successful you should see the following screen.

Just to make sure the image uploaded successfully, head on over to your Flickr account and view the image you just uploaded.


Step 21: Export as AIR

Now that we know our app is working properly, we can export it as an AIR application. To do that, click "File > Export > Release Build". There aren't any settings on the first window that we need to change, so click "Next" and head to the next window.

Create a certificate by filling in the "Publisher Name" and "Password" fields. Browse a location to save the certificate and name it. Click "finish" and wait for your AIR app to build.


Conclusion

Your app is finished, it's working and you've exported it out for AIR. What now? Now you can expand upon this application with some more of the API functions or you can deploy as is.

Thank you for taking the time to work through this tutorial, I hope you enjoyed it. And remember... keep learning!

Advertisement