Facebook Rails starter kit

This gem uses the ‘hashie’ gem for easy hash access (as returned by the Facebook graph API via Koala).

In an initializer or similar “boot location” for your app facebook integration:

Facebook.app = MyCool::FacebookAppConfig.instance

You can then define an app class that implements the following API.

Note: You may wan to load these values from a yaml file, and have the yaml filename as part of your .gitignore. You might want to look at ‘facebooker2’ gem for inspiration here (fx to support multiple environments). You have to have (or create) a Facebook App that is linked to your Rails application.

class MyCool
        class FacebookAppConfig
                include Singleton

                # please change!
                def identifier
                        '219868431409649' 
                end

                # please change!
                def secret
                        '7e5699f155df01d8e52b35c01dccd627' 
                end

                # please change for staging/production
                def site_url
                        'http://localhost:3000'
                end

                # please customize (see Facebook permissions)
                # https://developers.facebook.com/docs/authentication/permissions/
                def default_permissions
            ["publish_stream", "read_stream", "email"]
          end
        end
end

The facebook.yml file in config/apis:

identifier: 219868431409649
secret: 7e5699f155df01d8e52b35c01dccd627
site_url: http://localhost:3000
default_permissions: ["publish_stream", "read_stream", "email"]
callback_path: '/home/callback'

Note that the site_url is the url of your site hosting the external Facebook app integration, fx: www.mycoolapp.com.

See the config_loader or ‘config-file-loader’ gem for a nice way to load these yaml config values into a global App object of some kind.

Configuring this would allow you to do something like:

Facebook.app.secret # => value loaded from ‘secret’ entry in facebook.yml

Facebook access controllers

The module Facebook::Access::Helper can be included in controllers that require Facebook access (via signin).

class CampaignController < ApplicationController
        include Facebook::Access::Helper

  def signup
        fb_login!
  end
end

Some of the key methods made available are:

You can access the Facebook graph API for the current (session) user.

For this to work, it requires a previous Facebook login which can be done fx via the Facebook login button (see fx ‘facebook-social_plugins’ gem). Alternatively use OAuth directly, fx by using the fb_login! method.

Note: You can use the after_authenticate_new_user(user) hook method to fx add the authenticated user to the session for the current_user or similar method.

Debugging and logging

You can set the Facebook::Starterkit.logging_on! in order to get some logging/debugging output while using the Starterkit. By default, logging is turned off. You can also turn it off using ‘Facebook::Starterkit.logging_off!

Facebook Graph API

The fb_graph method returns a class with some nice convenience methods. The graph api used is Koala::Facebook::API from the koala gem.

The me method call get_object(‘me’) on the GraphAPI and converts the returned Hash into a Hashie for easy method access (using method_missing).

The following methods are all prefixed with ‘my_’

Examples: my_name and my_first_name and so on.

fb_graph.my_username

Currently only the following post API is provided

Facebook (and alternative OmniAuth) Authentication via Devise

This module is designed to help you quickly get started with Facebook - Devise integration and possibly other OAuth providers. Please see Railscasts omniauth-part-1 and omniauth-part-2

In your ApplicationController or some other class/module included in your AuthenticationsController you can override the new_user method if you need to.

# override as needed
        def new_user
                User.new
        end

Then simply include the Facebook::Auth::Devise module in your controller.

class AuthenticationsController < InheritedResources::Base
        include Facebook::Auth::Devise

        def new_user
                Profile.new
        end
end

This module adds controller REST methods for:

The following translation keys must be defined in a locale file (or similar i18n translation):

You can easily customize this module to suit your app by overriding any of the following methods:

Mode configuration

# in your User class
class Profile
  has_many :authentications

In your console:

rails g model authentication uid:string provider:string user_id:integer

Model:

class Authentication < ActiveRecord::Base
  attr_accessible :create, :destroy, :index, :provider, :uid, :user_id

        belongs_to :user  
end

Migration:

class CreateAuthentications < ActiveRecord::Migration
  def change
    create_table :authentications do |t|
      t.integer :user_id
      t.string  :provider
      t.string  :uid # the unique userid of the User supplied by the provider
      t.string  :index
      t.string  :create
      t.string  :destroy

      t.timestamps
    end
  end
end
rake db:migrate

Facebook Route setup

In your ‘routes.rb file

match 'auth/:provider/registration' => 'registrations#create', :as => :registration

# See http://railscasts.com/episodes/235-omniauth-part-1
match 'auth/:provider/callback' => 'authentications#create'

The :provider param can be accessed in the controller via params[:provider]. Note that the method auth_provider is already defined to return this value or default to 'facebook'.

You can then use the route like this:

= link_to "Register with Facebook", registration_path('facebook')

Or perhaps like this:

haml = button_to "", registration_path('facebook'), :class => "facebook_button"

Contributing to facebook-rails-starterkit

Copyright © 2012 Kristian Mandrup. See LICENSE.txt for further details.