refacebook 0.4.3 → 0.4.4

data/README.txt

@@ -8,8 +8,7 @@ ReFacebook is a facebook library and Sinatra extension.
 
 == TODO:
 
-* Need to document the code.
-* Need helpers to make life easier.
+* Need more helpers to make life easier.
 * Have a better example application with fbml, api, and all that good stuff.
 * Test with ruby 1.9, remove json dep if 1.9 since json is included.
 

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :minor: 4
 :major: 0
-:patch: 3
+:patch: 4

data/lib/refacebook/sinatra.rb

@@ -3,22 +3,44 @@ require 'refacebook'
 
 module Sinatra
   module ReFacebookHelper
+    # If in the facebook canvas returns true
     def in_canvas?
       params["fb_sig_in_canvas"].eql? "1"
     end
 
-    # Return a url prefixed with the canvas url with a path given as an argument.
+    # Return a concatenated url with the canvas url and the path
     def link_from_canvas(path="")
       path = (path.empty? || path.eql?("/")) ? "" : "/#{path}"
       "#{options.canvas_url}#{path}"
     end
 
+    # Since redirect doesn't work in the canvas since it relies
+    # on JavaScript Location field. This is a replacement which
+    # uses fbml as a means to redirect to the given url.
     def fbml_redirect(url)
       halt "<fb:redirect url=\"#{url}\" />"
     end
   end
 
   module ReFacebookRegister
+    # ReFacebook configuration done at the beginning of a Sinatra file.
+    #
+    # An exaple:
+    # <pre><code>
+    # require_facebook(:api_key =>'MY_API_KEY',
+    #                  :secret_key => 'MY_SECRET_KEY',
+    #                  :canvas_url => 'http://apps.facebook.com/canvas-page',
+    #                  :require_login => true,
+    #                  :store => store)
+    # </code></pre>
+    #
+    # :api_key - Your application's Facebook API key.
+    # :secret_key - Your application's Facebook Secret key.
+    # :canvas_url - The full path to your canvas page.
+    # :require_login - If this is set to true then the user is redirected to
+    #   the login page where she needs to authenticate.
+    # :store - This currently uses memcache-client as the session store since
+    #   Rack doesn't currently have non cookie based session stores.
     def require_facebook *args
       settings = args[0]
 

data/lib/refacebook.rb

@@ -3,17 +3,19 @@ require 'uri'
 require 'md5'
 require 'json'
 
-# ReFacebook the main store for a facebook session.
 module ReFacebook
   APIRestServer = "http://api.facebook.com/restserver.php"
   LoginUrl = "http://www.facebook.com/login.php"
 
+  # ReFacebook::Session is the main store for a facebook session.
   class Session
     attr_reader :api_key, :secret, :api
 
-    attr_accessor :user, :friends, :session_key, 
-                  :expires, :time, :profile_update_time
+    attr_reader :user, :friends, :session_key, 
+                :expires, :time, :profile_update_time
 
+    # Create a new session.
+    # api_key and secret are the Facebook API and Secret keys.
     def initialize api_key, secret
       @api_key = api_key
       @secret = secret
@@ -24,6 +26,8 @@ module ReFacebook
       end
     end
 
+    # Update the session variables based on the values that
+    # are sent in from the facebook parameters.
     def update_session_params params
       @user = params['fb_sig_user']
       @friends = params['fb_sig_friends'].split(',')
@@ -36,6 +40,10 @@ module ReFacebook
       @profile_update_time = params['fb_sig_profile_update_time']
     end
 
+    # Generate a redirect path to the default login page.
+    # :next - The page to redirect to after login.
+    # Optional:
+    #   :canvas - If this is true redirects to the canvas page.
     def get_login_url *args
       params = {}
       params['v'] = '1.0'
@@ -49,21 +57,38 @@ module ReFacebook
       LoginUrl + '?' + params.collect {|k,v| "#{k}=#{v}"}.join('&')
     end
 
-    def session_key=(session_key)
-      @session_key = @api.session_key = session_key
-    end
+    protected
+      # If the session_key changes update the API's session key as well.
+      def session_key=(session_key)
+        @session_key = @api.session_key = session_key
+      end
   end
 
+  # All <a href="http://wiki.developers.facebook.com/index.php/API">API</a> calls go 
+  # through this class. To request a method just modify the call such that . become _.
+  # If you create a session update the session_key with the session value so that
+  # all the calls become authenticated.
+  #
+  # Example calls:
+  # <pre><code>
+  #  # This is without a parameter
+  #  @api = API.new 'MY_API_KEY, 'MY_SECRET_KEY'
+  #  token = @api.auth_createToken
+  #  # This is with a parameter
+  #  app_properties = @api.admin_getAppProperties :properties => ['application_name','callback_url']
+  # </pre></code>
   class API
     attr_accessor :session_key
 
+    # Create a new API.
+    # api_key and secret are the Facebook API and Secret keys.
     def initialize api_key, secret
       @api_key = api_key
       @secret = secret
       @session_key = nil
     end
 
-    # FIXME: Implement.
+    # FIXME: This is not implemented yet. It is just a placeholder.
     def batch_run *args
       raise 
     end

metadata

@@ -54,7 +54,7 @@ test_files:
 - spec/api_spec.rb
 - examples/example.rb
 version: !ruby/object:Gem::Version 
-  version: 0.4.3
+  version: 0.4.4
 require_paths: 
 - lib
 dependencies: