facebookrb

= facebookrb

Facebookrb aims to be a lightweight yet fully featured client for the {Facebook API}[http://wiki.developers.facebook.com/index.php/API], drawing on the best features from existing Ruby Facebook libraries. The functions and features are intentionally kept simple, so you can spend your time reading the official Facebook documentation rather than learning how the code works.

== Installation

gem install facebookrb

== General Usage

The easiest way is to use the middleware. Put this in your config.ru, Sinatra application, or wherever you declare middleware:

require 'facebookrb'

use FacebookRb::Middleware, :api_key => "APIKEY", :secret => "SECRET"

This will create a Facebook API client, populate it with any parameters from Facebook, and store it in the Rack env for you.

fb = env['facebook.client']

Make a call using short or long format (thanks tmm1/sinbook for the short version)

user = fb.users.getInfo('uids' => '123235345', 'fields' => ['name', 'sex', 'religion'])
user = fb.call('users.getInfo', 'uids' => '123235345', 'fields' => ['name', 'sex', 'religion'])

This call parses the JSON from Facebook and returns the resulting objects (a Hash, Array, String, or Integer depending on how complex the JSON is). The raw text of the response is also available:

fb.call(...)
fb.last_response

If you received params from Facebook, and they are {valid}[http://wiki.developers.facebook.com/index.php/Verifying_The_Signature], then you can access them:

fb.params['user']
fb['user']  # Also works

The 'session_key' param will automatically be passed forward to any API calls if available.

== Options

The options for the middleware and the client are identical, and are values you get from Facebook:

:api_key, :secret, :canvas_url

== Features

=== Facebook Connect

The library supports reading parameters from cookies, so Connect support should be there (not thoroughly tested ATM).

=== {Batching}[http://wiki.developers.facebook.com/index.php/Using_Batching_API]

results = fb.batch do 
 fb.application.getPublicInfo(...)
 fb.users.getInfo(...)
end

results[0]  # => result for first call
results[1]  # => result for second call

== Potential Features

These would all be easy to add if anyone needs support for them.

• {Base domain}[http://wiki.developers.facebook.com/index.php/Base_Domain]
• {Preload FQL}[http://wiki.developers.facebook.com/index.php/Preload_FQL]
• {Permissions API}[http://wiki.developers.facebook.com/index.php/Permissions_API]
• {Session Secret}[http://wiki.developers.facebook.com/index.php/Session_Secret]
• Converting the request method from the Facebook POST to the original HTTP method used by the client. (http://wiki.developers.facebook.com/index.php/Fb_sig_request_method)

== Acknowledgements

The code for this project was initially derived from:

• {sinbook}[http://github.com/tmm1/sinbook]
• {MiniFB}[http://github.com/appoxy/mini_fb]
• {rack-facebook}[http://github.com/carlosparamio/rack-facebook]
• The official Facebook PHP library