rest-graph 1.1.1 → 1.2.0

data/CHANGES

@@ -1,5 +1,38 @@
 = rest-graph changes history
 
+== rest-graph 1.2.0 -- ?
+* Add RestGraph#parse_json!
+* Add RailsController to help you integrate into Rails.
+* Simplify arguments checking and require dependency.
+* Now if there's no secret in RestGraph, sig check would always fail.
+* Now there's a Rails example.
+  http://github.com/cardinalblue/rest-graph/tree/master/example
+
+* Add error_handler option. Default behavior is raising ::RestGraph::Error.
+  You may want to pass your private controller method to do redirection.
+  Extracted from README:
+  # You may want to do redirect instead of raising exception, for example,
+  # in a Rails application, you might have this private controller method:
+  def redirect_to_authorize error = nil
+    redirect_to @rg.authorize_url(:redirect_uri => request.url)
+  end
+
+  # and you'll use that private method to do error handling:
+  def setup_rest_graph
+    @rg = RestGraph.new(:error_handler => method(:redirect_to_authorize))
+  end
+
+* Add log_handler option. Default behavior is do nothing.
+  You may want to do this in Rails:
+  RestGraph.new(:log_hanlder => lambda{ |duration, url|
+                                  Rails.logger.debug("RestGraph "         \
+                                                     "spent #{duration} " \
+                                                     "requesting #{url}")
+                                })
+
+* Add RestGraph#fql_multi to do FQL multiquery. Thanks Ethan Czahor
+  Usage: rg.fql_multi(:query1 => 'SELECT ...', :query2 => 'SELECT ...')
+
 == rest-graph 1.1.1 -- 2010-05-21
 * Add oauth realted utilites -- authorize_url and authorize!
 * Fixed a bug that in Ruby 1.8.7-, nil =~ /regexp/ equals to false.

data/README.rdoc

