You are not logged in
click here to log in
Expand All
Collapse All

A RevLet as a Facebook application


Copyright © 2009

Mark Schonewille

Economy-x-Talk

http://economy-x-talk.com


This article is obsolete because the Facebook API has changed. The purpose of this article is solely to serve as a reference and to satisfy your curiosity.


As you probably know, with the release of Revolution 4, we now have a plugin at our disposal, which allows us to display Revolution stacks in an internet browser. With the Revolution plugin, we are able to build highly interactive web pages, which makes Revolution most suitable for creating Facebook applications.



phpsite small.png


1. The main web page divided in 3 parts



This article assumes that you have at least basic knowledge of Revolution. We assume that you know how to make a useful stack and how to prepare this (if necessary) to build a standalone. It is also assumed that you already have a Facebook account and are familiar with some of the features and applications Facebook provides. You will also need a little knowledge of HTML.


A Facebook application is basically a website that communicates with the Facebook server, using special API's. These API's are provided by Facebook. Your website can consist of anything you like. You could turn your existing personal or company website into a Facebook application with hardly any modification. Such a website won't get approval, though, if it isn't using the Facebook API's. Approval is necessary to be included in the application directory, which allows people to find your application.


In this article, we create a Facebook application, which includes a RevLet and talks to the Facebook API's. We will cover the basics only, because additional features increase complexity exponentially, as will be explained after we finish our application.


Picture 1 shows a sample of the source code of a Facebook application. This is the index page, which contains the RevLet and makes calls to other source files and API's. The source code is divided into three parts. The green part contains PHP code, which connects to Facebook. The second part contains HTML code, created by the Revolution Standalone builder. The third part contains our own custom HTML code.


We will start with the RevLet, after which we will add our custom HTML code and finally we will turn the website into a Facebook application by adding the PHP code. This involves creating a RevLet in Revolution and registering an application in Facebook.



The Revlet


Let's create a simple RevLet. It doesn't matter much what kind of stack you use. Any stack will do. The stack we will be using, is shown in picture 2.The stack that we are turning into a RevLet creates random terms from a few adjectives and one noune. The terms are nonsense and hopefully turn out to be funny.


Picture 3 shows the standalone settings for a RevLet. We disabled the settings for Mac OS X, Windows and Linux and build a RevLet only. Naturally, you can build standalones for all platforms simultaneously, if you want. 


To prepare the web settings, activate the check box labelled Web, on top of the Web pane of the Standalone Application Settings window. Under General Settings, a Unique User ID number has been entered already. Don't change this.


You can choose a picture file, which is displayed while your RevLet loads. The picture must be of either PNG or JPEG format. You have to check this yourself, because the standalone builder doesn't tell you if the format is incorrect. You can also choose a top and bottom colour for the background, which is displayed while your RevLet loads. For the top, we choose white and for the bottom Facenook's main colour (approximately RGB 71,89,149).



stack in rev small.png


2. Our stack in the Revolution IDE



In the Security Settings area, we select the radio button labelled Use These Settings. We need to check only one checkbox in this area: Process. This will allow us to make the URL's work, which are displayed on top and in the bottom of the stack. If the Process checkbox is unchecked, the launch URL command won't work.


We don't select a particular minimum environment version, because it will show an error when you try to build  standalone. Make sure that the minimum environment is set to "none".


Because we don't use any platform-specific features, such as shell functions or alternative scripting languages, we can check all three checkmarks under Platforms Supported and allow for running the RevLet on other platforms. If you have an affiliate ID, it should be entered already and you can decide whether you want a promo to be displayed on the plug-in by checking the Affiliate Include checkbox. If you have no Affiliate ID, you don't need to enter anything there.


standalonebuilder small.png

3. The Standalone Application Settings window



Choose Save As Standalone Application from the File menu to build your RevLet. This should take only a few seconds. The RevLet will automatically load in your internet browser, when the build is complete. The result is shown in picture 4. 



Registering the Facebook application


We will now create the Facebook-side of your application. Facebook is a quickly changing environment. The description in this part of this article may be obsolete within months after publication, but the basics should still be the same (for a while).


Login on Facebook. Open the URL http://www.facebook.com/developers/. Grant the application access if it asks for it. In the top-right, you see a button labelled +Set Up New Application. Click on the button and enter an application name. The name of our application will be Bang (you will want to use a unique name for your own project). After entering a name, agree with the Facebook terms and click on Create Application.

