doesfacebook 0.4.3 → 0.5.0.pre

data/README.rdoc

@@ -3,8 +3,8 @@
 The Awexome Labs rails plugin for handling Facebook application credentials and authentication. 
 Also provides helpers and convenience methods for canvas applications.
 
-You may also be interested in accessing content on the Facebook Open Graph. For that, consider
-this gem's brother from the same mother, DoesOpenGraph
+You may also be interested in accessing content on Facebooks Open Graph API. For that, consider
+this gem's brother from the same mother, DoesOpenGraph[https://github.com/awexome/doesopengraph].
 
 
 == Installation
@@ -15,65 +15,86 @@ To install the gem, do the usual:
   
 If you plan on using DoesFacebook in a project with a Gemfile:
 
-  gem "doesfacebook", ">=0.3.2"
+  gem "doesfacebook"
   
-You can live on the edge, too, if you like:
+You can live on the edge, too:
 
-  gem "doesfacebook", ">=0.3.2", :git=>"git://github.com/awexome/doesfacebook.git"
+  gem "doesfacebook", :git=>"git://github.com/awexome/doesfacebook.git"
 
 
 == Configuration
 
-You configure DoesFacebook in much the same way you'll configure other Facebook integration
-helper plugins. Add a "doesfacebook.yml" file to you config/ directory with the a config for
-each environment in the following format:
+You can configure your Facebook applications for use in your Rails project by specifying them
+within the "doesfacebook.yml" file under config/
 
-  development:
+To generate a boilerplate configuration file, run the generator:
+
+  rails generate does_facebook:config
+  
+The appropriate application configuration will be loaded for each request based on the callback
+path of your application. The host of each incoming request will be compared against the callback_url
+or ssl_callback_url fields of your app. A sample configuration looks like this:
+
+  my_sweet_facebook_app:
     app_id: 1234567890
-    api_key: 1234567890abcdefghijklmnopqrsttuv
-    secret_key: 1234567890abcdefghijklmnopqrsttuv
-    canvas_name: your_canvas_name
-    callback_url: http://your.dev.server.com/and/path
+    secret_key: a1b2c3d4e5f6g7h8i9j0k1l
+    canvas_name: my_sweet_canvas_name
+    callback_url: http://your.server.com/and/path
+    ssl_callback_url: https://your.secure.server.com/and/path
+
+Top-level keys in this file are configuration names. This allows you to specify many different apps
+which can be used within any environment, provided they have different callback patterns.
+
+If you do have one app for each environment, however, naming an app after the corresponding Rails
+environment ("development","production",etc.) will provide a fallback should the request host not
+directly resolve to a callback_url
+
+The typical configuration options are as follows:
+
+* app_id: Facebook ID of your application
+* secret_key: Facebook secret key of your application (used to parse and validate Facebook requests)
+* canvas_name: The "myapp" from "http://apps.facebook.com/myapp" used frequently for link generation and redirection
+* callback_url: The server callback URL for your app. Used to identify the proper configuration which should be loaded for each request.
+* ssl_callback_url: The server callback for secure, HTTPS requests. Required for production apps. Can be different from your non-secure callback_url
 
 These parameters relate to settings in the Facebook Developers application configuration panel,
-and should be easy to copy and paste in as you need for each application.
+which you can review at https://developers.facebook.com/apps and should be easy to copy and paste
+in as you need for each application.
 
 
 == Usage
 
-To parse requests, add the following declaration to your controller:
+To parse and validate requests from Facebook, simply add the following declaration to your controller:
 
   does_facebook
 
-Now, with each incoming request, DoesFacebook will parse the signed_request_parameter against your
+Now, with each incoming request, DoesFacebook will parse the "signed_request" parameter against your
 application's keys, as described at http://developers.facebook.com/docs/authentication/signed_request
 
