Facebook Newsroom Application Framework

From Newscloud

1 Introduction
2 Screenshot
3 Code Documentation
4 How Index.php Works
5 Example Page: Home
6 Other Facebook Applications

Introduction

The Facebook Newsroom CMS framework is generic Facebook application code which can be quickly and easily installed, configured and customized for any small organization wanting to establish a sophisticated Web presence within the Facebook community. We hope this framework will drastically reduce the barrier to entry for organizations wishing to leverage Facebook.

While Facebook has Groups and Pages that are easy to set up, they are also quite limited in functionality. These features are not conducive to community-building, engagement or organizing. Until now, building a Facebook application with broader capabilities required a significant investment of $5 - $15,000 minimum. This framework provides the easiest, most customizable and economical solution for small and/or non profit organizations to run an application on Facebook.

It's essentially a start up kit for small organizations wishing to build a Facebook application without spending thousands of dollars. It's also a great starting point which can later be enhanced and extended with additional features. With just a few hours, a Web developer with basic PHP skills can launch your application. Hosting can even be obtained free for one year at Joyent (waiting list may exist for free accounts).

Since the framework is open source, it can grow over time as the development community contributes new capabilities.

Read the overview of the Facebook Newsroom CMS
Demonstration Site at Facebook
ONE/Northwest Demonstration Site
Download the code from our SourceForge project site

[edit]

Screenshot

[edit]

Code Documentation

Directory Structure

Root files

README Check out the readme.txt file for a lot of helpful set up information.

CRON newsroom.cron calls cron.php hourly to perform tasks associated with updating the newsroom stories.

INI File

The example INI file is included in the source code download:


[db]
database="newsroom"
username="your database user name"
password="your password"
hostname=""
path="/var/www/newsroom"
log="/var/log/newsroom.log"
[facebook]
fbAPIKey="facebook api key"
fbSecretKey="facebook secret key"
[crypt]
analytics="UA-#####-##"

IFRAME Server

iframe.php serves up the html source for the url argument name to be used in Facebook as an iFrame

Classes

fbApp.class.php is the application library for the newsroom. Many basic Facebook features - including some page layou - are handled here.
systemStatus.class.php manages configuration data and for the application
actions.class.php manages recording actions in the database for Facebook
feeds.class.php manages reporting actions to mini-feeds in Facebook
feedStories.class.php uses SimplePie to populate RSS feeds configured in the application e.g. the organization's RSS feed
profile.class.php updates the user's profile box in Facebook
cron.class.php mostly manages the newsroom stories, talking to the NewsCloud API and RSS feeds
newsroom.class.php manages features related to the NewsCloud newsroom
apiNewsCloud.class.php is the standard NewsCloud API library for connecting to NewsCloud.com for the newsroom
user.class.php helper functions for managing users
utilities.class.php helper functions for PHP
xml.php and xml_saxy_parser.php are used for converting XML from the NewsCloud Web Service to PHP data structures

Facebook. A copy of the PHP4/5 Facebook API Client Library. Download

Images. Directory of images used in the application.

Includes. PHP for individual pages, called by index.php based on $_GET['page'] arguments in URL e.g. home.php, about.php, invite.php, manage.php, newsroom.php

Simplepie. An easy to use class for reading RSS feeds. Learn more

Utilities. Contains the initDatabase.php script which builds out the initial database. See also newsroom_sql.txt in the root

Database Class

db.class.php is used widely throughout the NewsCloud platform to talk to our databases
dbManage.class.php provides table configuration features for initializing database tables and columns
There is a newsroom_sql.txt export in the root directory

[edit]

How Index.php Works

All traffic for the site comes in through the controller file Index.php


// Configure Facebook from settings in INI file
$init=parse_ini_file($_SERVER['DOCUMENT_ROOT'].'../newsroom.ini');
$api_key = $init['fbAPIKey'];
$secret  = $init['fbSecretKey'];
$path = $init['path'];
// Initialize the facebook client library
include_once $path.'/facebook/facebook.php';		
$fbLib = new Facebook($api_key, $secret);
// Initialize the facebook newsroom application class
require_once "classes/fbApp.class.php";
$fbApp=new fbApp($fbLib);
/* Process incoming variable requests */	
if (!$fbApp->isDatabaseConfigured())  
 // you can remove this once the database is installed
 $page='manage';
 $option='initialize';
 $forceInitialize=true; 
} else {
// Load the application settings
$fbApp->loadAppSettings();
if (isset($_GET['page'])) { 
 $page=$_GET['page'];
} else 
 $page='home';
 // which sub option for the page
 if (isset($_GET['option'])) {
  $option=$_GET['option'];
 } else 
  $option=;
  $forceInitialize=false;
  // which app pages don't require user to be loged in at Facebook
  $openPages=array('home','newsroom','about');
  if (array_search($page,$openPages)===false) {
  // require install for pages behind the firewall
  $user = $fbLib->require_install();			
 } else {
 // just check if they are logged in
 $user = $fbLib->get_loggedin_user();			
}
// set is_logged_out to true if user is unknown
$is_logged_out=!$user;
}

