Building a Facebook application

 

For more instructions about building Facebook applications, take a look at the Facebook Developers wiki

 

Watch and Learn!

Everything you need to know about using iFrames to create Facebook applications: facebook_demo.swf

 

Getting started:

1. ) First step is to install the Facebook Developers application in your Facebook profile. If you don't have a Facebook account, create one! As developer of the application, you're Facebook profile will be directly associated with the application. The developer application allows you to communicate with Facebook, entering the necessary data and URLs for your library application. The developer application also includes a discussion board and news feed.

 

In this example, I already have the application installed, and can access it from the applications menu at the bottom of the Facebook page.

 

 

2.) Here is what the Facebook Developers Application looks like once installed. The Developer application provides an interface for you to enter the necessary information Facebook requires for your application.  You will need to give your application a name, provide a description, and supply a callback URL

(the URL where your application resides), and a canvas URL (the Facebook application URL). But before you get to creating your application, you will need to download and set-up your Facebook library files.

 

 

 

 

 

 

3.) Before you go any further, make sure your web server supports PHP. PHP is a programming language that can be used to create web pages and applications. For more about PHP, take a look here.  PHP is free software, so most commercial web hosting services offer this option since there is no cost in providing it. In addition, PHP is widely used on the web these days (just look at Facebook!), so chances are good your server will support it. There are different versions, so if your server has the older PHP4.0 version installed, then you will need to use the older Faceboook PHP4.0 library.

 

Download the appropriate Facebook library for use in your application. A library, in this case, is a set of files designed to communicate with each other and the Facebook platform. When a website or company opens their Application Program Interface (API) to the pubilc, this is essntially what they are doing. Allowing you access to the necessary files to move your stuff into their website.  For an entire list of available libraries, consult the Developers Wiki. You can create applications for Facebook using a wide variety of programming languages and platforms. Each programming language will have its own library. The examples used in this presentation use the Facebook PHP 5.0 library. 

 

You can download the Facebook PHP 5.0 library here (Note: this is a compressed .tar folder. You will need appropriate software to unzip the folder and access the files). The Facebook PHP5.0 library will include many files, most of which are not necessary to create a simple application using the method desribed here. Install the necessary PHP files into the directory on your web server where your Facebook application will live. Look at the example image below. Don't worry about the index.php file or the tab.php file right now. We'll create those on our own. For now, just make sure you have the facebook.php, facebook_desktop.php, and facebookapi_php5_restlib.php files from the PHP library in your directory. 

 

 

 

 

If you famililiar with command line unix/linux, then you can use the following commands to download and install the necessary files

 

Extract this archive into a directory on your hosting server where you can host and run PHP code (let's call this directory MY_DIR):

$ wget 'http://developers.facebook.com/clientlibs/facebook-platform.tar.gz'
$ tar -xzvf facebook-platform.tar.gz
$ cp facebook-platform/client/facebook*.php MY_DIR

 

POST WORKSHOP Note: If you just wish to build an application as described here, you may download the five .php files described above, and as illustrated in the above image, from here. This may help make things a bit easier.  

 

 

 

Creating Your Facebook Application

4.) In addition to the PHP Facebook library files, you will need to create a PHP file with the application contents. Instead of adding code to create an entirely new web page, we are going to use an exisiting one: the library catalog! We will take the exisiting web page for the catalog and insert it into Facebook using the <fb:iframe> tag. To start we need to create a PHP file with the appropriate markup. Best practices indicate you will want to name this file index.php. The reason being is you want this file to be the default webpage for the directory. [Some servers may prefer a filename of default.php] Place the index.php in the same directory as the other PHP library files [see image above]. To start, create a new index.php file and add the code below.

 

<?php

print '<fb:iframe src="http://www.yourlibrarystuff.com" width="700" height="600" /> ';

?>

 

Replace the URL for the page you want to load to the src= attribute.

 

NOTES:

We can also specify the dimensions of the iframe using the width and height attributes.

 

5.) Once you've set-up your PHP files, you're ready to create an application. Click the +Set Up New Application button on the Facebook Developer application. You'll be asked to give your application a name and agree to the terms of service.

 

6.) Next, you need to enter the data for your application. Most importantly, we need to supply the callback URL and the canvas URL. The callback URL is the location of the directory for your index.php file.  You need to supply the complete URL for the directory, but avoid adding the file name at the end [Example: "http://www.mylibrary.com/myplugins/" insead of "http://www.mylibrary.com/myplugins/index.php"] . This will save you some headache as you try and establish the content for the user profile. The entry field for the Callback URL is found under the Basic Canvas information tab.

 

 

 

 

The field for the Canvas URL is also found on the Canvas tab. Your canvas URL can be any name you want, but it makes sense to give it the exact same name as your application. This will be the URL for your application in the Facebook website. It will also be the URL you will use to advertise and provide access to your application.

 

 

 

As the name suggests, your canvas URL acts as a blank canvas. It retrieves the content from the page you specified in your callback URL. Basically, you are taking your webpage and laying it on top of the Facebook canvas.

 

One final step in Developer is to allow users to add your application to their profile or pages. Click the check boxes on the Authentication tab. However, to take full advantage of these features, we'll need to make some adjustments (See Taking it to the next level below)

 

7.) We're almost ready. Save your changes in developer, and you will be directed to your applications admin page.  Scroll to the bottom and look for a link that says example code. This will produce a pop-up window with the necessary code for your index.php file. If you have failed to include the Callback URL or Canvas URL, you will be prompted to add this data using the Developer application before proceeding.  The example code includes some code for an example application, but what we are intersted in is the stuff at the top.

 

