make_flaggable 0.0.2

data/.gitignore

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

data/Gemfile

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

data/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.

data/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

data/Rakefile

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

data/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

data/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

data/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

data/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

data/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

data/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

data/lib/make_flaggable/version.rb

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

data/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

data/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       = ["schlamp@gmx.de"]
+  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

data/spec/database.yml

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

data/spec/database.yml.sample

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

data/spec/generators/make_flaggable_generator_spec.rb

@@ -0,0 +1,28 @@
+require 'spec_helper'
+require 'action_controller'
+require 'generator_spec/test_case'
+require 'generators/make_flaggable/make_flaggable_generator'
+
+describe MakeFlaggableGenerator do
+  include GeneratorSpec::TestCase
+  destination File.expand_path("/tmp", __FILE__)
+  tests MakeFlaggableGenerator
+
+  before do
+    prepare_destination
+    run_generator
+  end
+
+  specify do
+    destination_root.should have_structure {
+      directory "db" do
+        directory "migrate" do
+          migration "create_make_flaggable_tables" do
+            contains "class CreateMakeFlaggableTables"
+            contains "create_table :flaggings"
+          end
+        end
+      end
+    }
+  end
+end

data/spec/lib/make_flaggable_spec.rb

@@ -0,0 +1,104 @@
+require File.expand_path('../../spec_helper', __FILE__)
+
+describe "Make Flaggable" do
+  before(:each) do
+    @flaggable = FlaggableModel.create(:name => "Flaggable 1")
+    @flagger = FlaggerModel.create(:name => "Flagger 1")
+    @flagger_once = FlaggerOnceModel.create(:name => "Flagger Once 1")
+  end
+
+  it "should create a flaggable instance" do
+    @flaggable.class.should == FlaggableModel
+    @flaggable.class.flaggable?.should == true
+  end
+
+  it "should create a flagger instance" do
+    @flagger.class.should == FlaggerModel
+    @flagger.class.flagger?.should == true
+
+    @flagger_once.class.should == FlaggerOnceModel
+    @flagger_once.class.flagger?.should == true
+  end
+
+  describe "flagger" do
+    describe "flag" do
+      it "should create a flagging" do
+        @flaggable.flaggings.length.should == 0
+        @flagger.flag!(@flaggable)
+        @flaggable.flaggings.reload.length.should == 1
+      end
+
+      it "should store the reason" do
+        @flagger.flag!(@flaggable, "The reason.")
+        reason = @flaggable.flaggings[0].reason
+        reason.should == "The reason."
+      end
+
+      it "should only allow to flag a flaggable per flagger once with rasing an error" do
+        @flagger_once.flag!(@flaggable)
+        lambda { @flagger_once.flag!(@flaggable) }.should raise_error(MakeFlaggable::Exceptions::AlreadyFlaggedError)
+        MakeFlaggable::Flagging.count.should == 1
+      end
+
+      it "should only allow to flag a flaggable per flagger once without rasing an error" do
+        @flagger_once.flag(@flaggable)
+        lambda { @flagger_once.flag(@flaggable) }.should_not raise_error(MakeFlaggable::Exceptions::AlreadyFlaggedError)
+        MakeFlaggable::Flagging.count.should == 1
+      end
+    end
+
+    describe "unflag" do
+      it "should unflag a flagging" do
+        @flagger.flag!(@flaggable)
+        @flagger.flaggings.length.should == 1
+        @flagger.unflag!(@flaggable).should == true
+        @flagger.flaggings.reload.length.should == 0
+      end
+
+      it "should unflag multiple flaggings" do
+        @flagger.flag!(@flaggable)
+        @flagger.flag!(@flaggable)
+        @flagger.flaggings.length.should == 2
+        @flagger.unflag!(@flaggable).should == true
+        @flagger.flaggings.reload.length.should == 0
+      end
+
+      it "normal method should return true when successfully unflagged" do
+        @flagger.flag(@flaggable)
+        @flagger.unflag(@flaggable).should == true
+      end
+
+      it "should raise error if flagger not flagged the flaggable with bang method" do
+        lambda { @flagger.unflag!(@flaggable) }.should raise_error(MakeFlaggable::Exceptions::NotFlaggedError)
+      end
+
+      it "should not raise error if flagger not flagged the flaggable with normal method" do
+        lambda {
+          @flagger.unflag(@flaggable).should == false
+        }.should_not raise_error(MakeFlaggable::Exceptions::NotFlaggedError)
+      end
+    end
+
+    it "should have flaggings" do
+      @flagger.flaggings.length.should == 0
+      @flagger.flag!(@flaggable)
+      @flagger.flaggings.reload.length.should == 1
+    end
+  end
+
+  describe "flaggable" do
+    it "should have flaggings" do
+      @flaggable.flaggings.length.should == 0
+      @flagger.flag!(@flaggable)
+      @flaggable.flaggings.reload.length.should == 1
+    end
+
+    it "should check if flaggable is flagged" do
+      @flaggable.flagged?.should == false
+      @flagger.flag!(@flaggable)
+      @flaggable.flagged?.should == true
+      @flagger.unflag!(@flaggable)
+      @flaggable.flagged?.should == false
+    end
+  end
+end