Then it determines which page to include:


/* begin building page response */
$code=;
switch ($page) {
default: // home
// ask them to invite their friends every 14 days
$noRecentInvite=false;
if (!$is_logged_out) { 			
$fbApp->lookupUser($fbLib->user);
$result=$fbApp->db->query("SELECT uid FROM User WHERE fbId=$fbLib->user AND lastInvite<date_sub(NOW(), INTERVAL 14  DAY);");
if ($fbApp->db->countQ($result)>0) 
$noRecentInvite=true;			
if (!$noRecentInvite)			
include('includes/home.php');
else {
$fbApp->touchInvite($fbLib->user);
include('includes/invite.php');
}
} else
include('includes/home.php');
break;
case 'manage':
include('includes/manage.php');
break;		
...

After that, it displays the page it's built:


// build the header and navigation above the constructed body
$code=$fbApp->buildStyles().$fbApp->buildHeader().$fbApp->buildNav($page,$option).'<div   id="body">'.$code.'</div><!-- end body -->';
$code.=$fbApp->buildFooter($user,$page);
$code.='<fb:google-analytics uacct="'.$fbApp->settings['appGoogleAnalytics'].'" page="'.$fbApp->appName.': '.$page.'"/>';
$fbApp->display($code);

[edit]

Example Page: Home

This is the include for constructing the home page:


// Feed Stories will read in the latest RSS feeds from the Organization
require_once ($path.'/classes/feedStories.class.php');
$fsObj=new feedStories();
// if the user is logged in, make sure we've added them to the user table as app-installed
if (!$is_logged_out) $fbApp->setInstalled($fbLib->user);
// construct the layout with styles
$leftCol='style="margin:0px;padding:0px;width:280px;float:left;"';
$midCol='style="margin:0px;padding:0px;width:35px;height:670px;float:left;background-image: url('.$fbApp->callback.'/images/midFiller.gif); background-repeat:repeat-y;"';  $rightCol='style="padding:0px;float:left;margin:10px 0px 10px 0px;"';
//start left column
$code.='<div '.$leftCol.'>';
// <fb:name uid="'.$fbApp->fbLib->user.'" useyou="false" firstnameonly="true"/>!
$code.='<div style="float:left;margin-bottom:5px;"></div>';
// display items from the CMS e.g. Welcome, Recent News
$code.=$fbApp->getState('htmlHomeWelcome');
$code.=$fbApp->getState('htmlHomeRecentNews');
// get RSS stories
$code.=$fsObj->getStories(5);
// display friends using the app
$code.=$fbApp->getState('htmlHomeFriendsUsing');
if (!$is_logged_out) $code.=$fbApp->friendsUsingApp($fbApp->fbLib->user);
 else 
$code.='You can <a href="?page=invite">invite more friends</a> by signing in to Facebook.';	
$code.='</div> <!-- end left column -->';	
//start middle column
$code.='<div '.$midCol.'>';
$code.='</div> <!-- end middle column -->';
//start right column
$code.='<div '.$rightCol.'>';
$code.='<div style="width:250px;margin:0px;padding:5px;">'.$fbApp->getState('htmlHomeWhatsNew').'</div>';
// display the latest top stories from the newsroom
require_once ($fbApp->path.'/classes/newsroom.class.php');
$nrObj=new newsroom();	
$topStories=$nrObj->buildTopStories(5);
if ($topStories<>) $code.='<div style="width:250px;margin:0px;padding:5px;"><h3>Top stories</h3>'.$topStories.'</div>';
// display an IFRAME with the Flickr content slideshow
$code.='<h3>Our photostream</h3>'.$fbApp->displayIFrame('Flickr').'<br clear="all" />';
$code.=$fbApp->displayIFrame('ChipIn').'<br clear="all" />';
$code.='</div> <!-- end right column --><br clear="all" />';

[edit]