Views
From alfrescowiki
Back to HTTP API.
Note: The Alfresco Facebook integration is an example implementation and is unsupported.
Note: Alfresco community member, Jeff Potts, created an excellent Screencast of the integration and how it works.
Contents |
Introduction
Content-oriented Facebook Applications may now easily be developed using the Alfresco platform. This means that enterprise content management capabilities can be mixed with the social graph of Facebook.
An Alfresco Facebook Application is developed using the Web Script Framework which has been extended to support Facebook capabilities. Java, compilation and all those other hard-core development activities are not required; just scripting.
What You Need
- Some knowledge of the Facebook Developer Platform
- Some knowledge of Web Scripts
- A hosted Alfresco Server (for hosting your Facebook Application)
How to Build Hello Friends
The quickest way to learn how to build an Alfresco Facebook Application is to dive right in. We'll build the obligatory "Hello World" application, but with a friendly twist.
Become a Facebook Developer
- Visit http://developers.facebook.com/
- Follow the "Get Started" link to add the Facebook "Developer" Application
Setup a new Facebook Application
From within the Facebook "Developer" Application...
- Click on the "Set Up New Application" button
- Enter Application Name e.g. Hello Friends
- Agree to the terms of the Facebook Platform
- Expand Optional Fields
- Enter Canvas Page URL and Callback URL
A simple convention is followed when developing Alfresco Facebook Applications for specifying the above URLs. For a Canvas Page URL of <x>, the Callback URL is http[s]://<host>:<port>/alfresco/facebook/<x>/ where <host> and <port> refer to your hosted installation of Alfresco.
NOTE: Facebook requires a unique Canvas Page URL. If building this application, you may have to find a unique canvas page URL of your own.
- Use FBML
- Choose "Yes" for 'Can your application be added on Facebook?'. This presents further options.
- Enter Post-Add URL. For now, this is simply the Canvas Page URL e.g. http://apps.facebook.com/<x>
- Enter Application Description
- Tick Developer Mode - this is IMPORTANT, unless you want the world to use your app before you've finished it.
- Click Submit
At this point, a new Application has been registered with Facebook. There are three values you need to take note of:
- API Key - shown above
- Secret - shown above
- Application Id - this is trickier to get hold of - it's in the "View About Page URL" e.g. http://www.facebook.com/apps/application.php?id=7225005894
Register Application With Alfresco
It's time to tell Alfresco about our new Facebook application.
- Login to the Alfresco Web Client (of your hosted Alfresco)
- Locate the "Web Scripts" folder within the "Data Dictionary" folder
- Create the folder "com/facebook/_apps" within "Web Scripts" (if it doesn't already exist)
- Register the Application:
This is where our three Facebook application values come into play.
Create a file called app.<API Key>.js whose content is:
app.id="<Application id>"; app.secret="<Secret>";
Implement Hello Friends
"Hello Friends" is a very simple one page application. It presents a Hello message from all your Facebook friends.
Each page of your Facebook Application is implemented as a Web Script. For our simple application we'll implement a Web Script for the Canvas Page URL we registered with Facebook (in this case /facebook/alfhello/). The Web Script renders FBML (Facebook Markup Language).
- Within the "Web Scripts" folder, create the folder "org/alfresco/facebook", if it doesn't already exist
- Within org/alfresco/facebook, create the following Web Script Definition file hellofriends.post.desc.xml whose content is:
<webscript> <shortname>Hello Friends</shortname> <url>/facebook/alfhello/</url> <format default="fbml"/> <authentication>user</authentication> </webscript>
This registers the Web Script against the Facebook Canvas Page URL. Facebook always POSTS when rendering FBML. Also notice the default format is fbml, a new pre-registered Web Script format for Facebook.
- Within org/alfresco/facebook, create the following Web Script Template file hellofriends.post.fbml.ftl whose content is:
Hello from
<#list facebook.friends as friend>
<fb:name uid="${friend}"/><#if friend_has_next>, </#if>
</#list>
This simple template iterates through each of your Facebook friends and outputs their name (via FBML). Notice the use of the new root object named facebook available in all Facebook Web Scripts.
Of course, the usual Alfresco Web Script goodies are also available, so it's easy to perform content management within Facebook.
That's it. Time to test.
Execute Hello Friends
- In a new browser window, issue http://apps.facebook.com/alfhello
- Login to the Application, if required
- You should now be presented with something akin to:
Facebook Web Scripts
The Web Script Framework has been extended to support Facebook Application development.
Authentication
Facebook authentication is handled automatically by the Web Script framework. A user cannot access an Alfresco Facebook application until they have logged in. Facebook is responsible for authenticating, but once authenticated, Web Scripts execute as the Facebook user. This means the Alfresco user id is inherited from the Facebook user id (an integer). All Alfresco operations performed by that user are recorded under the Facebook user id, including 'created by' and 'modified by'.
Facebook Root Objects
A new facebook root object is available to both Javascript and Freemarker Templates within Facebook Web Scripts.
A root object allowing interaction with the Facebook Server.
- friends
- (read only) array of all Facebook friends (user ids) associated with the currently logged in user
- appFriends
- (read only) array of Facebook friends (user ids) associated with the currently logged in user and have added the currently executing Facebook application
- postUserAction(String title, String body)
- post a Mini-feed and News feed story associated with this application and user action. See Facebook publishActionOfUser
- user
- (read only) currently logged-in Facebook user id
- apiKey
- (read only) currently executing Facebook Application Api Key
- secret
- (read only) currently executing Facebook Application Secret Key
- appId
- (read only) currently executing Facebook Application id
- sessionKey
- (read only) current Facebook session key
- canvasPath
- (read only) the Canvas path entered when registering this application with Facebook e.g. alfhello/
- canvasURL
- (read only) the absolute Facebook URL to the Canvas Page of this Application e.g. http://apps.facebook.com/alfhello/
- pageURL
- (read only) the absolute Facebook URL to this application's current page e.g. http://apps.facebook.com/alfhello/invite
Note: The intention is to provide all Facebook REST API calls via the facebook root object. Contributions to this area are welcome.
Application: Alfresco Document Library
The Alfresco Document Library demonstrates a more complex real-life content-oriented Facebook application. It's essentially Facebook Photos, but for Documents. The sample application is available in the AMP file named "alfresco-fb-doclib.amp", where the complete Web Script source code is provided. This source code is now managed on Google Code.
Canvas Page
- Presents a list of documents recently added or modified by any of your friends
My Documents
- Store any type of document (of any size) organized into libraries.
- Upload of documents via a simple dialog
- View all the documents in a library
Sharing Documents
- Documents uploaded by your friends appear in your news feed
- Your friends are notified of your uploads
- Your uploads also appear in your profile page
- View uploaded documents direct from a feed