@@ -1,4 +1,4 @@
-= rest-graph 1.1.1
+= rest-graph 1.2.0
 by Cardinal Blue ( http://cardinalblue.com )
 
 == LINKS:
@@ -9,19 +9,22 @@ by Cardinal Blue ( http://cardinalblue.com )
 
 == DESCRIPTION:
 
- super simple facebook open graph api client
+ A super simple Facebook Open Graph API client
 
 == FEATURES:
 
-* simple graph api call
-* simple fql call
-* utility to extract access_token and check sig in cookies
+* Simple Graph API call
+* Simple FQL call
+* Utility to extract access_token and check sig in cookies
 
 == SYNOPSIS:
 
+# If you feel SYNOPSIS is so hard to understand, please read
+# {examples}[http://github.com/cardinalblue/rest-graph/tree/master/example].
+
  require 'rest-graph'
 
- # every option is optional!!
+ # Every option is optional.
  rg = RestGraph.new(:access_token => '...',
                     :graph_server => 'https://graph.facebook.com/',
                     :fql_server   => 'https://api.facebook.com/',
@@ -29,8 +32,36 @@ by Cardinal Blue ( http://cardinalblue.com )
                     :lang         => 'en-us', # this affect search
                     :auto_decode  => true,    # decode by json
                     :app_id       => '123',
-                    :secret       => '1829')
+                    :secret       => '1829',
+
+  # This handler callback is only called if auto_decode is set to true,
+  # otherwise, it's ignored.
+                    :error_handler =>
+                      lambda{ |hash| raise ::RestGraph::Error.new(hash) },
+
+  # You may want to do this in Rails to do debug logging:
+                    :log_handler =>
+                      lambda{ |duration, url|
+                        Rails.logger.debug("RestGraph "         \
+                                           "spent #{duration} " \
+                                           "requesting #{url}")
+                      })
+
+ # You may want to do redirect instead of raising exception, for example,
+ # in a Rails application, you might have this private controller method:
+ def redirect_to_authorize error = nil
+   redirect_to @rg.authorize_url(:redirect_uri => request.url)
+ end
+
+ # and you'll use that private method to do error handling:
+ def setup_rest_graph
+   @rg = RestGraph.new(:error_handler => method(:redirect_to_authorize))
+ end
 
+ # This way, you don't have to check if the token is expired or not.
+ # If the token is expired, it will automatically do authorization again.
+
+ # Other simple API call:
  rg.get('me')       # GET https://graph.facebook.com/me?access_token=...
  rg.get('4/likes')  # GET https://graph.facebook.com/4/likes?access_token=...
 
@@ -40,20 +71,28 @@ by Cardinal Blue ( http://cardinalblue.com )
  # GET https://graph.facebook.com/me?metadata=1&access_token=...
  rg.get('me', :metadata => '1')
 
- # POST https://graph.facebook.com/feed/me?message=bread%21&access_token=...
- rg.post('feed/me', :message => 'bread!')
+ # POST https://graph.facebook.com/me/feed?message=bread%21&access_token=...
+ rg.post('me/feed', :message => 'bread!')
 
  # for fully blown cookies hash
  rg = RestGraph.new(:app_id => '123', :secret => '1829')
  rg.parse_cookies!(cookies) # auto save access_token if sig checked
  rg.data['uid']             # => facebook uid
 
- # fql query, same as:
+ # FQL query, same as:
  # GET https://api.facebook.com/method/fql.query?query=
  #     SELECT+name+FROM+page+WHERE+page_id%3D%22123%22&
  #     format=json&access_token=...
  rg.fql('SELECT name FROM page WHERE page_id="123"')
 
+ # FQL multiquery, same as:
+ # GET https://api.facebook.com/method/fql.multiquery?query=
+ #     %7BSELECT+name+FROM+page+WHERE+page_id%3D%22123%22&%2C
+ #        SELECT+name+FROM+page+WHERE+page_id%3D%22456%22&%7D
+ #     format=json&access_token=...
+ rg.fql_multi(:q1 => 'SELECT name FROM page WHERE page_id="123"',
+              :q2 => 'SELECT name FROM page WHERE page_id="456"')
+
  # default setting:
  class RestGraph
    def self.default_app_id
@@ -90,7 +129,7 @@ by Cardinal Blue ( http://cardinalblue.com )
 
 == REQUIREMENTS:
 
-* tested with MRI 1.8.7 and 1.9.1
+* Tested with MRI 1.8.7 and 1.9.1
 * gem install rest-client
 * gem install json      (optional)
 * gem install json_pure (optional)

data/TODO

@@ -1,17 +1,5 @@
 = rest-graph todo list
 
-= 1.1
-* auto authorization?
-
-class AuthError < RuntimeError; end
-
-rg = RestGraph.new(:scope => 'publish_stream,read_friendlists',
-                   :error_callback => lambda{ |json| raise AuthError } )
-
-begin
-  rg.get('me')
-rescue AuthError
-  # ...
-end
-
-rg.error_callback = lambda{ |json| redirect request.url }
+= 1.2
+* more docs?
+* more examples?

data/example/rails/README

@@ -0,0 +1,4 @@
+
+Please fill config/rest-graph.yaml with your app_id, secret, and canvas to
+see if this example is working or not. This is supposed to be used in an
+iframe canvas page.

data/example/rails/Rakefile

@@ -0,0 +1,10 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require(File.join(File.dirname(__FILE__), 'config', 'boot'))
+
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+require 'tasks/rails'

data/example/rails/app/controllers/application_controller.rb

@@ -0,0 +1,20 @@
+# Filters added to this controller apply to all controllers in the application.
+# Likewise, all the methods added will be available for all controllers.
+
+class ApplicationController < ActionController::Base
+  helper :all # include all helpers, all the time
+  protect_from_forgery # See ActionController::RequestForgeryProtection for details
+
+  # Scrub sensitive parameters from your log
+  # filter_parameter_logging :password
+
+  include RestGraph::RailsController
+  before_filter :setup_iframe
+  before_filter :setup_rest_graph
+
+  def index
+    me = @rg.get('me')
+    return unless me
+    render :text => me.to_json
+  end
+end

data/example/rails/app/views/rest-graph.erb

@@ -0,0 +1,16 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html>
+  <head>
+  <script type="text/javascript">
+    window.top.location.href = '<%= @authorize_url %>'
+  </script>
+  <noscript>
+    <meta http-equiv="refresh" content="0;url=<%= h @authorize_url %>" />
+    <meta http-equiv="window-target" content="_top" />
+  </noscript>
+  </head>
+  <body>
+    <div>Please <a href="<%= h @authorize_url %>" target="_top">authorize</a> if this page is not automatically redirected.</div>
+  </body>
+</html>

data/example/rails/config/boot.rb

@@ -0,0 +1,110 @@
+# Don't change this file!
+# Configure your app in config/environment.rb and config/environments/*.rb
+
+RAILS_ROOT = "#{File.dirname(__FILE__)}/.." unless defined?(RAILS_ROOT)
+
+module Rails
+  class << self
+    def boot!
+      unless booted?
+        preinitialize
+        pick_boot.run
+      end
+    end
+
+    def booted?
+      defined? Rails::Initializer
+    end
+
+    def pick_boot
+      (vendor_rails? ? VendorBoot : GemBoot).new
+    end
+
+    def vendor_rails?
+      File.exist?("#{RAILS_ROOT}/vendor/rails")
+    end
+
+    def preinitialize
+      load(preinitializer_path) if File.exist?(preinitializer_path)
+    end
+
+    def preinitializer_path
+      "#{RAILS_ROOT}/config/preinitializer.rb"
+    end
+  end
+
+  class Boot
+    def run
+      load_initializer
+      Rails::Initializer.run(:set_load_path)
+    end
+  end
+
+  class VendorBoot < Boot
+    def load_initializer
+      require "#{RAILS_ROOT}/vendor/rails/railties/lib/initializer"
+      Rails::Initializer.run(:install_gem_spec_stubs)
+      Rails::GemDependency.add_frozen_gem_path
+    end
+  end
+
+  class GemBoot < Boot
+    def load_initializer
+      self.class.load_rubygems
+      load_rails_gem
+      require 'initializer'
+    end
+
+    def load_rails_gem
+      if version = self.class.gem_version
+        gem 'rails', version
+      else
+        gem 'rails'
+      end
+    rescue Gem::LoadError => load_error
+      $stderr.puts %(Missing the Rails #{version} gem. Please `gem install -v=#{version} rails`, update your RAILS_GEM_VERSION setting in config/environment.rb for the Rails version you do have installed, or comment out RAILS_GEM_VERSION to use the latest version installed.)
+      exit 1
+    end
+
+    class << self
+      def rubygems_version
+        Gem::RubyGemsVersion rescue nil
+      end
+
+      def gem_version
+        if defined? RAILS_GEM_VERSION
+          RAILS_GEM_VERSION
+        elsif ENV.include?('RAILS_GEM_VERSION')
+          ENV['RAILS_GEM_VERSION']
+        else
+          parse_gem_version(read_environment_rb)
+        end
+      end
+
+      def load_rubygems
+        min_version = '1.3.2'
+        require 'rubygems'
+        unless rubygems_version >= min_version
+          $stderr.puts %Q(Rails requires RubyGems >= #{min_version} (you have #{rubygems_version}). Please `gem update --system` and try again.)
+          exit 1
+        end
+
+      rescue LoadError
+        $stderr.puts %Q(Rails requires RubyGems >= #{min_version}. Please install RubyGems and try again: http://rubygems.rubyforge.org)
+        exit 1
+      end
+
+      def parse_gem_version(text)
+        $1 if text =~ /^[^#]*RAILS_GEM_VERSION\s*=\s*["']([!~<>=]*\s*[\d.]+)["']/
+      end
+
+      private
+        def read_environment_rb
+          File.read("#{RAILS_ROOT}/config/environment.rb")
+        end
+    end
+  end
+end
+
+# All that for this:
+Rails.boot!

data/example/rails/config/environment.rb

@@ -0,0 +1,43 @@
+# Be sure to restart your server when you modify this file
+
+# Specifies gem version of Rails to use when vendor/rails is not present
+RAILS_GEM_VERSION = '2.3.8' unless defined? RAILS_GEM_VERSION
+
+# Bootstrap the Rails environment, frameworks, and default configuration
+require File.join(File.dirname(__FILE__), 'boot')
+
+Rails::Initializer.run do |config|
+  # Settings in config/environments/* take precedence over those specified here.
+  # Application configuration should go into files in config/initializers
+  # -- all .rb files in that directory are automatically loaded.
+
+  # Add additional load paths for your own custom dirs
+  # config.load_paths += %W( #{RAILS_ROOT}/extras )
+
+  # Specify gems that this application depends on and have them installed with rake gems:install
+  # config.gem "bj"
+  # config.gem "hpricot", :version => '0.6', :source => "http://code.whytheluckystiff.net"
+  # config.gem "sqlite3-ruby", :lib => "sqlite3"
+  # config.gem "aws-s3", :lib => "aws/s3"
+  config.gem 'rest-graph'
+  config.gem 'rest-graph', :lib => 'rest-graph/auto_load'
+
+  # Only load the plugins named here, in the order given (default is alphabetical).
+  # :all can be used as a placeholder for all plugins not explicitly named
+  # config.plugins = [ :exception_notification, :ssl_requirement, :all ]
+
+  # Skip frameworks you're not going to use. To use Rails without a database,
+  # you must remove the Active Record framework.
+  config.frameworks -= [ :active_record, :active_resource, :action_mailer ]
+
+  # Activate observers that should always be running
+  # config.active_record.observers = :cacher, :garbage_collector, :forum_observer
+
+  # Set Time.zone default to the specified zone and make Active Record auto-convert to this zone.
+  # Run "rake -D time" for a list of tasks for finding time zone names.
+  config.time_zone = 'UTC'
+
+  # The default locale is :en and all translations from config/locales/*.rb,yml are auto loaded.
+  # config.i18n.load_path += Dir[Rails.root.join('my', 'locales', '*.{rb,yml}')]
+  # config.i18n.default_locale = :de
+end

data/example/rails/config/environments/development.rb

@@ -0,0 +1,17 @@
+# Settings specified here will take precedence over those in config/environment.rb
+
+# In the development environment your application's code is reloaded on
+# every request.  This slows down response time but is perfect for development
+# since you don't have to restart the webserver when you make code changes.
+config.cache_classes = false
+
+# Log error messages when you accidentally call methods on nil.
+config.whiny_nils = true
+
+# Show full error reports and disable caching
+config.action_controller.consider_all_requests_local = true
+config.action_view.debug_rjs                         = true
+config.action_controller.perform_caching             = false
+
+# Don't care if the mailer can't send
+config.action_mailer.raise_delivery_errors = false

data/example/rails/config/environments/production.rb

@@ -0,0 +1,28 @@
+# Settings specified here will take precedence over those in config/environment.rb
+
+# The production environment is meant for finished, "live" apps.
+# Code is not reloaded between requests
+config.cache_classes = true
+
+# Full error reports are disabled and caching is turned on
+config.action_controller.consider_all_requests_local = false
+config.action_controller.perform_caching             = true
+config.action_view.cache_template_loading            = true
+
+# See everything in the log (default is :info)
+# config.log_level = :debug
+
+# Use a different logger for distributed setups
+# config.logger = SyslogLogger.new
+
+# Use a different cache store in production
+# config.cache_store = :mem_cache_store
+
+# Enable serving of images, stylesheets, and javascripts from an asset server
+# config.action_controller.asset_host = "http://assets.example.com"
+
+# Disable delivery errors, bad email addresses will be ignored
+# config.action_mailer.raise_delivery_errors = false
+
+# Enable threaded mode
+# config.threadsafe!

data/example/rails/config/environments/test.rb

@@ -0,0 +1,28 @@
+# Settings specified here will take precedence over those in config/environment.rb
+
+# The test environment is used exclusively to run your application's
+# test suite.  You never need to work with it otherwise.  Remember that
+# your test database is "scratch space" for the test suite and is wiped
+# and recreated between test runs.  Don't rely on the data there!
+config.cache_classes = true
+
+# Log error messages when you accidentally call methods on nil.
+config.whiny_nils = true
+
+# Show full error reports and disable caching
+config.action_controller.consider_all_requests_local = true
+config.action_controller.perform_caching             = false
+config.action_view.cache_template_loading            = true
+
+# Disable request forgery protection in test environment
+config.action_controller.allow_forgery_protection    = false
+
+# Tell Action Mailer not to deliver emails to the real world.
+# The :test delivery method accumulates sent emails in the
+# ActionMailer::Base.deliveries array.
+config.action_mailer.delivery_method = :test
+
+# Use SQL instead of Active Record's schema dumper when creating the test database.
+# This is necessary if your schema can't be completely dumped by the schema dumper,
+# like if you have constraints or database-specific column types
+# config.active_record.schema_format = :sql