Initial release.

.gitignore

@@ -0,0 +1,7 @@
+Gemfile.lock
+pkg/*
+doc/*
+*.gem
+*.log
+*.sqlite3
+.bundle

Gemfile

@@ -0,0 +1,4 @@
+source :gemcutter
+
+# Specify your gem's dependencies in make_flaggable.gemspec
+gemspec

MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010-2011 by Kai Schlamp
+
+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.

README.rdoc

@@ -0,0 +1,81 @@
+= MakeFlaggable
+
+MakeFlaggable is an extension for building a user-centric flagging system for Rails 3 applications.
+It currently supports ActiveRecord models.
+
+== Installation
+
+add MakeFlaggable to your Gemfile
+
+  gem 'make_flaggable'
+
+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.
+  class Article < ActiveRecord::Base
+    make_flaggable
+  end
+
+  # Specify a model that can flag another model.
+  class User < ActiveRecord::Base
+    make_flagger
+  end
+
+  # You can specify that a flagger can only flag a flaggable once.
+  class User < ActiveRecord::Base
+    make_flagger :flag_once => true
+  end
+
+  # The user can now flag the flaggable.
+  # If the user already flagged the flaggable and :flag_once was set then an AlreadyFlaggedError is raised.
+  user.flag!(article, reason)
+
+  # 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.
+  # If :flag_once was not set then this method behaves like flag! method.
+  user.flag(article, reason)
+
+  # The user may unflag an already done flagging.
+  # If the user never flagged the flaggable then an NotFlaggedError is raised.
+  user.unflag!(article)
+
+  # The method without bang(!) does not raise the NotFlaggedError, but just returns false if the user never flagged
+  # the flaggable.
+  user.unflag(article)
+
+  # Get all flaggings of a flaggable.
+  article.flaggings
+
+  # Get the reason of a flagging.
+  flagging = article.flaggings.first
+  flagging.reason
+
+  # Get the flagger of the flagging.
+  flagging = article.flaggings.first
+  user = flagging.flagger
+
+  # Returns true if the article was flagged by any flagger, false otherwise
+  article.flagged?
+
+  # Flaggings can also be accessed by its flagger.
+  flagger.flaggings
+
+== Testing
+
+MakeFlaggable uses RSpec for testing and has a rake task for executing the provided specs
+
+  rake spec
+
+Copyright © 2010-2011 Kai Schlamp (http://www.medihack.org), released under the MIT license

Rakefile

@@ -0,0 +1,7 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

lib/generators/make_flaggable/make_flaggable_generator.rb

@@ -0,0 +1,20 @@
+require 'rails/generators/migration'
+require 'rails/generators/active_record'
+
+class MakeFlaggableGenerator < Rails::Generators::Base
+  include Rails::Generators::Migration
+
+  desc "Generates a migration for the Flag model"
+
+  def self.source_root
+    @source_root ||= File.dirname(__FILE__) + '/templates'
+  end
+
+  def self.next_migration_number(path)
+    ActiveRecord::Generators::Base.next_migration_number(path)
+  end
+
+  def generate_migration
+    migration_template 'migration.rb', 'db/migrate/create_make_flaggable_tables'
+  end
+end

lib/generators/make_flaggable/templates/migration.rb

@@ -0,0 +1,23 @@
+class CreateMakeFlaggableTables < ActiveRecord::Migration
+   def self.up
+     create_table :flaggings do |t|
+       t.string :flaggable_type
+       t.integer :flaggable_id
+       t.string :flagger_type
+       t.integer :flagger_id
+       t.text :reason
+
+       t.timestamps
+    end
+
+    add_index :flaggings, [:flaggable_type, :flaggable_id]
+    add_index :flaggings, [:flagger_type, :flagger_id, :flaggable_type, :flaggable_id], :name => "access_flaggings"
+  end
+
+  def self.down
+    remove_index :flaggings, :column => [:flaggable_type, :flaggable_id]
+    remove_index :flaggings, :name => "access_flaggings"
+
+    drop_table :flaggings
+  end
+end

lib/make_flaggable.rb

@@ -0,0 +1,38 @@
+require 'make_flaggable/flagging'
+require 'make_flaggable/flaggable'
+require 'make_flaggable/flagger'
+require 'make_flaggable/exceptions'
+
+module MakeFlaggable
+  def flaggable?
+    false
+  end
+
+  def flagger?
+    false
+  end
+
+  # Specify a model as flaggable.
+  # Optional option :once_per_flagger when only on flag per flagger is allowed.
+  #
+  # Example:
+  # class Article < ActiveRecord::Base
+  #   make_flaggable :once_per_flagger => true
+  # end
+  def make_flaggable
+    include Flaggable
+  end
+
+  # Specify a model as flagger.
+  #
+  # Example:
+  # class User < ActiveRecord::Base
+  #   make_flagger
+  # end
+  def make_flagger(options = {})
+    define_method(:flaggable_options) { options }
+    include Flagger
+  end
+end
+
+ActiveRecord::Base.extend MakeFlaggable

lib/make_flaggable/exceptions.rb

@@ -0,0 +1,21 @@
+module MakeFlaggable
+  module Exceptions
+    class AlreadyFlaggedError < StandardError
+      def initialize
+        super "The flaggable was already flagged by this flagger."
+      end
+    end
+
+    class NotFlaggedError < StandardError
+      def initialize
+        super "The flaggable was not flagged by the flagger."
+      end
+    end
+
+    class InvalidFlaggableError < StandardError
+      def initialize
+        super "Invalid flaggable."
+      end
+    end
+  end
+end

lib/make_flaggable/flaggable.rb

@@ -0,0 +1,19 @@
+module MakeFlaggable
+  module Flaggable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :flaggings, :class_name => "MakeFlaggable::Flagging", :as => :flaggable
+    end
+
+    module ClassMethods
+      def flaggable?
+        true
+      end
+    end
+
+    def flagged?
+      flaggings.count > 0
+    end
+  end
+end

lib/make_flaggable/flagger.rb

@@ -0,0 +1,73 @@
+module MakeFlaggable
+  module Flagger
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :flaggings, :class_name => "MakeFlaggable::Flagging", :as => :flagger
+    end
+
+    module ClassMethods
+      def flagger?
+        true
+      end
+    end
+
+    # Flag a +flaggable+ using the provided +reason+.
+    # Raises an +AlreadyFlaggedError+ if the flagger already flagged the flaggable and +:flag_once+ option is set.
+    # Raises an +InvalidFlaggableError+ if the flaggable is not a valid flaggable.
+    def flag!(flaggable, reason = nil)
+      check_flaggable(flaggable)
+
+      if (flaggable_options[:flag_once] && fetch_flaggings(flaggable).try(:first))
+        raise MakeFlaggable::Exceptions::AlreadyFlaggedError.new
+      end
+
+      Flagging.create(:flaggable => flaggable, :flagger => self, :reason => reason)
+    end
+
+    # Flag the +flaggable+, but don't raise an error if the flaggable was already flagged and +:flag_once+ was set.
+    # If +:flag_once+ was not set then this method behaves like +flag!+.
+    # The flagging is simply ignored then.
+    def flag(flaggable, reason = nil)
+      begin
+        flag!(flaggable, reason)
+      rescue Exceptions::AlreadyFlaggedError
+      end
+    end
+
+    def unflag!(flaggable)
+      check_flaggable(flaggable)
+
+      flaggings = fetch_flaggings(flaggable)
+
+      raise Exceptions::NotFlaggedError if flaggings.empty?
+
+      flaggings.destroy_all
+
+      true
+    end
+
+    def unflag(flaggable)
+      begin
+        unflag!(flaggable)
+        success = true
+      rescue Exceptions::NotFlaggedError
+        success = false
+      end
+      success
+    end
+
+    private
+
+    def fetch_flaggings(flaggable)
+      flaggings.where({
+        :flaggable_type => flaggable.class.to_s,
+        :flaggable_id => flaggable.id
+      })
+    end
+
+    def check_flaggable(flaggable)
+      raise Exceptions::InvalidFlaggableError unless flaggable.class.flaggable?
+    end
+  end
+end

lib/make_flaggable/flagging.rb

@@ -0,0 +1,6 @@
+module MakeFlaggable
+  class Flagging < ActiveRecord::Base
+    belongs_to :flaggable, :polymorphic => true
+    belongs_to :flagger, :polymorphic => true
+  end
+end

lib/make_flaggable/version.rb

@@ -0,0 +1,3 @@
+module MakeFlaggable
+  VERSION = "0.0.1"
+end

make_flaggable.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path("../lib/make_flaggable/version", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = "make_flaggable"
+  s.version     = MakeFlaggable::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Kai Schlamp"]
+  s.email       = ["[email protected]"]
+  s.homepage    = "http://github.com/medihack/make_flaggable"
+  s.summary     = "Rails 3 flagging extension"
+  s.description = "A user-centric flagging extension for Rails 3 applications."
+
+  s.required_rubygems_version = ">= 1.3.6"
+  s.rubyforge_project         = "make_flaggable"
+
+  s.add_dependency "activerecord", "~> 3.0.0"
+  s.add_development_dependency "bundler", "~> 1.0.0"
+  s.add_development_dependency "rspec", "~> 2.5.0"
+  s.add_development_dependency "database_cleaner", "0.6.7.RC"
+  s.add_development_dependency "sqlite3-ruby", "~> 1.3.0"
+  s.add_development_dependency "generator_spec", "~> 0.8.2"
+
+  s.files        = `git ls-files`.split("\n")
+  s.executables  = `git ls-files`.split("\n").map{|f| f =~ /^bin\/(.*)/ ? $1 : nil}.compact
+  s.require_path = 'lib'
+end

spec/database.yml

@@ -0,0 +1,3 @@
+sqlite3:
+  adapter: sqlite3
+  database: make_flaggable.sqlite3

spec/database.yml.sample

@@ -0,0 +1,3 @@
+sqlite3:
+  adapter: sqlite3
+  database: make_flaggable.sqlite3