Create your first Flex and Facebook application – Part 3: Modify and deploy as a web application

Note: This tutorial series was updated September 2011 to use the Adobe ActionScript 3 SDK for Facebook Platform, which uses OAuth 2.0. Facebook is requiring all applications to use OAuth 2.0 by October 1, 2011.

Note: In September 2011 Facebook partnered with Heroku to provide free hosting for Facebook sample apps using PHP, Ruby, Node.j, or Python. You can select any of these environments, since this tutorial does not use any server-side code.

This tutorial series steps you through the process of building and deploying either a desktop or web application that retrieves, displays, and posts Facebook data. In Part 1, you built a local Flex and Facebook desktop application with Flash Builder and the Adobe ActionScript 3 SDK for Facebook Platform. In this part, you will modify the local desktop application you built in Part 1 and deploy it as a web application on your own web server.

You are modifying an existing desktop application instead of building a web application from scratch for two reasons. One, you cannot test Facebook web applications locally; they have to be accessed on a public web server and registered with Facebook in order to work. Thus, it is much easier to first build and debug a local desktop application. Second, most of the code for the desktop and web application is the same, so it would be redundant to step through them both. Instead, you will just modify the desktop application.

Specifically, in this tutorial you will:

• Create a Flash Builder web project.
• Modify the existing desktop application to be a web application using the Facebook class instead of the FacebookDesktop class.
• Provide a seamless user login and application authorization experience using the Adobe ActionScript 3 SDK for Facebook Platform which calls methods of the Facebook JavaScript SDK.
• Create a new HTML wrapper page for the application that includes the Facebook JavaScript SDK.
• Deploy the application to a web server.
• Register the web application URL using the Facebook Developer application so it can be accessed as an external web application.
• Browse to your web application on your server and successfully log in, authorize the application, see your user information, send a status message, and log out.
• Debug the remote application using Flash Builder. 

Note: Facebook frequently changes to the site's user interface and API. This makes it difficult to keep this tutorial 100% up-to-date. Please be sure to add and read the comments at the end of this tutorial for any user interface or API modifications that might have occurred.

Make sure you have a working local desktop application and then create a web project that starts with that desktop code.

Get a starting desktop project

To complete this tutorial, you need a working desktop application as it was at the end of Part 1.

1. If you completed Part 1 (and not part 2), use your existing FacebookUserStatusAIR project.
2. If you completed Parts 1 and 2, follow the instructions in step 3 to get a starting application that matches the application at the end of Part 1.
3. If you did not complete Part 1 or you do not have a working desktop project for any reason, do the following:

• Complete the Register an application with Facebook section of Part 1.
• Download and unzip flex45_fbgraph_pt1_endproject.zip.
• Import the FXP this ZIP contains into Flash Builder. In Flash Builder, select File > Import Flash Builder Project, browse to the FXP file, and then Click Finish.
• In FacebookUserStatusAIR.mxml, replace the string YOUR APPLICATION ID HERE with the ID Facebook assigned to your application.

4. Run the application and make sure it works as it did at the end of Part 1; make sure you can log in to Facebook and then see your user information displayed.

Create a Flash Builder web project

Because you cannot convert a Flash Builder desktop project to a web project, you next need to make a new web project.

1. Select File > New > Flex Project.
2. In the New Flex Project dialog box, enter FacebookUserStatusWeb as the project name (see Figure 1).

3. Leave the default location selected or navigate to a new location where you would like your project folder created.
4. For the Application type, select Web (see Figure 1).
5. Click Finish. The project will be created and you should see a file called FacebookUserStatusWeb.mxml displayed.

Add the Adobe ActionScript 3 SDK for Facebook Platform to your project

Next, download the Adobe ActionScript 3 SDK for Facebook Platform and add it to your project.

1. In a browser, go to the Google repository for the Adobe ActionScript 3 SDK for Facebook Platform.
2. Click the Downloads tab.
3. Click the GraphAPI_Web_1_7.swc (or later) file name link for the latest version and save the file to your computer.
4. Drag this SWC file and drop it in the libs folder of your FacebookUserStatusWeb project (see Figure 2).

Note: If you want to look at the source code, download the source code zip instead (or in addition to the SWC). After unzipping it, copy the com folder and add it to the src directory of your project in Flash Builder. You can then browse the source code for the classes contained in the SWC.

