Ryerson University Library & Archives
Ask a Librarian for Help
 
Home > Catalogue > Facebook and your WebPac

Facebook and your WebPac

Creating an application that uses the functionality of a Library Catalogue within Facebook can be challenging.  There are many limitations created by both systems and creating a program to facilitate both requires the use of workarounds that can become very complex.

With the above in mind, I will attempt to make this how-to as easy to use and implement as possible.

Implementation

I developed the application in PHP5 so this how-to will focus only on the PHP implementation.  I did this because PHP is the language that Facebook was written in and at the time of development, there was more support available for the PHP API than any other language.

Before we start

The first thing you’ll need to do is get access to a webserver that can run PHP5.  Once you have that, install the facebook developer application which allows you to create facebook apps.  I suggest reading the getting started section of http://developers.facebook.com/, and looking at some of the documentation.

The Facebook programmers have developed their own markup language called “FBML”, which is similar to HTML and XML. I also recommend a read through of the available HTML tags that can be used through FBML and how to use some of the FBML tags.

Step 1: - The Initial Creation

Once you have installed the Developer Application, click on the link “Developer” from the applications menu on the left hand side of the screen. 

This is the developer main page, where you can post your problems on the discussion board, read the newest features added to the API, and view the help documentation.

To create an application, click on the “Set Up New Application” button on the top right of the screen.  This takes you to another page, where you enter a name for your application and agree to the terms of service.  You will also see a link to optional fields; don’t worry about that right now, we will be editing them later.

Once you click the submit button, you will be taken to another page, that says “API Key Created” which shows the details of your application.

You should see this sort of box on the page:
app details
I’ll explain the details of this page:

  1. “My Library Application” is the name of the application.
  2. The Edit Settings link, allows you change the application settings
  3. The about page, is the page that users can read up on your program before installing it
  4. The API Key and Secret key are the two keys that you need to access the Facebook API.
  5. The CallBack URL is the location of your application on your server.

Now, Click on the Edit Settings link.

