ActsAsFollower
==============

acts_as_follower is a plugin to allow any model to "follow" any other model.

Main uses would be for Users to follow other Users or for Users to follow Books, etc...

(Basics to develop the type of follow system that GitHub has)

Install
=======

* Run the following command:
  ./script/plugin install git://github.com/tcocca/acts_as_follower.git 
  
* Create a new rails migration using the generator:
  ./script/generate acts_as_follower
  
  This will generate a migration file as well as a model called Follow.


Usage & Examples
=======

Make your model(s) that you want to allow to to follow acts_as_followable

   class User < ActiveRecord::Base
     ...
     acts_as_followable
     ...
   end
   
   class Book < ActiveRecord::Base
     ...
     acts_as_followable
     ...
   end
 
Make your model(s) that can follow other model(s) acts_as_follower

   class User < ActiveRecord::Base
     ...
     acts_as_follower
     ...
   end

ActsAsFollower Methods

- To have a Model object start following another use the following:

    book = Book.find(1)
    current_user.follow(book) # Creates a record for the current_user as the follower and the book as the followable

- To stop following a Model object use the following

    current_user.stop_following(book) # Deletes that record in the Follow table

- You can check to see if a Model that acts_as_follower is following a Model acts_as_followable through the following:

    current_user.following?(book) # Returns true or false

- To get all of the records that a Model is following use the following on a model that acts_as_follower

    current_user.all_following # Returns an array of every followed object for the current user.
    
- To get all followed objects by a certain type use the following on a model that acts_as_follower. It should be noted 
that this method is considerably faster than the above one.

    current_user.following_by_type('Book') # Returns an array of all followed objects for current user where 
    followable_type is 'Book'
    
- To get the total number (count) of follows for a user use the following on a model that acts_as_follower

    current_user.follow_count # Returns and integer


# ActsAsFollowable Methods

- To get all the followers of a model that acts_as_followable

    book = Book.find(1)
    book.followers  # Returns an array of all the followers for that book
    
- To get just the number of follows use

    book.follows_count
    
- To see is a model that acts_as_followable is followed by a model that acts_as_follower use the following

    book.followed_by?(current_user) # Returns true or false depending on if current_user is following book

- To block a follower call the following
        
        book.block(current_user)  
  
    # Blocks the current user from appearing in the followers list, and blocks the book from appearing in the 
    current_user.all_follows or current_user.all_following lists

- To unblock is just as simple
        
        book.unblock(current_user)
    
    # Unblocking deletes all records of that follow, instead of just the :blocked attribute => false the follow is 
    deleted.  So, current_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


Comments
=======

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


Props
=======
Thank you to Dougal and JDG for their interest and time in commiting to making this plugin better.
Also, make sure to check out Dougal's blog about the plugin here: 
http://douglasfshearer.com/blog/rails-plugin-acts-as-follower

Also, props go out to Pete Jackson on his VoteFu plugin which is what I took the majority of the design pattern for this 
plugin from:
See Pete's plugin here: http://github.com/peteonrails/vote_fu/tree/master

Pete based his plugin off of acts_as_voteable and acts_as_commentable so I should give props there as well.

Thank you Pete!

Thank you to  jhchabran (Jean Hadrien Chabran) - http://github.com/jhchabran and TomK32 (Thomas R. Koll) 
http://github.com/TomK32
for their commits to the block/unblock problem, I took a sampling of their strategies and combined them.  Thanks guys.


TODO
=======

* Add Example Usage code to the plugin

* Let me know if there is something else you would like to see.

Copyright (c) 2008 Tom Cocca ( tom dot cocca at gmail dot com ), released under the MIT license