Copy the desktop application code

Because most of the code for the desktop and web applications will be the same, start with the existing desktop code in your web project.

1. Return to FacebookUserStatusAIR.mxml in the FacebookUserStatusAIR project and copy all the code between the start and end WindowedApplication tags.
2. Return to FacebookUserStatusWeb.mxml in the FacebookUserStatusWeb project and paste this code between the start and end Application tags.
3. Return to the FacebookUserStatusAIR project and copy the skins and images folders.
4. Return to the FacebookUserStatusWeb project and paste these folders in the src folder.
5. Change the name of the windowedapplication1_creationCompleteHandler() function to application1_creationCompleteHandler.
6. Add a creationComplete event to the Application tag and set it equal to application1_creationCompleteHandler(event).

7. Change the Application tag's minHeight to 300 and the minWidth to 600.
8. Save the file. You will have errors in your code that you will fix in the next section.

To provide Facebook login and authorization functionality in web applications, you use the Facebook class (com.facebook.graph.Facebook) instead of the FacebookDesktop class (com.facebook.graph.FacebookDesktop). The code you write using these classes is very similar; they both have init() , login() , and logout() functions.

Change the code to use the Facebook class

In your code, change the FacebookDesktop references to Facebook.

1. In Flash Builder, select Edit > Find/Replace.
2. In the Find/Replace dialog box, enter FacebookDesktop in the Find field and Facebook in the Replace with field.
3. Click Replace All. There should be 8 matches replaced.
4. Close the Find/Replace dialog box.

Modify the logout code

The FacebookDesktop logout() method has no arguments; the Facebook class's logout() method requires one, a callback function to call when the user logs out.

1. Save the FacebookUserStatusWeb.mxml file.
2. In the Problems view, double-click the Incorrect number of arguments error. There is an error with the logout() function.
3. In a browser window, go to the Adobe ActionScript 3 SDK for Facebook Platform ASDocs and navigate to the logout() method of the com.facebook.graph.Facebook class (see Figure 3). Unlike the FacebookDesktop logout() method which has no required arguments, the Facebook logout() method has one required argument, a function to call when the Facebook logout succeeds.

4. Return to Flash Builder.
5. Pass to the Facebook logout() method a reference to a function logoutHandler.

6. Create a new protected function logoutHandler() with one argument (an Object) and no return value.

You can run the application now, but nothing will happen when you click the login button. The login() method of the Facebook class, calls a method in the Facebook JavaScript SDK, which has not been included in the wrapper page yet.

Modify the login code

You need to make several changes to the login code. The FacebookDesktop login() method has a second optional argument equal to an array of extended permissions; the optional second optional argument of the Facebook class's login() method is an object. There is also a difference in what login functionality each class provides. In addition to handling user login and application authorization, the FacebookDesktop login functionality also makes an initial Facebook API call (to the me object) to retrieve all the basic information about the user. The login functionality of the Facebook class does not make this initial call so you need to modify your code to add it.

1. In a browser window, go to the Adobe ActionScript 3 SDK for Facebook Platform ASDocs and navigate to the login() method of the com.facebook.graph.Facebook class (see Figure 4). Unlike the FacebookDesktop login() method which has a second optional argument equal to an array of extended permissions, it has a second optional argument equal to an object that contains information for modifying the login window.

2. Copy the URL listed to get more information about this object (see Figure 4) and browse to it in a new tab or window: http://developers.facebook.com/docs/reference/javascript/FB.login.
3. Locate the parameters at the bottom of the page and see that the object can contain a property that you set equal to a comma separated list of extended permissions (see Figure 5).

4. Return to Flash Builder.
5. Inside the login() function, change the second argument of the Facebook login() method from an array to an object with a property called scope (the name required by the Adobe ActionScript 3 SDK for Facebook Platform) equal to a comma-delimited list of the extended permissions.

6. Inside the if block of loginHandler(), use the Facebook api() method to call the Facebook Graph me object and specify a function getMeHandler to be the callback function.

7. Create a function getMeHandler() with two Object arguments and no return value.

8. Move the two lines of code populating nameLbl and birthdayLbl from inside loginHandler() to inside getMeHandler() .