<?php
// Copyright 2007 Facebook Corp.  All Rights Reserved. 
// 
// Application: alatester
// File: 'index.php' 
//   This is a sample skeleton for your application. 
// 

  

  

  

  

  

  
require_once 'facebook.php';

  

  

  

  $appapikey = '76b26cff736f45deffad8edca5cdadc1';

  

  $appsecret = '358###########################84';

  

  $facebook = new Facebook($appapikey, $appsecret);

  

  $user_id = $facebook->require_login();
 // Greet the currently logged-in user!

  

  echo "<p>Hello, <fb:name uid=\"$user_id\" useyou=\"false\" />!</p>";
  // Print out at most 25 of the logged-in user's friends,
// using the friends.get API method

  

  echo "<p>Friends:";

  

  $friends = $facebook->api_client->friends_get();

  

  $friends = array_slice($friends, 0, 25);
foreach ($friends as $friend) { echo "<br>$friend";

......and so on.

 

From the example code offered by Facebook, copy and paste the code that is similar to what I've highlighted in yellow into your index.php file. Why is this important?

 

The require _once command links your index.php file with the PHP library files in the same directory. If you house the PHP library files in a different directory, make sure to adjust the relative URL accordingly.

The user_id command requires the user to log-in to use your application

The remaining code references your application key and secret. These are unique identifiers for your application. NEVER GIVE OUT your secret!  

 

Your final index.php file should look something like this:

 

<?php

require_once 'facebook.php';

 

$appapikey = '55e96fd5f18b11c3bd974c54ad6901d0';

$appsecret = '567########################3d2e';

$facebook = new Facebook($appapikey, $appsecret);

$user_id = $facebook->require_login();

 

print '<fb:iframe src="http://www.yourlibrarystuff.com" width="700" height="600" /> ';

?>

 

8.) You should be ready to go now! Type in your canvas URL in your browser, and you should be directed to your application. You'll be prompted to agree to install the application. Once inside, you should see the web page you specified in the <fb:iframe> inside a frame, surrounded by the Facebook website. 

 

Taking it to the next level

 

There are some limitations to this method. Using the <fb:iframe> method, your application will not be accessible as a tab in the user's profile, nor can the user add it to a Facebook page they administer (for example, your're a lirbarian who has created a Facebook page for your library).  If you try and add the application to your profile as a tab, you will likely receive the following error:

If you try and add it to a Facebook page, nothing will appear on the page, even though it has been installed.

 

Again, this is because the profile tabs and boxes do not support the <fb:iframe> feature. But there is an easy workaround. We can add a link to our canvas page that will appear in the user's profile tab and any boxes added to a Facebook page. This link will take them direct to our canvas page with our application.

 

Solving the Pages problem

 

First, we need to return to the Facebook Devloper application and add some HTML to the Profile Box. The box is labelled Default FBML. FBML is an acronym for Facebook Markup Language. It is Facebook's modifed version of HTML. In this case though, there is no difference between the simple HTML we will use and the FBML.  In the example below, I've added the HTML markup for a link to the canvas page. 

 

Save your changes. Now, if any Facebook user adds your application to a Facebook page, they will see a link to your application's canvas page. The image below is from a Facebook page with four different applications added: the Lumen Catalog Search, ALA Midwinter Example Application, midwala, and the Lumen Framed appplications. The first two applications use a different, more complex method to deliver the application, which allows for the application to appear directly in the boxes on the Facebook page.  The midwala and Lumen Framed applications use the <fb:iframe> method, as described above. Since we can't add the application direct to the box, we placed a link to the canvas page instead.  Users of the Lumen Framed and midwala applications will just need to make one extra click before being able to use the application in Facebook.

 

 

Solving the Profile problem

 

To add the link to a tab in the users profile, we need to do just a little more work. First, we'll create a new PHP file in the same directory as our Facebook PHP library files and our index.php file. This new file will be a very simple PHP file with the link to our canvas page. Let's call it tab.php, so we know it is the file we will use for the profile tab:

 

<?php

print '<a  href="http://apps.facebook.com/lumen_framed/">Click here to

Search Lumen!</a> ';

?>

 

Next, we'll return to the Facebook Developers application, and look for the entry fields for the Profile tab under the Users Profile menu. In the tab URL, enter

the address for the tab.php file:

 

Save your changes. Users can now access your application through a link on the tab in the user's profile.

 

We've now added links to our application that will appear in the user's profile or on a Facebook page.  For the profile, we created a separate PHP file with the link. For the boxes that appear on Facebook pages, we've actually just added the link using the Developers application. Remember: you want to link to the canvas URL, so your application is used within the Facebook website.   

 

You're ready to rock Facebook now! When you're ready, send out the canvas URL to your patrons so they can use your application in Facebook.

 

A few final words

 

This is a very basic way to set-up a Facebook application. There are many other ways to build applications for Facebook, but they require a better knowledge of PHP and more complex programming. The emphasis here is on taking already existing online content and transferring in into the Facebook platform, in as easy a fashion as possible.   As you become more comfortable working with PHP and the developers application, you may want to explore other ways of building more robust applications. As with most computer programming, there is no one way to do things, you can cater the complexity of your application and the necessary programming to your ability. 

 

For more on PHP, take a look at the W3C school tutorials. Another good source for beginners is PHP for the World Wide Web from Peachpit Press