You will now come to a page where you can edit all the details of your application.  I will explain the fields that I used for the application, for complete information on all the fields see the Documentation.

  1. Application Name (can be changed at any time)
  2. Your contact e-mail
  3. Callback URL (location (on your server) of your application
    1. For example: http://www.MYSCHOOL.edu/facebookApp/
  4. Canvas page
    1. This is the internal link of your application; pick a short name that represents what the application does. 
  5. Under Canvas, there are two options:
    1. using FBML: (select this one) allows you to create your program right in facebook (more restrictive, but quicker loads, and looks better)
    2. using iFrame: creates a frame that your program runs in.  (Not as restrictive, but more resource intensive). 
    3. I developed the Ryerson Library Application using the FBML, and in some sections I called the <fb:iframe> tag.
    4. Select FBML.
  6. Application Type
    1. Select Website, we won’t be making a desktop application
  7. Can your app be added to facebook
    1. When you select yes, you are provided with more Installations options for your program.
  8. TOS URL
    1. This is a terms of service page that you would like users to agree to before using your program, I did not include one.
  9. Icon
    1. a little 16x16 pixel picture for your application, that will appear on the left hand side menu.

Installation Options:

  1. Post Add URL
    1. The page the user goes to once they add the application
    2. A Thank you page, or just the index page.  Use the canvas page URL here instead of the call back URL
    3. Eg: http://apps.facebook.com/MyLibraryApp/thankyoupage.html
  2. App Description
    1. Short description of your app
  3. Developer Mode
    1. Use this while testing your application, so others cannot add it (except other developers)
  4. Side Nav URL,
    1. Put the internal link to the page you want your visitors to see once they click on your application’s link.
  5. Private Installation
    1. Disables news feeds from your app, good for testing (unless, you’re trying to test news feeds!)

Fill out those fields and then click the save button, you will be taken back to your list of applications. 

The About page is pretty straight forward, so I won’t go into detail of how to use each field, the description of application, allows some HTML tags for formatting, which you can use to create links, or bold certain fields.

So now you have the framework of your application set up.  Now it is time to delve into the programming.

Step 2: Programming

I’ve created a SHELL program, for you to work in, that contains most of the functionality of the Ryerson Library Application (I removed certain elements that would only complicate the understanding of how the program works.)

Description of Files:

  1. Folder:  magpierss, program that parses RSS news feeds
  2. appinclude.php
    1. This is the file that sends the two Keys to Facebook
    2. It also checks to see if the user is logged in, if not, it takes them to the login page.
  3. dashboard.php
    1. This file contains the menu that appear along the top of the application 
  4. facebook.php, facebook_desktop.php, facebookapi_php5_restlib.php
    1. These are the files that give you access to the API, the facebook_desktop.php file is only used for standalone application.  Including it, doesn’t hurt.
  5. filter.php
    1. When facebook submits a form, it adds 4 hidden fields which disrupt the innovative catalogue from functioning properly
    2. This file retrieves the good parts and redirects the website to the catalogue
  6. help.php
    1. Help page for using the application
  7. index.php
    1. Main page, with all the functionality.  This is the first page the users see when they run our application
  8. newsfeedDigest.php
    1. Php script that uses the magpierss files to read RSS feeds
  9. newsstyle.css
    1. Style sheet, that emulates the facebook look for the news feed

Now that we know what each file does, it is time to start customizing the program for your own uses.

Open the File appinclude.php.
As I said before, this file is responsible for connecting your program to Facebook, by using the api and secret keys given to you when you first created the application.

Insert your keys in place of the existing place holders:
$appapikey = 'PUT_YOUR_API_KEY_HERE';
$appsecret = 'PUT_YOUR_SECRET_KEY_HERE';

Then, change the following URLs to your callback URL and Internal URL:
$appcallbackurl = 'http://www.YOURSERVER.com/APP_DIRECTORY/'; 
$appInternalURL = 'http://apps.facebook.com/CANVAS_PAGE_URL/';

Open the Dashboard.php File.
This file contains the navigation menu of your application.  I have included two pages here, you can add more by creating “<fb:action href=””>” tags.

The files facebook.php, facebook_deasktop.php and facebookapi_php5_restlib.php do not need to be edited; these are the API pages that send information between your program and Facebook.

Open the index.php File
This is the file that gets called when someone clicks on your application (if you have set it up correctly).  It is mostly in HTML and can be understood quite easily.  However, if you look at some of the forms, you see this:
<form action="<?= $appInternalURL ?>parseCatalogue.php" method="POST">

The php call in the form’s action returns the full address to Facebook.  Facebook requires the full address from forms.  Also when you submit this form, Facebook adds 4 other hidden fields which conflict with the way that the innovative catalogue expects to receive information.  Because of this, I had to create a work around called parseCatalogue.php, which receives all the information, and parses out the unnecessary information, sending it to the filter.php file.

index.php also contains an iframe at the bottom which connects to a file called newsfeedDigest.php, this shows the last 5 news items from an RSS FEED.

At the very bottom of the page, are two groups of FBML tags. The first, <fb:narrow>, and the second, <fb:wide>

These two tags refer to two parts of your profile, the wide part, and the narrow.  You can customize these two to display different sets of information depending where this small part of your application is being shown.

The changes in this file are all mostly regular HTML changes related to what you want the user to see, I have highlighted key ones in uppercase text.

Open Filter.php.
This file works as the go between for parseCatalogue.php and the catalogue.
You need to change the $url variable (in both the first and second if statements), from Ryerson’s catalogue location to yours.
In retrospect, I should not have duplicated my code for the POST and GET methods. Not a big deal.

The next file, newsfeedDigest.php
This is the file that receives the last 5 news items from a blog.
All you need to do here, is change the location of your RSS feed, from the Ryerson Library news feed to your own.  I created a CSS file to mimic the Facebook template, so the output resembles Facebook as much as possible.

Now open help.php
This is a help file, where you can add information about the application, and how to use its features.  For the Ryerson application, we listed the purpose of having a Facebook application, hours of operation and location.

And that is all you need to do.

Now upload all of these files to your server, and test all the functionality.

If you have any problems with getting the program set up for your catalogue, or have any comments, please don’t hesitate to email me!

Enjoy!

Links:

Graham McCarthy, July 2007