data/spec/models.rb

@@ -0,0 +1,14 @@
+class FlaggableModel < ActiveRecord::Base
+  make_flaggable
+end
+
+class FlaggerModel < ActiveRecord::Base
+  make_flagger
+end
+
+class FlaggerOnceModel < ActiveRecord::Base
+  make_flagger :flag_once => true
+end
+
+class InvalidFlaggableModel < ActiveRecord::Base
+end

data/spec/schema.rb

@@ -0,0 +1,30 @@
+ActiveRecord::Schema.define :version => 0 do
+  create_table :flaggable_models, :force => true do |t|
+    t.string :name
+  end
+
+  create_table :flagger_models, :force => true do |t|
+    t.string :name
+  end
+
+  create_table :flagger_once_models, :force => true do |t|
+    t.string :name
+  end
+
+  create_table :invalid_flaggable_models, :force => true do |t|
+    t.string :name
+  end
+
+  create_table :flaggings, :force => true 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

data/spec/spec_helper.rb

@@ -0,0 +1,37 @@
+require 'rubygems'
+require 'bundler'
+require 'logger'
+require 'rspec'
+require 'active_record'
+require 'database_cleaner'
+
+$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../lib')
+require 'make_flaggable'
+
+ActiveRecord::Base.logger = Logger.new(File.dirname(__FILE__) + '/debug.log')
+ActiveRecord::Base.configurations = YAML::load_file(File.dirname(__FILE__) + '/database.yml')
+ActiveRecord::Base.establish_connection(ENV['DB'] || 'sqlite3')
+
+ActiveRecord::Base.silence do
+  ActiveRecord::Migration.verbose = false
+
+  load(File.dirname(__FILE__) + '/schema.rb')
+  load(File.dirname(__FILE__) + '/models.rb')
+end
+
+RSpec.configure do |config|
+  config.filter_run :focus => true
+  config.run_all_when_everything_filtered = true
+  config.filter_run_excluding :exclude => true
+
+  config.mock_with :rspec
+
+  config.before(:suite) do
+    DatabaseCleaner.strategy = :truncation
+    DatabaseCleaner.clean
+  end
+
+  config.after(:each) do
+    DatabaseCleaner.clean
+  end
+end

metadata

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification 
+name: make_flaggable
+version: !ruby/object:Gem::Version 
+  prerelease: 
+  version: 0.0.2
+platform: ruby
+authors: 
+- Kai Schlamp
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-06-18 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: bundler
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.0.0
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 2.5.0
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: database_cleaner
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        version: 0.6.7.RC
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: sqlite3-ruby
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.3.0
+  type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: generator_spec
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 0.8.2
+  type: :development
+  version_requirements: *id006
+description: A user-centric flagging extension for Rails 3 applications.
+email: 
+- schlamp@gmx.de
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- Gemfile
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- lib/generators/make_flaggable/make_flaggable_generator.rb
+- lib/generators/make_flaggable/templates/migration.rb
+- lib/make_flaggable.rb
+- lib/make_flaggable/exceptions.rb
+- lib/make_flaggable/flaggable.rb
+- lib/make_flaggable/flagger.rb
+- lib/make_flaggable/flagging.rb
+- lib/make_flaggable/version.rb
+- make_flaggable.gemspec
+- spec/database.yml
+- spec/database.yml.sample
+- spec/generators/make_flaggable_generator_spec.rb
+- spec/lib/make_flaggable_spec.rb
+- spec/models.rb
+- spec/schema.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/medihack/make_flaggable
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: make_flaggable
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Rails 3 flagging extension
+test_files: []
+