acmetech/make_flaggable

User-centric flagging system for Rails 3 applications.

MakeFlaggable¶ ↑

MakeFlaggable is an extension for building a user-centric flagging system for Rails 3 applications. It currently supports ActiveRecord models.

Special thanks to medihack for providing this awesome gem!

Installation¶ ↑

add MakeFlaggable to your Gemfile

gem 'make_flaggable', :git => 'git://github.com/cavneb/make_flaggable.git'

afterwards execute

bundle install

generate the required migration file

rails generate make_flaggable

migrate the database

rake db:migrate

Usage¶ ↑

# Specify a model that can be flagged and provide the names of the flags
class Article < ActiveRecord::Base
  make_flaggable :inappropriate, :favorite
end

# Specify a model that can flag another model.
class User < ActiveRecord::Base
  make_flagger
end

# The user can now flag the flaggable.
# If the user already flagged the flaggable with the :flag_name then an AlreadyFlaggedError is raised.
user.flag!(article, :flag_name)

# The method without bang(!) does not raise the AlreadyFlaggedError when the user flags the flaggable more than once.
# Instead it just returns false and ignores the flagging.
user.flag(article, :flag_name)

# The user may unflag an already done flagging.
# If the user never flagged the flaggable then an NotFlaggedError is raised.
user.unflag!(article, :flag_name)

# The method without bang(!) does not raise the NotFlaggedError, but just returns false if the user never flagged
# the flaggable.
user.unflag(article, :flag_name)

# The user can also easily toggle the state of a flag: subsquent calls to toggle_flag will flag/unflag it:
user.toggle_flag(article, :flag_name) # returns true as the flag has been set
user.toggle_flag(article, :flag_name) # returns false as the flag has now been removed
user.toggle_flag(article, :flag_name) # flag set again

# Get all flaggings of a flaggable.
article.flaggings

# Get the flagging with a specified flag.
article.flaggings.with_flag(:flag_name)

# Get the flagger of the flagging.
flagging = article.flaggings.with_flag(:flag_name).first
user = flagging.flagger

# Returns true if the flagger flagged the flaggable, false otherwise.
user.flagged?(article, :flag_name)

# Returns true if the flagger flagged the flaggable with any flag, false otherwise.
# A more concise version of user.flaggings.with_flaggable(article)
user.flagged?(article)

# Return true if the flaggable was flagged by the flagger, false otherwise.
article.flagged_by?(user, :flag_name)

# Returns true if the article was flagged by any flagger at all, false otherwise.
article.flagged?(:flag_name)

# Flaggings can also be accessed by its flagger.
flagger.flaggings or flagger.flaggings.with_flag(:flag_name) or flagger.flaggings.with_flaggable(:flaggable)

# Get the available flags for a flaggable
article.available_flags

# Get the available flags for a flaggable class
Article.available_flags

Testing¶ ↑

MakeFlaggable uses RSpec for testing and has a rake task for executing the provided specs

rake spec

or simply

rake

Copyright © 2010-2011 Kai Schlamp (www.medihack.org), released under the MIT license

Modified to use specified flags by Eric Berry