9. In both lines of code, replace success.user with result .

The current wrapper page for the application (FacebookUserStatusWeb.html) is an HTML page that was generated automatically by Flash Builder. It contains the code to check for the correct version of Flash Player needed to run your application and embeds your application. The JavaScript Flash Player detection code is provided by the open-source SWFObject.

Note: You can learn more about SWFObject from documents on the Google Code repository and the article, Detecting Flash Player versions and embedding SWF files with SWFObject 2.

When you deploy your application as a web application, the wrapper page needs some additional functionality to provide a seamless user login experience—one in which the Facebook login and/or application authorization pages appear in pop-up windows. To provide this experience, the login functionality for your application will be handled by the Facebook JavaScript SDK. The init() , login() , and logout() methods of the Facebook class in the Adobe ActionScript 3 SDK for Facebook Platform call methods of the com.facebook.core.FacebookJSBridge.as class which in turn call methods of the Facebook JavaScript SDK.

A wrapper file is provided for you in this tutorial. It is a modifed version of an index (dynamic).html sample file located in the Embedding folder of the GraphAPI_Examples.zip which you can download from the Google code respository. In order to keep the wrapper page server-agnostic, you will use an HTML page.

1. Download and unzip new flex45_fbgraph_pt3_wrapper.zip.
2. Place the file it contains in the src directory of your project (see Figure 6).

3. Right-click index.html and select Open With > Text Editor.
   You will see includes for SWFObject and the Facebook JavaScript SDK. The name and size of the SWF and the minimum required version of the Flash Player have all been set.
4. Look at the files in the project's bin-debug folder. You should see both the old (FacebookUserStatusWeb.html) and the new (index.html) wrapper files.
5. In Flash Builder, select Project > Properties.
6. Select Flex Compiler from the list of items on the left, and then clear the check box for Generate HTML wrapper file (see Figure 7).

7. Click OK.
8. In the Overwriting Files dialog box, click OK.
9. Select Project > Clean to delete all the existing files in the bin-debug folder and have them regenerated based on your new project properties.
10. In the Clean dialog box, click OK.
11. Look again at the files in the bin-debug folder. You should see your SWF file and index.html, but not the FacebookUserStatusWeb.html wrapper file.

    If you ran the application now, the SWF file would open in the operating system's default application for viewing SWF files. You could create a run configuration in Flash Builder to launch your new index.html wrapper page instead of FacebookUserStatusWeb.html, but this would do you no good because the application must live on a publicly available web server that you specify in the application's Facebook settings to work.

In order to run and debug the web application, you must first upload it to your web server.

1. In Flash Builder, look at the files in the bin-debug folder. In order to debug the remote application, you need to upload the debug version of the SWF file, the new index.html file, and the Flex framework SWF files.
2. Create the folder(s) on your web server where you want to store the application; for example, /{yourwebserver}/facebook/userstatusweb.
3. Using an FTP client, upload the contents of your projects's bin-debug folder to the folder on your web server that you just created (see Figure 8). Although you can, you do not need to upload the images folder.
   

Note: Later in the tutorial after you are finished testing and debugging the web application, you will create and upload a release version of the SWF to replace this debug version. At that time, you can also remove the Flex framework SWF files from the server.

4. In Flash Builder, select Run > Run > Configurations.
5. In the Run Configurations dialog box, clear the Use default check box and set the URL to the appropriate folder on your web server (see Figure 9); for example, http://stallons.com/facebook/userstatusweb/.

6. Click the Run button. Your remote application should launch in a browser window.

Note: You could also just browse to the application URL directly in a browser window; for example, browse to http://stallons.com/facebook/userstatusweb/.

7. Click the login button. You will get an error message (see Figure 10). You need to register a URL for the web application using the Facebook Developer application.

Next, edit the application's properties in the Facebook Developer application so that it will work as an external web application and then browse to the application.

Add a site URL

You need to register the URL for you web application with Facebook so that Facebook will enable authentication for it.

