acts_as_follower 0.1.0

data/.gitignore

@@ -0,0 +1,8 @@
+test/debug.log
+coverage
+rdoc
+memory
+*.gem
+.rvmrc
+Gemfile.lock
+log

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in acts_as_follower.gemspec
+gemspec

data/MIT-LICENSE

@@ -0,0 +1,44 @@
+Copyright (c) 2008 Tom Cocca
+
+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.
+
+The major design pattern of this plugin was abstracted from Peter Jackson's VoteFu, which is subject to the same license.
+Here is the original copyright notice for VoteFu:
+
+Copyright (c) 2008 Peter Jackson (peteonrails.com)
+
+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/README.rdoc

@@ -0,0 +1,208 @@
+= acts_as_follower
+
+acts_as_follower is a gem to allow any model to follow any other model.  This is accomplished through a double polymorphic relationship on the Follow model.  There is also built in support for blocking/un-blocking follow records.
+
+Main uses would be for Users to follow other Users or for Users to follow Books, etc...
+
+(Basically, to develop the type of follow system that GitHub has)
+
+
+== Installation
+
+=== The master branch supports rails 3
+
+Add the gem to the gemfile:
+  gem "acts_as_follower"
+
+Run the generator:
+  rails generate acts_as_follower
+
+This will generate a migration file as well as a model called Follow.
+
+=== Rails 2.3.x support
+
+Rails 2.3.x is supported in the rails_2.3.x branch http://github.com/tcocca/acts_as_follower/tree/rails_2.3.x but must be installed as a plugin.
+The gem version does not work with rails 2.3.x.
+
+Run the following command:
+  script/plugin install git://github.com/tcocca/acts_as_follower.git -r rails_2.3.x
+
+Run the generator:
+  script/generate acts_as_follower
+
+
+== Usage
+
+=== Setup
+
+Make your model(s) that you want to allow to be followed acts_as_followable, just add the mixin:
+  class User < ActiveRecord::Base
+    ...
+    acts_as_followable
+    ...
+  end
+
+  class Book < ActiveRecord::Base
+    ...
+    acts_as_followable
+    ...
+  end
+
+Make your model(s) that can follow other models acts_as_follower
+  class User < ActiveRecord::Base
+    ...
+    acts_as_follower
+    ...
+  end
+
+---
+
+=== acts_as_follower methods
+
+To have an object start following another use the following:
+  book = Book.find(1)
+  user = User.find(1)
+  user.follow(book) # Creates a record for the user as the follower and the book as the followable
+
+To stop following an object use the following
+  user.stop_following(book) # Deletes that record in the Follow table
+
+You can check to see if an object that acts_as_follower is following another object through the following:
+  user.following?(book) # Returns true or false
+
+To get the total number (count) of follows for a user use the following on a model that acts_as_follower
+  user.follow_count # Returns and integer
+
+To get follow records that have not been blocked use the following
+  user.all_follows # returns an array of Follow records
+
+To get all of the records that an object is following that have not been blocked use the following
+  user.all_following
+  # Returns an array of every followed object for the user, this can be a collection of different object types, eg: User, Book
+
+To get all Follow records by a certain type use the following
+  user.follows_by_type('Book') # returns an array of Follow objects where the followable_type is 'Book'
+
+To get all followed objects by a certain type use the following.
+  user.following_by_type('Book') # Returns an array of all followed objects for user where followable_type is 'Book', this can be a collection of different object types, eg: User, Book
+
+There is also a method_missing to accomplish the exact same thing a following_by_type('Book') to make you life easier
+  user.following_users # exact same results as user.following_by_type('User')
+
+To get the count of all Follow records by a certain type use the following
+  user.following_by_type_count('Book') # Returns the sql count of the number of followed books by that user
+
+There is also a method_missing to get the count by type
+  user.following_books_count # Calls the user.following_by_type_count('Book') method
+
+The following methods take an optional hash parameter of ActiveRecord options (:limit, :order, etc...)
+  follows_by_type, all_follows, all_following, following_by_type
+---
+
+=== acts_as_followable methods
+
+To get all the followers of a model that acts_as_followable
+  book.followers  # Returns an array of all the followers for that book, a collection of different object types (eg. type User or type Book)
+
+To get just the number of follows use
+  book.followers_count
+
+To get the followers of a certain type, eg: all followers of type 'User'
+  book.followers_by_type('User') # Returns an array of the user followers
+
+There is also a method_missing for this to make it easier:
+  book.user_followers # Calls followers_by_type('User')
+
+To get just the sql count of the number of followers of a certain type use the following
+  book.followers_by_type_count('User') # Return the count on the number of followers of type 'User'
+
+Again, there is a method_missing for this method as well
+  book.count_user_followers # Calls followers_by_type_count('User')
+
+To see is a model that acts_as_followable is followed by a model that acts_as_follower use the following
+  book.followed_by?(user)
+
+  # Returns true if the current instance is followed by the passed record
+  # Returns false if the current instance is blocked by the passed record or no follow is found
+
+To block a follower call the following
+  book.block(user)
+  # Blocks the user from appearing in the followers list, and blocks the book from appearing in the user.all_follows or user.all_following lists
+
+To unblock is just as simple
+  book.unblock(user)
+
+To get all blocked records
+  book.blocks # Returns an array of blocked follower records (only unblocked) (eg. type User or type Book)
+
+If you only need the number of blocks use the count method provided
+  book.blocked_followers_count
+
+Unblocking deletes all records of that follow, instead of just the :blocked attribute => false the follow is deleted.  So, a user would need to try and follow the book again.
+I would like to hear thoughts on this, I may change this to make the follow as :blocked => false instead of deleting the record.
+
+The following methods take an optional hash parameter of ActiveRecord options (:limit, :order, etc...)
+  followers_by_type, followers, blocks
+---
+
+=== Follow Model
+
+The Follow model has a set of named_scope's.  In case you want to interface directly with the Follow model you can use them.
+  Follow.unblocked # returns all "unblocked" follow records
+
+  Follow.blocked # returns all "blocked" follow records
+
+  Follow.descending # returns all records in a descending order based on created_at datetime
+
+This method pulls all records created after a certain date.  The default is 2 weeks but it takes an optional parameter.
+  Follow.recent
+  Follow.recent(4.weeks.ago)
+
+Follow.for_follower is a named_scope that is mainly there to reduce code in the modules but it could be used directly.  It takes an object and will return all Follow records where the follower is the record passed in.  Note that this will return all blocked and unblocked records.
+  Follow.for_follower(user)
+If you don't need the blocked records just use the methods provided for this:
+  user.all_follows
+  # or
+  user.all_following
+
+Follow.for_followable acts the same as its counterpart (for_follower).  It is mainly there to reduce duplication, however it can be used directly.  It takes an object that is the followed object and return all Follow records where that record is the followable. Again, this returns all blocked and unblocked records.
+  Follow.for_followable(book)
+Again, if you don't need the blocked records use the method provided for this:
+  book.followers
+If you need blocked records only
+  book.blocks
+
+
+== Comments/Requests
+
+If anyone has comments or questions please let me know (tom dot cocca at gmail dot com).
+If you have updates or patches or want to contribute I would love to see what you have or want to add.
+
+
+== Note on Patches/Pull Requests
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a future version unintentionally (acts_as_follower uses Shoulda and Factory Girl)
+* Send me a pull request. Bonus points for topic branches.
+
+
+== Contributers
+
+Thanks to everyone for their interest and time in committing to making this plugin better.
+
+* dougal (Douglas F Shearer) - http://github.com/dougal
+* jdg (Jonathan George) - http://github.com/jdg
+* m3talsmith (Michael Christenson II) - http://github.com/m3talsmith
+* joergbattermann (Jörg Battermann) - http://github.com/joergbattermann
+* TomK32 (Thomas R. Koll) - http://github.com/TomK32
+* drcapulet (Alex Coomans) - http://github.com/drcapulet
+* jhchabran (Jean Hadrien Chabran) - http://github.com/jhchabran
+* arthurgeek (Arthur Zapparoli) - http://github.com/arthurgeek
+
+Please let me know if I missed you.
+
+
+== Copyright
+
+Copyright (c) 2008 - 2010 ( tom dot cocca at gmail dot com ), released under the MIT license.

