joey 0.0.1 → 0.0.2

data/COPYING.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Waseem Ahmad
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest

@@ -1,7 +1,9 @@
+COPYING.txt
 README.md
 Rakefile
 devel.vim
 init.rb
+joey.gemspec
 lib/joey.rb
 lib/joey/affiliation.rb
 lib/joey/album.rb

data/README.md

@@ -1,3 +1,77 @@
 Joey
 ====
-Joey(<a href="http://github.com/waseem/joey">http://github.com/waseem/joey</a>) is object wrappers for nodes in the Facebook OpenGraph. It also provides wrapper for the data returned by requesting the facebook REST api. This gem depends upon Koala(<a href="http://github.com/arsduo/koala">http://github.com/arsduo/koala</a>).
+Joey(<a href="http://github.com/waseem/joey">http://github.com/waseem/joey</a>) provides object wrappers for nodes in the Facebook OpenGraph. It also provides wrappers for the data returned from facebook REST api. This gem depends upon Koala(<a href="http://github.com/arsduo/koala">http://github.com/arsduo/koala</a>).
+
+This discussion(<a href="http://groups.google.com/group/koala-users/browse_thread/thread/650be4f3377aef48">http://groups.google.com/group/koala-users/browse_thread/thread/650be4f3377aef48</a>) sums up the motivation to create Joey and what it intends to accomplish.
+
+Wrappers
+----
+
+Koala is a lightweight Ruby library which provides an interface to access Facebook Open Graph and REST API.
+
+Facebook servers return data in the form of Json or XML. When you use Koala to make requests to the Graph, it converts the returned Json into ready to be used Ruby hashes. e.g.
+
+    koala_client = Koala::Facebook::GraphAndRestAPI.new(access_token)
+    # http://graph.facebook.com/me
+    me = koala_client.get_object('me')
+    # => {"name"=>"Phuddu Bandar", "timezone"=>5.5, "gender"=>"male", "id"=>"100000654222309", "birthday"=>"12/01/1986", "last_name"=>"Bandar", "updated_time"=>"2010-01-10T16:35:06+0000", "hometown"=>{"name"=>nil, "id"=>nil}, "link"=>"http://www.facebook.com/profile.php?id=100000654222309", "email"=>"phuddu.bandar@gmail.com", "first_name"=>"Phuddu"}
+
+    me['name'] # => 'Phuddu Bandar'
+    me['gender'] # => 'male'
+    me['hometown']['name'] # => nil
+
+Above when tried with joey returns a Joey::User object. We can access different information associated with a user using accessor methods instead of hash keys.
+
+    koala_client = Koala::Facebook::GraphAndRestAPI.new(access_token)
+    # http://graph.facebook.com/me
+    me = koala_client.me
+    # => <#Joey::User about=nil about_me=nil activities=nil birthday="12/01/1986" birthday_date=nil books=nil email="phuddu.bandar@gmail.com" first_name="Phuddu" gender="male" id="100000654222309" interests=nil is_app_user=nil is_blocked=nil last_name="Bandar" link="http://www.facebook.com/profile.php?id=100000654222309" locale=nil meeting_for=nil meeting_sex=nil middle_name=nil movies=nil music=nil name="Phuddu Bandar" notes_count=nil pic=nil pic_big=nil pic_big_with_logo=nil pic_small=nil pic_small_with_logo=nil pic_square=nil pic_square_with_logo=nil pic_with_logo=nil political=nil profile_blurb=nil profile_update_time=nil profile_url=nil quotes=nil relationship_status=nil religion=nil sex=nil significant_other_id=nil timezone=5.5 tv=nil uid=nil updated_time="2010-01-10T16:35:06+0000" username=nil verified=nil wall_count=nil website=nil>
+
+    me.name # => 'Phuddu Bandar'
+    me.gender # => 'male'
+    me.hometown.name # => nil
+
+
+The main advantage of creating wrapper classes for different nodes in the Graph is that one can add custom methods to different objects. e.g.
+
+In Open Graph there is no method to know if a user has given some particular extended permission to your application. However in old REST api there is <a href="http://developers.facebook.com/docs/reference/rest/users.hasAppPermission">users.hasAppPermission</a> for the same.
+
+If we use plain Koala, we can implement it in following way:
+
+    !koala_client.rest_call('users.hasAppPermission', :ext_perm => 'email').zero? # => true or false
+
+In Joey, call to users.hasAppPermission is sheilded behind a Joey::User#has_app_permission?(ext_perm)
+
+    me = koala_client.me
+    me.has_app_permission?(:email) # => true or false
+
+A more complex use case arises when someone intends to add application specific methods to different nodes. e.g.
+
+An application intends to know if a user has given his proxy email while giving the email extended permission. One can include a module with custom methods.
+
+    module FacebookUser
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+      end
+
+      def has_proxy_email?
+        if self.has_app_permission?(:email)
+          return self.email =~ /@proxymail\.facebook\.com/
+        else
+          return true
+        end
+      end
+    end
+
+and somewhere when you intialize your application like 'config/initializers/joey_patch.rb' in Rails
+
+    Joey::User.send(:include, FacebookUser)
+
+Now one can do
+
+    me = koala_client.me
+    me.has_proxy_email? # => true or false

data/joey.gemspec

@@ -2,15 +2,15 @@
 
 Gem::Specification.new do |s|
   s.name = %q{joey}
-  s.version = "0.0.1"
+  s.version = "0.0.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Waseem Ahmad"]
-  s.date = %q{2010-06-16}
+  s.date = %q{2010-06-22}
   s.description = %q{Object wrappers for nodes in the Facebook OpenGraph}
   s.email = %q{talk.to.waseem@gmail.com}
   s.extra_rdoc_files = ["README.md", "lib/joey.rb", "lib/joey/affiliation.rb", "lib/joey/album.rb", "lib/joey/education.rb", "lib/joey/education_history.rb", "lib/joey/fetching_array.rb", "lib/joey/hs_info.rb", "lib/joey/location.rb", "lib/joey/model.rb", "lib/joey/page.rb", "lib/joey/parser_helpers.rb", "lib/joey/photo.rb", "lib/joey/profile.rb", "lib/joey/relative.rb", "lib/joey/rest_api.rb", "lib/joey/status.rb", "lib/joey/television.rb", "lib/joey/user.rb", "lib/joey/version.rb", "lib/joey/work.rb", "lib/joey/work_history.rb"]
-  s.files = ["README.md", "Rakefile", "devel.vim", "init.rb", "lib/joey.rb", "lib/joey/affiliation.rb", "lib/joey/album.rb", "lib/joey/education.rb", "lib/joey/education_history.rb", "lib/joey/fetching_array.rb", "lib/joey/hs_info.rb", "lib/joey/location.rb", "lib/joey/model.rb", "lib/joey/page.rb", "lib/joey/parser_helpers.rb", "lib/joey/photo.rb", "lib/joey/profile.rb", "lib/joey/relative.rb", "lib/joey/rest_api.rb", "lib/joey/status.rb", "lib/joey/television.rb", "lib/joey/user.rb", "lib/joey/version.rb", "lib/joey/work.rb", "lib/joey/work_history.rb", "Manifest", "joey.gemspec"]
+  s.files = ["COPYING.txt", "README.md", "Rakefile", "devel.vim", "init.rb", "joey.gemspec", "lib/joey.rb", "lib/joey/affiliation.rb", "lib/joey/album.rb", "lib/joey/education.rb", "lib/joey/education_history.rb", "lib/joey/fetching_array.rb", "lib/joey/hs_info.rb", "lib/joey/location.rb", "lib/joey/model.rb", "lib/joey/page.rb", "lib/joey/parser_helpers.rb", "lib/joey/photo.rb", "lib/joey/profile.rb", "lib/joey/relative.rb", "lib/joey/rest_api.rb", "lib/joey/status.rb", "lib/joey/television.rb", "lib/joey/user.rb", "lib/joey/version.rb", "lib/joey/work.rb", "lib/joey/work_history.rb", "Manifest"]
   s.homepage = %q{http://github.com/waseem/joey}
   s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Joey", "--main", "README.md"]
   s.require_paths = ["lib"]

data/lib/joey/rest_api.rb

@@ -10,10 +10,12 @@ module Joey
     module ClassMethods
     end
 
+    # return the currently connected user
     def me
       get_and_map('me', Joey::User)
     end
 
+    # revoke an extended permissions granted by current connected user
     def revoke_app_permission(ext_perm)
       # no need to boolianize. It returns true/false.
       self.rest_call("auth.revokeExtendedPermission", :perm => ext_perm.to_s)
@@ -33,6 +35,7 @@ module Joey
       map_data(data,klass)
     end
 
+    # map the returned data to a node class
     def map_data(data, klass = nil)
       raise_error_if_necessary(data)
       hash_or_array = extract_hash_or_array(data, klass)

data/lib/joey/user.rb

@@ -2,12 +2,13 @@ module Joey
   class User < Profile
     include ParserHelpers
     
-    define_properties :first_name, :last_name, :middle_name, :link, :about, :about_me, :birthday, :gender,
+    # New Graph API has gender while old REST api has sex. I don't know why facebook does these kind of things.
+    define_properties :first_name, :last_name, :middle_name, :link, :about, :about_me, :birthday, :gender, :sex,
           :email, :website, :timezone, :updated_time, :verified, :religion, :political
     define_properties :pic_small, :pic_big, :pic_square, :pic, :pic_big_with_logo, :pic_small_with_logo,
           :pic_square_with_logo, :pic_with_logo
     define_properties :is_app_user, :books, :username, :significant_other_id, :meeting_for, :tv, :meeting_sex, :relationship_status
-    define_properties :wall_count, :uid, :movies, :sex, :birthday_date, :notes_count, :activities, :profile_blurb, :music, :music, :locale
+    define_properties :wall_count, :uid, :movies, :birthday_date, :notes_count, :activities, :profile_blurb, :music, :music, :locale
     define_properties :profile_url, :profile_update_time, :interests, :is_blocked, :quotes
     
     def self.recognize?(hash)
@@ -29,18 +30,22 @@ module Joey
     hash_populating_accessor :family, "Relative"
 
     #has_association :activities,"Activity"
-    has_association :friends, "User"
     #has_association :interests, "Interest"
     #has_association :music, "Music"
     #has_association :books, "Book"
     #has_association :movies, "Movie"
     has_association :television, "Television"
     has_association :likes, "Page"
+    has_association :friends, "User"
     
+    # Does the current user has an extender permission
     def has_app_permission?(ext_perm)
       boolianize(client.rest_call("users.hasAppPermission", :ext_perm => ext_perm.to_s))
     end
 
+    # Get information about current user's friends.
+    # A lot of information is not available in Graph api or is available but
+    # only after making several requests to Facebook.
     def friends!(ids)
       data = self.client.rest_call('users.getInfo', :uids => ids, :fields =>
                                                 'about_me,activities,affiliations,books,birthday,birthday_date,current_location,education_history,

data/lib/joey/version.rb

@@ -2,7 +2,7 @@ module Joey #:nodoc:
   module VERSION #:nodoc:
     MAJOR = 0
     MINOR = 0
-    TINY  = 1
+    TINY  = 2
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Waseem Ahmad
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-06-16 00:00:00 +05:30
+date: 2010-06-22 00:00:00 +05:30
 default_executable: 
 dependencies: []
 
@@ -48,10 +48,12 @@ extra_rdoc_files:
 - lib/joey/work.rb
 - lib/joey/work_history.rb
 files: 
+- COPYING.txt
 - README.md
 - Rakefile
 - devel.vim
 - init.rb
+- joey.gemspec
 - lib/joey.rb
 - lib/joey/affiliation.rb
 - lib/joey/album.rb
@@ -74,7 +76,6 @@ files:
 - lib/joey/work.rb
 - lib/joey/work_history.rb
 - Manifest
-- joey.gemspec
 has_rdoc: true
 homepage: http://github.com/waseem/joey
 licenses: []