-This allows your application to verify requests from Facebook, properly handle Facebook POSTs via
-canvas and within page tabs.
-
-You also get helpers for your views that will make many aspects of developing on the Facebook platform
-easier:
+This allows your application to verify and properly handle requests from Facebook, as well as view any
+additional data and parameters your app is sent by Facebook, such as the current user ID, active
+Facebook page, and more.
 
-  app_id
-  => The current application's id, parsed from doesfacebook.yml
+Within your controllers which declare _does_facebook_ (or inherit from a controller which does), you
+will now have access to the following niceties:
 
-  app_callback_url
-  => The current application's callback URL, parsed from doesfacebook.yml
+* redirect_to_canvas: Generate a JS top frame redirection which keeps users inside your application's canvas as opposed to loading links only within your app's iframe
+* @fbparams: This hash will be set with all keys and values Facebook provided to you for this request (things like user id, page id, logged in status, region, locale, etc.)
 
-  app_canvas_name
-  => The current application's canvas shortname, parsed from doesfacebook.yml
+Within your views, you have access to a wealth of helpers that will make many aspects of developing
+against the Facebook platform easier:
 
-  app_canvas_url
-  => The full URL to the application canvas (e.g., http://apps.facebook.com/your_canvas_name)
+* app_id: The current application's id, parsed from doesfacebook.yml
+* app_callback_url: The current application's callback URL, parsed from doesfacebook.yml
+* app_canvas_name: The current application's canvas shortname, parsed from doesfacebook.yml
+* app_canvas_url: The full URL to the application canvas (e.g., http://apps.facebook.com/myapp)
+* url_for_canvas(url_opts={}): Like the standard url_for, but ensures the endpoint is in the Facebook canvas
+* link_to_canvas(text, url_opts={}, html_opts={}): Use as you would the regular link_to helper; generates links to the canvas and properly targets the link to "_top" frame to keep app within canvas and not break into your iframe
 
-  url_for_canvas(url_opts={})
-  => Like the standard url_for, but ensures the endpoint is in the Facebook canvas
+Other helpers and useful shortcuts being added regularly.
 
-  link_to_canvas(text, url_opts={}, html_opts={})
-  => Use as you would the regular link_to helper; generates links to the canvas and properly
-     targets the link to "_top"
 
-Other helpers and useful shortcuts being added regularly.
+Now, you are armed with the tools you need to build an app within the Facebook platform simply and quickly.
 
 
 
@@ -81,5 +102,8 @@ Other helpers and useful shortcuts being added regularly.
 
 == Copyright
 
-Copyright 2011 Awexome Labs, LLC http://awexomelabs.com
+Copyright 2011-12 Awexome Labs, LLC 
+http://awexomelabs.com
+http://facebook.com/AwexomeLabs
+http://twitter.com/awexomelabs
 

data/app/helpers/does_facebook_helper.rb

@@ -10,11 +10,6 @@ module DoesFacebookHelper
     controller.send(:facebook_config)[:app_id]
   end
   
-  # Return the API key of the current application to the view
-  def api_key
-    controller.send(:facebook_config)[:api_key]
-  end
-  
   # Return the current app callback URL
   def app_callback_url
     if request.ssl?

data/lib/doesfacebook/config.rb

@@ -6,13 +6,35 @@ module DoesFacebook
     
     protected
     
-    # Access the Facebook-specific configuration for the given environment:
+    # Load app configuration by Facebook callback path with a fallback to config
+    # defined with name matching our current environment:
     def facebook_config
-      @@facebook_config ||= HashWithIndifferentAccess.new(all_facebook_config[Rails.env])
+      app_settings = all_facebook_config.find do |app_name, settings|
+        (settings["ssl_callback_url"] || settings["callback_url"]).match(/https?:\/\/#{request.host}/)
+      end
+      if app_settings
+        app_name, app_config = app_settings
+        if app_config
+          Rails.logger.debug("  Facebook configuration for app \"#{app_name}\" loaded via request to host #{request.host}")
+          return @@facebook_config = HashWithIndifferentAccess.new(app_config)
+        end
+      end
+      
+      @@facebook_config = HashWithIndifferentAccess.new(all_facebook_config[Rails.env])
+      unless @@facebook_config.blank?
+        Rails.logger.debug("  Facebook configuration loaded for app based on environment \"#{Rails.env}\"")
+      else
+        Rails.logger.warn("  Facebook configuration could not be found. doesfacebook.yml has no app for host #{request.host}")
+        Rails.logger.warn("  Facebook configuration can be generated by running \"rails generate does_facebook:config\"")
+      end
+      
+      return @@facebook_config
     end
     
+      
     # Load configuration from YAML file for all environments:
     def all_facebook_config
+      return @@all_facebook_config if @all_facebook_config
       config_file = File.join(Rails.root, "config", "doesfacebook.yml")
       if File.exist?(config_file)
         return @@all_facebook_config ||= YAML.load(File.open( config_file ))

data/lib/doesfacebook/filters.rb

@@ -22,6 +22,8 @@ module DoesFacebook
             logger.info "  Facebook Signed Request is not Valid. Ensure request is from Facebook."
             raise "DoesFacebook: Invalid Signed Request. Ensure request is from Facebook."
           end
+        else
+          logger.info "  Facebook Signed Request cannot be verified without app configuration"
         end
       end
     end

data/lib/doesfacebook/middleware.rb

@@ -0,0 +1,23 @@
+# AWEXOME LABS
+# DoesFacebook
+#
+# Middleware - Rack adapter for POST conversion, etc.
+
+module DoesFacebook
+  class Middleware
+    
+    def initialize(app)
+      @app = app
+    end
+    
+    def call(env)
+      request = Rack::Request.new(env)
+      if request.POST["signed_request"]
+        env["REQUEST_METHOD"] = "GET"
+        Rails.logger.info("  Facebook POST request converted to GET request")
+      end
+      @app.call(env)
+    end
+    
+  end  
+end # DoesFacebook

data/lib/doesfacebook.rb

@@ -9,6 +9,9 @@ require 'doesfacebook/config'
 require 'doesfacebook/filters'
 require 'doesfacebook/controls'
 require 'doesfacebook/session'
+require 'doesfacebook/middleware'
+
+require 'generators/doesfacebook/config/config_generator'
 
 module DoesFacebook
 
@@ -17,6 +20,13 @@ module DoesFacebook
     # engine_name :doesfacebook
   end
   
+  # Create a Railtie for Rack, config injection
+  class Railtie < Rails::Railtie
+    initializer "doesfacebook.init" do |app|
+      app.middleware.use DoesFacebook::Middleware
+    end
+  end
+  
   # Return the current working version of DoesFacebook from VERSION file:
   def self.version
     @@version ||= File.open(File.join(File.dirname(__FILE__), "..", "VERSION"), "r").read

data/lib/generators/doesfacebook/config/config_generator.rb

@@ -0,0 +1,21 @@
+# AWEXOME LABS
+# DoesFacebook Config Generator
+
+require 'rails/generators'
+require 'rails/generators/named_base'
+
+module DoesFacebook
+  module Generators
+    class ConfigGenerator < ::Rails::Generators::Base
+      
+      desc "Creates a boilerplate DoesFacebook configuration file at config/doesfacebook.yml"
+      
+      source_root File.expand_path("../templates", __FILE__)
+      
+      def create_config_file
+        template "doesfacebook.yml", File.join("config","doesfacebook.yml")
+      end
+
+    end
+  end #Generators
+end #DoesFacebook

data/lib/generators/doesfacebook/config/templates/doesfacebook.yml

@@ -0,0 +1,32 @@
+# AWEXOME LABS
+# DoesFacebook Configuration File
+#
+# The appropriate application configuration will be loaded for each
+# request based on the callback path of your application. The host
+# of each incoming request will be compared against the callback_url
+# or ssl_callback_url fields of your app.
+#
+# Top-level keys in this file are configuration names. If you have one
+# app for each environment, however, naming an app after the corresponding
+# Rails environment ("development","production",etc.) will provide a
+# fallback should the request host not directly resolve to a callback_url
+#
+
+name_of_app:
+  app_id: 1234567890
+  secret_key: 1234567890abcdefghijklmnopqrsttuv
+  canvas_name: your_canvas_name
+  callback_url: http://your.dev.server.com/and/path
+  
+name_of_another_app:
+  app_id: 1234567890
+  secret_key: 1234567890abcdefghijklmnopqrsttuv
+  canvas_name: your_canvas_name
+  callback_url: http://your.dev.server.com/and/path
+  
+name_of_production_app:
+  app_id: 1234567890
+  secret_key: 1234567890abcdefghijklmnopqrsttuv
+  canvas_name: your_canvas_name
+  callback_url: http://your.server.com/and/path
+  ssl_callback_url: https://your.secure.server.com/and/path

metadata

@@ -1,86 +1,79 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: doesfacebook
-version: !ruby/object:Gem::Version 
-  prerelease: 
-  version: 0.4.3
+version: !ruby/object:Gem::Version
+  version: 0.5.0.pre
+  prerelease: 6
 platform: ruby
-authors: 
+authors:
 - mccolin
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-09-18 00:00:00 -04:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-03-13 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &2158889540 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
         version: 1.0.0
   type: :development
   prerelease: false
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
+  version_requirements: *2158889540
+- !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  requirement: &2158888940 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
         version: 1.5.1
   type: :development
   prerelease: false
-  version_requirements: *id002
+  version_requirements: *2158888940
 description: Paper-thin Facebook validation and signed request parsing Rails plugin
 email: info@awexomelabs.com
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - LICENSE
 - README.rdoc
-files: 
+files:
 - app/helpers/does_facebook_helper.rb
-- config/doesfacebook.yml.example
 - lib/doesfacebook.rb
 - lib/doesfacebook/config.rb
 - lib/doesfacebook/controls.rb
 - lib/doesfacebook/filters.rb
+- lib/doesfacebook/middleware.rb
 - lib/doesfacebook/session.rb
+- lib/generators/doesfacebook/config/config_generator.rb
+- lib/generators/doesfacebook/config/templates/doesfacebook.yml
 - LICENSE
 - README.rdoc
-has_rdoc: true
 homepage: http://awexomelabs.com/
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+  requirements:
+  - - ! '>'
+    - !ruby/object:Gem::Version
+      version: 1.3.1
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.5.2
+rubygems_version: 1.8.17
 signing_key: 
 specification_version: 3
 summary: Paper-thin Facebook validation and signed request parsing Rails plugin
 test_files: []
-

data/config/doesfacebook.yml.example

@@ -1,26 +0,0 @@
-# AWEXOME LABS
-# Beyond12
-#
-# Example Facebook Configuration File
-
-development:
-  app_id: 1234567890
-  api_key: 1234567890abcdefghijklmnopqrsttuv
-  secret_key: 1234567890abcdefghijklmnopqrsttuv
-  canvas_name: your_canvas_name
-  callback_url: http://your.dev.server.com/and/path
-  
-staging:
-  app_id: 1234567890
-  api_key: 1234567890abcdefghijklmnopqrsttuv
-  secret_key: 1234567890abcdefghijklmnopqrsttuv
-  canvas_name: your_canvas_name
-  callback_url: http://your.dev.server.com/and/path
-  
-production:
-  app_id: 1234567890
-  api_key: 1234567890abcdefghijklmnopqrsttuv
-  secret_key: 1234567890abcdefghijklmnopqrsttuv
-  canvas_name: your_canvas_name
-  callback_url: http://your.server.com/and/path
-  ssl_callback_url: https://your.secure.server.com/and/path