data/Rakefile

@@ -0,0 +1,39 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the acts_as_follower gem.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the acts_as_follower gem.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Acts As Follower'
+  rdoc.main     = 'README.rdoc'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc', 'lib/**/*.rb')
+end
+
+namespace :rcov do
+
+  desc "Generate a coverage report in coverage/"
+  task :gen do
+    sh "rcov --output coverage test/*_test.rb --exclude 'gems/*'"
+  end
+
+  desc "Remove generated coverage files."
+  task :clobber do
+    sh "rm -rdf coverage"
+  end
+
+end

data/acts_as_follower.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "acts_as_follower/version"
+
+Gem::Specification.new do |s|
+  s.name        = "acts_as_follower"
+  s.version     = ActsAsFollower::VERSION
+  s.authors     = ["Tom Cocca"]
+  s.email       = ["tom dot cocca at gmail dot com"]
+  s.homepage    = "https://github.com/tcocca/acts_as_follower"
+  s.summary     = %q{A Rubygem to add Follow functionality for ActiveRecord models}
+  s.description = %q{acts_as_follower is a Rubygem to allow any model to follow any other model. This is accomplished through a double polymorphic relationship on the Follow model. There is also built in support for blocking/un-blocking follow records. Main uses would be for Users to follow other Users or for Users to follow Books, etc… (Basically, to develop the type of follow system that GitHub has)}
+
+  s.rubyforge_project = "acts_as_follower"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency "sqlite3"
+  s.add_development_dependency "shoulda"
+  s.add_development_dependency "factory_girl"
+  s.add_development_dependency "rails", "~>3.0.10"
+end

