= grafff

grafff is a small rails plugin that wraps facebook connect (with the new extended permission handling) and the new facebook graph api.

== Installation

clone the repository
git clone http://github.com/apolzin/grafff.git build the gem gem build grafff.gemspec install the gemgem (this will also install httmultiparty and all it´s dependencies if you don´t have that installed already) gem install grafff-0.0.3.gem

== Usage

in your environment.rb put Rails::Initializer.run do |config| config.gem "grafff"

you will need to create two constants FACEBOOK_APP_ID FACEBOOK_API_KEY FACEBOOK_SECRET

these can be either hashes (for international apps that require different facebook apps for different locales) or strings

if you only use one facebook app FACEBOOK_APP_ID = 'yourfacebookapplicationidhere' FACEBOOK_API_KEY = 'yourfacebookapikeyhere' FACEBOOK_SECRET = 'yourfacebooksecrethere'

if you use multiple facebook apps FACEBOOK_APP_ID = { "en-US" => 'yourfacebookapplicationidhere', "en-GB" => 'yourfacebookapplicationidhere' } FACEBOOK_API_KEY = { "en-US" => 'yourfacebookapikeyhere', "en-GB" => 'yourfacebookapikeyhere' } FACEBOOK_SECRET = { "en-US" => 'yourfacebooksecrethere', "en-GB" => 'yourfacebooksecrethere' }

if you use multiple facebook apps you will also need to have the variable @locale available to grafff which needs to hold the locale as a string. (e.g. "en-US") this can be done with a before filter for example. just make sure you use the before filter before you use the grafff before filter (this behaviour is likely to change soon because it´s pretty clumsy the way it is)

now you can use before_filter :get_facebook_user in all the controllers you want to access the facebook user

this will give you the instance variable @facebook_user which is either nil or contains a FacebookUser. See lib/facebook_user.rb for what methods are available there

examples: @facebook_user.name would give you the name and @facebook_user.picture would give you the url to the profile picture

there are also some view helpers which handle the login process for you (those will be greatly enhanced rather soon) for example if you would want to login the facebook user and ask him for the permission to see his/her email, your view would look something like this <% if @facebook_user %>

do something with your logged in facebook user

<% else %>

show the login screen with the extended permissions to the user

<%= render_login_button_extended(["email"])

<% end %>

you can also just render the javascript functions, if you want to call them yourself via a link or flash. for the login: <%= render_login_js %> this will give you this javascript function: facebook_login();

or if you want to prompt the user for additional permissions: <%= render_permission_js("publish_stream") %> this will give you a javascript function with a name like facebook_permission_permission_name so in this case facebook_permission_publish_stream()

if the user is logged in (which he/she should be) the permission function only pops up with the permission form... otherwise it would log the user in first, too

== Todo

• change the way api key and api secret and the @locale variable are handled for multiple facebook apps to something sane
• add more view helpers (e.g. helpers to individually request permissions)
• implement all the remaining graph api calls
• implement 'manual' api call

== Note on Patches/Pull Requests

• Fork the project.
• Make your feature addition or bug fix.
• Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
• Send me a pull request. Bonus points for topic branches.

== Copyright

Copyright (c) 2010 Alexander Polzin. See LICENSE for details.