1. Return to the Facebook Developer application (http://facebook.com/developers).
2. Click the Edit App button or the Settings link for the YourLastName User Status AIR application (see Figure 11).

3. Change the Application Name from YourLastName User Status AIR to YourLastName User Status and click the Save Changes button. For example, Stallons User Status.
4. Make sure the Basic link in the left-hand navigation is selected.
5. Click the Website option and enter a Site URL (see Figure 12) that corresponds to where you uploaded the release build of the application on your web server. For example, http://stallons.com/facebook/userstatusweb/.

6. Click the Save Changes button.

De-authorize the application

This application has already been authorized with Facebook (when you logged into it as a desktop application) so to test the web application, you need to first de-authorize it.

1. In Facebook, select Home > Account Settings and click Apps.
2. Click the x next to the YourLastName User Status appliction (see Figure 13).

3. In the Remove dialog box, click Remove.
4. In the Application Removed dialog box, click Okay.
5. Select Home > Log Out to log out from Facebook so you can test the login functionality of the web application.

You are now ready to run and debug your remote web application with Flash Builder.

1. Return to Flash Builder and click the Run button.
2. Click the login button. You should get the Facebook login page in a new window.

3. Enter your email and password and click Log In. You should get a Log into YourLastName User Status (see Figure 14).

If you were already logged in to Facebook, you would have got this dialog box directly.

4. Click Log In. You should get a request to add additional permissions (see Figure 15).

5. Click Allow. You should see your Facebook user information in the web application and can post statuses as before (see Figure 16).

6. In Flash Builder, return to FacebookUserStatusWeb.mxml and place a breakpoint inside the getMeHandler() function.
7. Debug the application.

Your application will launch in a browser window as before, but now the URL has ?debug=true appended to it; for example, http://stallons.com/facebook/userstatusweb/?debug=true. If you are already logged in to Facebook, application execution is suspended and you will automatically be returned to Flash Builder. If you are not logged in, click the login button, log in, and then return to Flash Builder.

8. In Flash Builder, expand the result variable in the variables view and look at the data returned from Facebook (see Figure 17).

9. Stop the debugger.

A normal development workflow for working with a Flex and Facebook web application is the following:

• Make changes to your code.
• Upload the bin-debug folder to your web server (or once the other files are already uploaded, just the modified SWF).
• Run/browse the application in a web browser.
• Debug the application. You can use Flash Builder to debug the Flex code. To debug the JavaScript code, you can add and display Alert boxes or HTML text. You can also use a tool to examine the network responses from Facebook (like Firebug for Firefox).
• When done with development, create a release build and upload the final SWF and SWZ files to your server.

Once you are done testing and debugging the application, you should create and upload a release version of the application SWF file. The SWF file that has been generated up to now (and stored in the bin-debug folder and uploaded to your web server) contains extra information for debugging the application during development.

1. In Flash Builder, select Project > Export Release Build.
2. Make sure your project and application are selected and then change the Export to folder field to the name of the folder that you stored your application files in on your server; for example, userstatusweb (see Figure 18).

3. Click the Finish button.
4. In the Package Explorer, locate your new folder and files (see Figure 19).

5. Upload this folder to your web server.

Note: Instead of uploading the entire folder, you can just upload the release version of FacebookUserStatusWeb.swf. The images folder is not needed; it contains some images that were compiled into the application. The index.html file is already on the server and has not been changed. The SWZ files are the signed Adobe runtime shared library files containing all the framework code. The first time a user loads a Flex application using a certain version of the SDK, the SWZ files are downloaded from the Adobe website and stored on the user's computer for future use by this application and other Flex applications using the same version of the SDK. By default, the backup or failover location of these SWZ files (in case the Adobe server is down) is set to be the folder on your web server where the SWF lives. The release version of the application uses these SWZ files, not the SWF files used by the debug version, so if you want, you can also delete the Flex framework SWF files from the server.

6. Browse to the application by running it in Flash Builder or by entering the URL directly in a browser window. You should be able to log in and log out of your application and submit status messages as before.

Where to go from here

In this tutorial, you used the Adobe ActionScript 3 SDK for Facebook Platform in conjunction with the Facebook JavaScript SDK to provide the login and authorization functionality for an external Flex and Facebook web application. You started with a local desktop application, converted it into a web application, and then uploaded it to a web server. In order for the application to work, you had to register the website URL with Facebook using the Facebook Developer application.

To deploy the application as a web application on Facebook.com, continue on to Part 4 of this tutorial series, Modify and deploy on Facebook.com.