data/init.rb

@@ -0,0 +1 @@
+require 'acts_as_follower'

data/lib/acts_as_follower.rb

@@ -0,0 +1,11 @@
+require "acts_as_follower/version"
+
+module ActsAsFollower
+  autoload :Follower,     'acts_as_follower/follower'
+  autoload :Followable,   'acts_as_follower/followable'
+  autoload :FollowerLib,  'acts_as_follower/follower_lib'
+  
+  require 'acts_as_follower/railtie' if defined?(Rails) && Rails::VERSION::MAJOR >= 3
+end
+
+

data/lib/acts_as_follower/followable.rb

@@ -0,0 +1,102 @@
+module ActsAsFollower #:nodoc:
+  module Followable
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      def acts_as_followable
+        has_many :followings, :as => :followable, :dependent => :destroy, :class_name => 'Follow'
+        include ActsAsFollower::Followable::InstanceMethods
+        include ActsAsFollower::FollowerLib
+      end
+    end
+
+
+    module InstanceMethods
+
+      # Returns the number of followers a record has.
+      def followers_count
+        self.followings.unblocked.count
+      end
+
+      # Returns the followers by a given type
+      def followers_by_type(follower_type, options={})
+        follows = follower_type.constantize.
+          includes(:follows).
+          where('blocked = ?', false).
+          where(
+            "follows.followable_id = ? AND follows.followable_type = ? AND follows.follower_type = ?", 
+            self.id, parent_class_name(self), follower_type
+          )
+        if options.has_key?(:limit)
+          follows = follows.limit(options[:limit])
+        end
+        follows
+      end
+
+      def followers_by_type_count(follower_type)
+        self.followings.unblocked.for_follower_type(follower_type).count
+      end
+
+      # Allows magic names on followers_by_type
+      # e.g. user_followers == followers_by_type('User')
+      # Allows magic names on followers_by_type_count
+      # e.g. count_user_followers == followers_by_type_count('User')
+      def method_missing(m, *args)
+        if m.to_s[/count_(.+)_followers/]
+          followers_by_type_count($1.singularize.classify)
+        elsif m.to_s[/(.+)_followers/]
+          followers_by_type($1.singularize.classify)
+        else
+          super
+        end
+      end
+
+      def blocked_followers_count
+        self.followings.blocked.count
+      end
+
+      # Returns the following records.
+      def followers(options={})
+        self.followings.unblocked.includes(:follower).all(options).collect{|f| f.follower}
+      end
+
+      def blocks(options={})
+        self.followings.blocked.includes(:follower).all(options).collect{|f| f.follower}
+      end
+
+      # Returns true if the current instance is followed by the passed record
+      # Returns false if the current instance is blocked by the passed record or no follow is found
+      def followed_by?(follower)
+        f = get_follow_for(follower)
+        (f && !f.blocked?) ? true : false
+      end
+
+      def block(follower)
+        get_follow_for(follower) ? block_existing_follow(follower) : block_future_follow(follower)
+      end
+
+      def unblock(follower)
+        get_follow_for(follower).try(:delete)
+      end
+
+      private
+
+      def get_follow_for(follower)
+        Follow.for_followable(self).for_follower(follower).first
+      end
+
+      def block_future_follow(follower)
+        follows.create(:followable => self, :follower => follower, :blocked => true)
+      end
+
+      def block_existing_follow(follower)
+        get_follow_for(follower).block!
+      end
+
+    end
+
+  end
+end