Partisan is a Ruby library that allows ActiveRecord records to follow other records.
---
It’s heavily inspired by `acts_as_follower`. However, it’s not 100% compatible with `acts_as_follower` as I removed some “features”:
* Block a follower
* Methods that returned mixed types of followers/following
* `*_count` methods (see the new features list)
But I also added awesome new ones:
* You can use `following_team_ids` but also `following_team_names` (basically any `following_team_s`). It takes advantage of the `pluck` method, so it doesn’t create an instance of each follower, it just return the relevant column values. (Go check `pluck` documentation, it’s simply awesome).
* The `followers` and `followings` methods now return an `ActiveRecord::Relation` for easy chaining, scoping, counting, pagination, etc.
## Installation
Add this line to your application’s Gemfile:
```ruby
gem 'partisan'
```
And then execute
```bash
$ bundle
```
Run the migration to add the `follows` table and the `Follow` model:
```bash
$ rails generate partisan:install
```
## Usage
Create a couple of models.
```ruby
class Fan < ActiveRecord::Base
acts_as_follower
end
class Band < ActiveRecord::Base
acts_as_followable
end
class Follow < ActiveRecord::Base
acts_as_follow
end
```
And follow/unfollow other records!
```ruby
fan = Fan.find(1)
band = Band.find(2)
fan.follow(band)
fan.following_bands
# => []
fan.follows?(band)
# => true
fan.unfollow(band)
fan.follows?(band)
# => false
```
### Cache counters
Most of the times, you would want to get a quick look at about how many fans follow a certain resource. That could be an expensive operation.
However, if the *followed* record has a `followers_count` column, Partisan will populate its value with how many followers the record has.
```ruby
fan.follow(band)
band.followers.count
# SQL query that counts records and returns `1`
band.followers_count
# Quick lookup into the column and returns `1`
```
The same concept applies to `followable` with a `followings_count` column.
### Callbacks
You can define callbacks that will be triggered before or after a following relationship is created.
If a `before_follow` callback returns `false`, it will halt the call and the relationship will be not be saved (much like `ActiveRecords`’s `before_save` callbacks).
```ruby
class Fan < ActiveRecord::Base
acts_as_follower
after_follow :send_notification
def send_notification
puts "#{self} is now following #{self.just_followed}"
end
end
class Band < ActiveRecord::Base
acts_as_followable
before_follow :ensure_active_fan
def ensure_active_fan
self.about_to_be_followed_by.active?
end
end
```
The available callbacks are:
#### Follower
| Callback | Reference to the followable |
| ------------------|-----------------------------|
| `before_follow` | `self.about_to_follow` |
| `after_follow` | `self.just_followed` |
| `before_unfollow` | `self.about_to_unfollow` |
| `after_unfollow` | `self.just_unfollowed` |
#### Followable
| Callback | Reference to the follower |
| --------------------------|----------------------------------|
| `before_being_followed` | `self.about_to_be_followed_by` |
| `after_being_followed` | `self.just_followed_by` |
| `before_being_unfollowed` | `self.about_to_by_unfollowed_by` |
| `after_being_unfollowed` | `self.just_unfollowed_by` |
## Contributors
* [@simonprev](https://github.com/simonprev)
* [@remiprev](https://github.com/remiprev)
* [@jdurand](https://github.com/jdurand)
## License
`Partisan` is © 2013-2016 [Mirego](http://www.mirego.com) and may be freely distributed under the [New BSD license](http://opensource.org/licenses/BSD-3-Clause). See the [`LICENSE.md`](https://github.com/mirego/partisan/blob/master/LICENSE.md) file.
## About Mirego
[Mirego](http://mirego.com) is a team of passionate people who believe that work is a place where you can innovate and have fun. We're a team of [talented people](http://life.mirego.com) who imagine and build beautiful Web and mobile applications. We come together to share ideas and [change the world](http://mirego.org).
We also [love open-source software](http://open.mirego.com) and we try to give back to the community as much as we can.