browser.png

4. The Revlet running in FireFox




You should see a form as displayed in picture 5. Fill out the form.  For now, you can leave the fields in the User-Facing URLs section empty. On the left side, you see a number of tabs. You don't need to change anything on the Authentication and Profiles tabs. On the Canvas page, you need to enter a unique Canvas Page URL. For example myfirstfbappbangrr. The name of the canvas page can contain lower-case letters, dashes and underscores only. Facebook users will be able to find your application at http://apps.facebook.com/myfirstfbappbangrr.


The field Canvas Callback URL is the most important field of the entire form. Here, you enter the URL to the Facebook application directory on your own web server. You will store all files related to your Facebook application in this directory. An example of such a URL could be http://economy-x-talk.com/fb/bang/. 


Although the Bookmark URL is optional according to Facebook, it is obligatory for us RevLet makers. Without it, user will end up on the wrong Facebook page. Just use your cancvas url as bookmark URL (for example: http://apps.facebook.com/myfirstfbappbangrr). We can leave the Post-Authorize Redirect URL empty.


appsettingssml.png


5. Edit Application Settings



The options in the Canvas Settings section are also important. Make sure that the Render Method is set the IFrame. Although FBML is much simpler, Facebook will try to parse your website if you use FBML, which corrupts the embedding HTML code of the RevLet. Hence, IFrame is the only possible option. Unfortunately, this makes talking to the Facebook API much more complicated. Continue selecting the options Smart size, Full width (760px), and Quick Transitions Off.


In the Connect Tab, you only need to enter the url to the root of your Facebook directory on your web server (http://economy-x-talk.com/fb/bang/ in our example).

You can ignore the Widgets tab. In the Advanced tab, you probably want to enable the Sandbox mode and leave everything else unchanged (just check that the application type is already set to Web).


Once you have entered all necessary information correctly. click on Save Changes. An overview will appear and below the overview you will find a number of links, one of them being Download the Client Library. Click on this link to download the library. You will receive a file facebook-platform.tar.gz. Decompress the file and copy the folder Facebook-platform to a convenient place (for example your desktop or the documents folder). We will be working with the files in the folder "php" inside folder "facebook-platform". The footprints folder contains libraries that allow you to use a MySQL database. We will keep the folder, but will ignore it in this article. There is also a folder jsonwrapper. Just keep this folder in place. We will ignore it too, even though we do use it behind the scenes. 


At the bottoom of the applictation settings overview, there is a link labelled" example code". You don't need to use this code, but it can be useful to look at it. Click on the link to view the code.


Facebook's sample code consists of a very basic piece of PHP code. The important part of the code is everything above "Greet the currently logged-in user!". This part makes a link to the facebook.php library, defines a few important variables, and gives your Facebook application access to the user profile of the user who accesses your application on Facebook.


The second half of the PHP code calls a Facebook API to show some information. This part is slightly deceptive, in that it only retrieves some information from the Facebook server without actually accessing the user profile. It won't allow us to post any information to the user profile (in Facebook terms: the user's wall). So, we will forget about this part of the code.


Below the bottom of the sample code, there is a link to test your application. Don't click on it, because it won't work until you have uploaded your application to your server.


Click on Done at the bottom to close the sample code frame.


To make things a little easier for you, we have created the following alternative code for you. This is a template, which you can still use later on, when you are an experienced Facebook coder. 


First, copy the following code into a new text file. 


<?php


function fbkey () {

return 'APIKEY';

}


function fbsecret () {

return 'APPLICATIONSECRET';

}


?>


In the application settings overview on Facebook, you will find three numbers: API Key, Application Secret and Application ID. Replace the word APIKEY in the above with the key labelled API Key and replace the word APPLICATIONSECRET with the code labelled Application Secret. Save the text file in your php folder and call the new text file apikey.php. 


Now follows the alternative PHP code, which we will use instead of the Facebook sample code.


<?php

require_once 'facebook.php';

include 'apikey.php';

$appapikey = fbkey();

$appsecret = fbsecret();

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

$user_id = $facebook->require_login();

$appcallbackurl = 'http://www.facebook.com';


// If app is not added, then attempt to add

/*

try

{

if ($facebook->api_client->users_isAppAdded($user_id))

{

exit;

}

}

catch (Exception $ex)

{

$facebook->set_user(null, null);

$facebook->redirect($appcallbackurl);

}

*/


//try

{

// create the one liner when TwistAWord is played

$one_line_story_templates = array();

$one_line_story_templates[] = '{*actor*} plays TwistAWord';

// create the short story when TwistAWord is played

$short_story_templates = array();

$short_story_templates[] = array('template_title' => '{*actor*} has a favourite Comic Book Cover','template_body' => 'this is the body of a more generic short story');

// define tokens for the short story

$tokens = array(

'images' => array(

array('src'=>'http://www.twistaword.net/fb/mainwindow.jpg', 'href'=>'http://apps.facebook.com/twistaword/'),

array('src'=>'http://www.twistaword.net/fb/icon.jpg', 'href'=>'http://apps.facebook.com/twistaword/')

)

);

// deprecated but needs to be passed anyway

$full_story_template = array();

$full_story_template[] = null;

// define links

$action_links = array();

$action_links[] = array( 'text'=>'Play TwistAWord', 'href'=>'http://apps.facebook.com/twistaword/' );

// story length

$story_length = 2;

// extend the body text of the short story

$body_general = 'Buy the full version of TwistaWord at http://www.twistaword.net.';

// register

//You get this id when you call registerTemplateBundle

$template_bundle_id = $facebook->api_client->feed_registerTemplateBundle($one_line_story_templates,$short_story_templates, $full_story_template, $action_links);

// post

// this should be replaced with stream_publish as soon as possible but I will do that when I understand the FB API better

$facebook->api_client->feed_publishUserAction($template_bundle_id, $tokens , null, $body_general,$story_length);

// unregister

$facebook->api_client->feed_deactivateTemplateBundleByID($template_bundle_id);

}

//catch(Exception $e)

{

// echo $e->getMessage();

}

?>


This code is a bit of a mess, because Facebook's API lacks some flexibility. We need to define some variables, such as $full_story_template, just because the API required the variable to be passed, even though it has been deprecated and is no longer of any use.


Copy the PHP code into a new text file.


We will only discuss the one-line story template, because the short-story template is too complicated to get to work and the full-story template has been deprecated. 


To use this code, you need to make few changes. Search for the line


$one_line_story_templates[] = '{*actor*} uses an application';

// create the short story when your application is used


and change it to 


$one_line_story_templates[] = '{*actor*} uses BANG!';

// create the short story when your application is used


Of course, you can replace "BANG!" with the name of your own RevLet or anything that you feel appropriate. *actor* is part of Facebook's XFBML code, which is necessarily used with iFrame-type Facebook applications.


If you created a canvas page at a url the doesn't end with "myfirstfbappbangrr", you should replace all instances of myfirstfbappbangrr in the PHP code with your own application name.


If you want to be able to see errors, you might want to uncomment the line 


// echo $e->getMessage();


Save your text file with the PHP code in the PHP folder and call it "index.php".



The Body of the Web Page


Now add the following code to it


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xmlns:fb="http://www.facebook.com/2008/fbml">

<header>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

<script src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php" type="text/javascript"></script>

</header>


As you will probably recognise, this is the beginning of a regular HTML file. This code comes below the PHP code. If you put it above the PHP code, the Facebook API won't be able to create HTTP headers because your HTML code already did and your web page will fail with a PHP error.


The code we just added gives access to Facebook's XFBML features. This allows you to use special tags, which are parsed by Facebook when your page loads. The *actor* tag, which we have seen already, is one of them. Additionally, it allows us to add the following line, consisting of an XFBML tag, which retrieves some very limited user profile information from the Facebook server.


Now we can add a body tag, just like in all HTML files, followed by a little piece of PHP code. We use PHP, because the $user_id variable has been defined in our earlier PHP code and we can retrieve the user name directly from the Facebook API for PHP. If we use the XFBML alternative for the PHP code, it won't work, probably because we are using an IFrame.


<body>

<?php

// Greet the currently logged-in user!

echo "<p>Hello, <fb:name uid=\"$user_id\" useyou=\"false\" linked=\"false\"></fb:name>! Thanks for using BANG!</p>";

?>


Again, you can replace "BANG!" with the name of your own RevLet. This code will show a message on top of your website, saying: "Hello, John Doe! Thanks for using BANG!" (assuming that the user's name is John Doe).


Add a few lines of white space to ndex.php to indicate where we will insert the RevLet later.


Below the white space, we will add a very simple piece of code. 


<fb:share-button class="url" string="icon" href="http://apps.facebook.com/myfirstfbappbangrr"></fb:share-button>


This simple XFBML code happens to work inside an IFRAME and allows the user to post a link to our application on his wall, or to send a message to Facebook friends, which includes the link. 


Now you can add your own text to the page. We will add a few small Facebook features. These features need the PHP code, which we will add later on.


Let's add a small picture and a brief text. While you add your own code, keep in mind that a lot of additional code will cause the page to become very long, which you might want to avoid.


The HTML code looks as following.


<table width=360px style="margin: 8px;">

<tr><td><img src="economyxtalk100x100.gif" style="border: 1px #F1F1F1 solid;"></td><td style="font-family: sans-serif; font-size: 10pt; padding: 16px;"><b>Bang (Band Name Generator)</b><br>This simple widget creates absurd combinations of adjectives and nouns, which might serve as a band name. Made with <a href="www.runrev.com">Runtime Revolution</a>.</td></tr></table>


You can replace the Economy-x-Talk company logo with a picture of your own. For simplicity, we hardly use any styles and use in-line style definitions, but you can freely use style definitions in the header of the page or in a separate CSS file.


We loaded a JavaScript file at the start of the body.  We finish the body with a line that tells the Facebook API to enable the XFBML features and identifies the application with the API. 


<script type="text/javascript"> 

<?php

echo "var apikey = (\"$appapikey\");\n"

?>

FB_RequireFeatures(["XFBML"], function(){ FB.Facebook.init(apikey, "xd_receiver.htm"); }); </script>


This code is a combination of PHP and JavaScript. The Facebook documentation suggests that this can be done with the JavaScript API directly, but again this won't work in our IFrame-type application.


We can now finish the website with the closing body and html tags.


</body>

</html>


We have now arrived at the point where we can insert the RevLet in the remaining white space.


Open the file test.html in a text editor. Select all text from


<!-- Embed your revlets using code like this, to automatically guide the user to install the plugin, if it is not already installed -->


until


<!-- Plugin detection script finishes above this line -->


and copy it onto the clipboard. Now go back to file index.php and replace the white space with the copied text and save.


We need to create one more file. Just create another file and copy the following code into it:


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" >

<head>

<title>Cross-Domain Receiver Page</title

</head>

<body>

<script src="http://static.ak.facebook.com/js/api_lib/v0.4/XdCommReceiver.js?2" type="text/javascript"></script>

</body>

</html>


Save the file as xd_receiver.htm in your php folder.  If you had not copied your RevLet to the php folder yet, this is the time to do so.


Your PHP folder should now look as in picture 6.


Upload all files in the php folder to the Facebook folder on your web server. Don't forget to disable the Sandbox mode! The application should now run and show a small message on a user's wall whenever the user uses your Facebook application. The user will see his or her name and can easily publish a message on the wall of his or her account with a link to your application.



A Final Word


First of all, it must be said that the Facebook documentation is very bad. It is very scattered and the descriptions of the API's are brief, if not incomplete. Most of the API's are very difficult or impossible to use, particularly in combination with an IFrame-type application. 


folderoverviewsml.png

6. Overview of your PHP folder



The Facebook framework could be improved with regard to flexibility. Because Facebook parses your website, quite a few JavaScripts can't be used. If we tried to use a pure FMBL-type website, the embedding code for our RevLet would get corrupted as Facebook parses the code. That's why an IFrame application is the only option. It shouldn't be like this, especially for simple RevLets like Bang!, which doesn't even interact with Facebook by itself.


The Facebook library should simpy include the file xd_receiver.htm, but it doesn't. This makes not only the documentation but even the onligatory library incomplete. 


Creating your first Facebook application is more difficult than creating your first command line tool or your first iPhone appliction and is definitely much more complicated than creating your first Revolution stack, if you have no good examples and tutorials available. 


You can download the complete source of this Facebook application including the RevLet at http://economy-x-talk.com/facebook/bang/source.php.zip.


Share on FaceBook! Digg! Delicious submit to reddit
click on an icon to share this web site with your friends

copyright © 2005-2012 by Economy-x-Talk, Nijmegen, the Netherlands - no rights can be derived from this website - economy-x-talk bears no responsibility for linking and linked websites - disclaimers apply at all times