dm-taggings 0.11.0

data/lib/dm-taggings.rb

@@ -0,0 +1,19 @@
+require 'pathname'
+
+# Add all external dependencies for the plugin here
+require 'dm-core'
+require 'dm-constraints'
+require 'dm-is-remixable'
+
+# Require plugin-files
+
+dir = Pathname(__FILE__).dirname.expand_path / 'dm-taggings' / 'is'
+
+require dir / 'taggable.rb'
+require dir / 'tag.rb'
+require dir / 'tagging.rb'
+require dir / 'tagger.rb'
+
+# Include the plugin in Resource
+DataMapper::Model.append_extensions DataMapper::Is::Taggable
+DataMapper::Model.append_extensions DataMapper::Is::Tagger

data/lib/dm-taggings/is/tag.rb

@@ -0,0 +1,42 @@
+class Tag
+  include DataMapper::Resource
+
+  property :id,   Serial
+  property :name, String, :required => true, :unique => true
+
+  # Shortcut to build method
+  #
+  # @see Tag.build
+  #
+  # @api public
+  def self.[](name)
+    build(name)
+  end
+
+  # Find or create a tag with the give name
+  #
+  # @param [String] name
+  #   A name of a tag
+  #
+  # @return [DataMapper::Resource]
+  #   A tag resource instance
+  #
+  # @api public
+  def self.build(name)
+    Tag.first_or_create(:name => name.strip) if name
+  end
+
+  # An overridden name attribute setter that strips the value
+  #
+  # @param [String] value
+  #   A value to be set as the tag name
+  #
+  # @return [String]
+  #  The name
+  #
+  # @api public
+  def name=(value)
+    super(value.strip) if value
+    name
+  end
+end

data/lib/dm-taggings/is/taggable.rb

@@ -0,0 +1,245 @@
+module DataMapper
+  module Is
+    module Taggable
+
+      # Make a resource taggable
+      #
+      # @example
+      #
+      #   class Post
+      #     include DataMapper::Resource
+      #
+      #     property :id,      Serial
+      #     property :title,   String
+      #     property :content, Text
+      #
+      #     is :taggable
+      #   end
+      #
+      # @param [Hash] options(optional)
+      #   A hash with options
+      # @option options [Array] :by
+      #   A list of DataMapper models that should become taggers
+      #
+      # @api public
+      def is_taggable(options={})
+
+        # Add class-methods
+        extend  DataMapper::Is::Taggable::ClassMethods
+        # Add instance-methods
+        include DataMapper::Is::Taggable::InstanceMethods
+
+        class << self
+          attr_reader :tagging_parent_name, :tagging_relationship_name, :tagging_relationship,
+            :tagging_class, :taggable_relationship_name
+        end
+
+        # Make the magic happen
+        options[:by] ||= []
+
+        remix n, :taggings
+
+        @tagging_parent_name       = DataMapper::Inflector.underscore(name).to_sym
+        @tagging_relationship_name = "#{@tagging_parent_name}_tags".to_sym
+        @tagging_relationship      = relationships[@tagging_relationship_name]
+        @tagging_class             = @tagging_relationship.child_model
+
+        @taggable_relationship_name = DataMapper::Inflector.underscore(name).pluralize.to_sym
+
+        @tagging_relationship.add_constraint_option(
+          @taggable_relationship_name, @tagging_class, self, :constraint => :destroy!)
+
+        tagging_parent_name = @tagging_parent_name
+
+        enhance :taggings do
+          belongs_to :tag
+          belongs_to tagging_parent_name
+
+          options[:by].each do |tagger_class|
+            belongs_to DataMapper::Inflector.underscore(tagger_class.name), :required => false
+          end
+        end
+
+        has n, :tags, :through => @tagging_relationship_name, :constraint => :destroy!
+
+        Tag.has n, @tagging_relationship_name,  :constraint => :destroy!
+        Tag.has n, @taggable_relationship_name, :through => @tagging_relationship_name
+
+        options[:by].each do |tagger_class|
+          tagger_class.is :tagger, :for => [self]
+        end
+      end
+
+      module ClassMethods
+        # @attr_reader [String] tagging_parent_name
+        # @attr_reader [String] tagging_relationship_name
+        # @attr_reader [DataMapper::Associations::OneToMany::Relationship] tagging_relationship
+        # @attr_reader [DataMapper::Resource] tagging_class
+        # @attr_reader [String] taggable_relationship_name
+
+        # @api public
+        def taggable?
+          true
+        end
+
+        # Return all the taggable resources that are tagged with the given list of tags.
+        #
+        # Can be chained, for instance:
+        #
+        #     Post.tagged_with(["foo", "bar"]).all(:created_at.lt => 1.day.ago)
+        #
+        # @param [Array] tags_or_names
+        #   A list of either tag resources or tag names
+        #
+        # @return [DataMapper::Collection]
+        #   A collection of taggables
+        #
+        # @api public
+        def tagged_with(tags_or_names)
+          tags_or_names = [tags_or_names] unless tags_or_names.kind_of?(Array)
+
+          tag_ids = if tags_or_names.all? { |tag| tag.kind_of?(Tag) }
+                   tags_or_names
+                 else
+                   Tag.all(:name => tags_or_names)
+                 end.map { |tag| tag.id }
+
+          all("#{tagging_relationship_name}.tag_id" => tag_ids)
+        end
+      end # ClassMethods
+
+      module InstanceMethods
+        # Add tags to a resource but do not persist them.
+        #
+        # @param [Array] tags_or_names
+        #   A list of either tag resources or tag names
+        #
+        # @return [DataMapper::Associations::OneToMany::Collection]
+        #   A DataMapper collection of resource's tags
+        #
+        # @api public
+        def tag(tags_or_names)
+          tags = extract_tags_from_names(tags_or_names)
+
+          tags.each do |tag|
+            next if self.tags.include?(tag)
+            taggings.new(:tag => tag)
+          end
+
+          taggings
+        end
+
+        # Add tags to a resource and persists them.
+        #
+        # @param [Array] tags_or_names
+        #   A list of either tag resources or tag names
+        #
+        # @return [DataMapper::Associations::OneToMany::Collection]
+        #   A DataMapper collection of resource's tags
+        #
+        # @api public
+        def tag!(tags_or_names)
+          taggings = tag(tags_or_names)
+          taggings.save! unless new?
+          taggings
+        end
+
+        # Delete given tags from a resource collection without actually deleting
+        # them from the datastore. Everything will be deleted if no tags are given.
+        #
+        # @param [Array] tags_or_names (optional)
+        #   A list of either tag resources or tag names
+        #
+        # @return [DataMapper::Associations::OneToMany::Collection]
+        #   A DataMapper collection of resource's tags
+        #
+        # @api public
+        def untag(tags_or_names=nil)
+          tags = extract_tags_from_names(tags_or_names) if tags_or_names
+
+          taggings_to_destroy = if tags.blank?
+                             taggings.all
+                           else
+                             taggings.all(:tag => tags)
+                           end
+
+          self.taggings = taggings - taggings_to_destroy
+
+          taggings_to_destroy
+        end
+
+        # Same as untag but actually delete the tags from the datastore.
+        #
+        # @param [Array] tags_or_names (optional)
+        #   A list of either tag resources or tag names
+        #
+        # @return [DataMapper::Associations::OneToMany::Collection]
+        #   A DataMapper collection of resource's tags
+        #
+        # @api public
+        def untag!(tags_or_names=nil)
+          taggings_to_destroy = untag(tags_or_names)
+          taggings_to_destroy.destroy! unless new?
+          taggings_to_destroy
+        end
+
+        # Return a string representation of tags collection
+        #
+        # @return [String]
+        #   A tag list separated by commas
+        #
+        # @api public
+        def tag_list
+          @tag_list ||= tags.collect { |tag| tag.name }.join(", ")
+        end
+
+        # Tag a resource using tag names from the give list separated by commas.
+        #
+        # @param [String]
+        #   A tag list separated by commas
+        #
+        # @return [DataMapper::Associations::OneToMany::Collection]
+        #   A DataMapper collection of resource's tags
+        def tag_list=(list)
+          @tag_list = list
+
+          tag_names = list.split(",").map { |name| name.blank? ? nil : name.strip }.compact
+
+          old_tag_names = taggings.map { |tagging| tagging.tag.name } - tag_names
+
+          untag!(old_tag_names)
+          tag(tag_names)
+        end
+
+        # @api public
+        def reload
+          @tag_list = nil
+          super
+        end
+
+        # @api public
+        def taggings
+          send(self.class.tagging_relationship_name)
+        end
+
+        # @api public
+        def taggings=(taggings)
+          send("#{self.class.tagging_relationship_name}=", taggings)
+        end
+
+        protected
+
+        # @api private
+        def extract_tags_from_names(tags_or_names)
+          tags_or_names = [tags_or_names] unless tags_or_names.kind_of?(Array)
+
+          tags_or_names.map do |tag_or_name|
+            tag_or_name.kind_of?(Tag) ? tag_or_name : Tag[tag_or_name]
+          end
+        end
+      end # InstanceMethods
+
+    end # Taggable
+  end # Is
+end # DataMapper
+

data/lib/dm-taggings/is/tagger.rb

@@ -0,0 +1,115 @@
+module DataMapper
+  module Is
+    module Tagger
+      # Set up a resource as tagger
+      #
+      # @example
+      #
+      #   class Song
+      #     include DataMapper::Resource
+      #
+      #     property :id,    Serial
+      #     property :title, String
+      #
+      #     is :taggable, :by => [ User ]
+      #   end
+      #
+      #   class User
+      #     include DataMapper::Resource
+      #
+      #     property :id,   Serial
+      #     property :name, String
+      #
+      #     is :tagger, :for => [ Song ]
+      #   end
+      #
+      # @param [Hash] options
+      #   A hash of options
+      # @option options [Array] :for
+      #   A list of DataMapper taggable models
+      #
+      # @return [Array]
+      #   A list of DataMapper taggable models
+      #
+      # @api public
+      def is_tagger(options={})
+        unless self.respond_to?(:tagger?)
+          # Add class-methods
+          extend  DataMapper::Is::Tagger::ClassMethods
+
+          # Add instance-methods
+          include DataMapper::Is::Tagger::InstanceMethods
+
+          cattr_accessor(:taggable_object_classes)
+          self.taggable_object_classes = []
+        end
+
+        raise "options[:for] is missing" unless options[:for]
+
+        add_taggable_object_classes(options[:for])
+      end
+
+      module ClassMethods
+        # Return if a model is tagger
+        #
+        # @return [TrueClass]
+        #   true
+        #
+        # @api public
+        def tagger?
+          true
+        end
+
+        # Register new taggables and set up relationships
+        #
+        # @param [Array] taggable_object_classes
+        #   An array of taggable DataMapper models
+        #
+        # @api public
+        def add_taggable_object_classes(taggable_object_classes)
+          taggable_object_classes.each do |taggable_object_class|
+            self.taggable_object_classes << taggable_object_class
+
+            has n, taggable_object_class.tagging_relationship_name,
+              :constraint => :destroy
+
+            has n, taggable_object_class.taggable_relationship_name,
+              :through => taggable_object_class.tagging_relationship_name,
+              :constraint => :destroy
+          end
+        end
+      end # ClassMethods
+
+      module InstanceMethods
+        # Tag a resource
+        #
+        # @param [DataMapper::Resource]
+        #   An instance of a taggable resource
+        #
+        # @param [Hash] options (optional)
+        #   A hash with options
+        #
+        # @return [DataMapper::Collection]
+        #  A collection of tags that were associated with the resource
+        #
+        # @api public
+        def tag!(taggable, options={})
+          unless self.taggable_object_classes.include?(taggable.class)
+            raise "Object of type #{taggable.class} isn't taggable!"
+          end
+
+          tags = options[:with]
+          tags = [tags] unless tags.kind_of?(Array)
+
+          tags.each do |tag|
+            taggable.taggings.create(:tag => tag, :tagger => self)
+          end
+
+          tags
+        end
+      end # InstanceMethods
+
+    end # Tagger
+  end # Is
+end # DataMapper
+

data/lib/dm-taggings/is/tagging.rb

@@ -0,0 +1,13 @@
+module Tagging
+  include DataMapper::Resource
+
+  property :id, Serial
+  property :tag_id, Integer, :min => 1, :required => true
+
+  is :remixable, :suffix => "tag"
+
+  def tagger=(tagger)
+    send("#{DataMapper::Inflector.underscore(tagger.class.name).to_sym}=", tagger)
+  end
+end
+

data/lib/dm-taggings/is/version.rb

@@ -0,0 +1,7 @@
+module DataMapper
+  module Is
+    module Taggable
+      VERSION = File.read(File.expand_path("../../../../VERSION", __FILE__)).strip
+    end
+  end
+end

data/lib/dm-taggings/spec/taggable_shared_spec.rb

@@ -0,0 +1,259 @@
+share_examples_for 'A taggable resource' do
+  def create_taggable(attrs={})
+    @taggable.create(@taggable_attributes.merge(attrs))
+  end
+
+  before :all do
+    %w[ @taggable ].each do |ivar|
+      raise "+#{ivar}+ should be defined in before block" unless instance_variable_defined?(ivar)
+    end
+
+    @taggable_attributes ||= {}
+
+    @foo_tag  = Tag["foo"]
+    @bar_tag  = Tag["bar"]
+
+    @tags = [@foo_tag, @bar_tag]
+  end
+
+  describe "public class methods" do
+    subject { @taggable }
+
+    it { should respond_to(:is_taggable) }
+    it { should respond_to(:taggable?) }
+    it { should respond_to(:tagged_with) }
+    it { should respond_to(:tagging_relationship_name) }
+    it { should respond_to(:tagging_relationship) }
+    it { should respond_to(:tagging_class) }
+    it { should respond_to(:tagging_parent_name) }
+    it { should respond_to(:taggable_relationship_name) }
+
+    describe ".taggable?" do
+      it "should return true" do
+        @taggable.taggable?.should be(true)
+      end
+    end
+
+    describe "relationships" do
+      subject { @taggable.relationships }
+
+      it { should have_key(@taggable.tagging_relationship_name) }
+
+      describe "tagging constraint" do
+        subject { @taggable.tagging_relationship.constraint }
+        it { subject.should eql(:destroy!) }
+      end
+    end
+
+    describe ".tagged_with" do
+      before :all do
+        @resource_one = create_taggable(:tag_list => "red, green, blue")
+        @resource_two = create_taggable(:tag_list => "orange, yellow")
+      end
+
+      it "should return correct resources" do
+        result = @taggable.tagged_with(["red", "yellow", "purple"])
+        result.size.should eql(2)
+        result.should include(@resource_one, @resource_two)
+      end
+    end
+  end
+
+  describe "public instance methods" do
+    subject { @taggable.new }
+
+    it { should respond_to(:tag) }
+    it { should respond_to(:tag!) }
+    it { should respond_to(:untag) }
+    it { should respond_to(:untag!) }
+    it { should respond_to(:tag_list) }
+    it { should respond_to(:taggings) }
+
+    describe ".tag" do
+      before :all do
+        @resource = create_taggable
+        @taggings = @resource.tag([@foo_tag, @bar_tag])
+      end
+
+      it "should set new taggings" do
+        @taggings.should eql(@resource.taggings)
+      end
+
+      it "should not create new taggings" do
+        @resource.tags.should be_empty
+      end
+    end
+
+    describe ".tag!" do
+      before :all do
+        @resource = create_taggable
+        @taggings = @resource.tag!([@foo_tag, @bar_tag])
+      end
+
+      it "should create new taggings" do
+        @resource.reload.tags.should include(@foo_tag, @bar_tag)
+      end
+    end
+
+    describe ".untag" do
+      describe "all" do
+        before :all do
+          @resource = create_taggable
+          @taggings = @resource.tag!([@foo_tag, @bar_tag])
+
+          @resource.untag
+        end
+
+        it "should remove the taggings from the collection" do
+          @resource.taggings.should be_empty
+        end
+
+        it "should not destroy the taggings" do
+          @resource.reload.tags.should_not be_empty
+        end
+      end
+
+      describe "specific names" do
+        before :all do
+          @resource = create_taggable
+          @taggings = @resource.tag!([@foo_tag, @bar_tag])
+
+          @resource.untag([@foo_tag])
+        end
+
+        it "should remove the related tagging from the collection" do
+          @resource.taggings.size.should eql(1)
+        end
+
+        it "should remove the related tag" do
+          @resource.tags.should_not include(@foo_tag)
+        end
+      end
+
+      describe "when save is called" do
+        before :all do
+          @resource = create_taggable
+          @taggings = @resource.tag!([@foo_tag, @bar_tag])
+
+          @resource.untag
+        end
+
+        it "should return true" do
+          pending "Currently DataMapper doesn't support saving an empty collection" do
+            @resource.save.should be(true)
+          end
+        end
+
+        it "should destroy taggings" do
+          pending "Currently DataMapper doesn't support saving an empty collection" do
+            @resource.reload.taggings.should be_empty
+          end
+        end
+
+        it "should destroy tags" do
+          pending "Currently DataMapper doesn't support saving an empty collection" do
+            @resource.reload.tags.should be_empty
+          end
+        end
+      end
+    end
+
+    describe ".untag!" do
+      describe "all" do
+        before :all do
+          @resource = create_taggable
+          @taggings = @resource.tag!([@foo_tag, @bar_tag])
+
+          @resource.untag!
+        end
+
+        it "should destroy the taggings" do
+          @resource.reload.taggings.should be_empty
+        end
+      end
+
+      describe "specific names" do
+        before :all do
+          @resource = create_taggable
+          @taggings = @resource.tag!([@foo_tag, @bar_tag])
+
+          @resource.untag!([@foo_tag])
+          @resource.reload
+        end
+
+        subject { @resource.tags }
+
+        it { should_not include(@foo_tag) }
+        it { should include(@bar_tag) }
+      end
+    end
+
+    describe ".tag_list=" do
+      describe "with a list of tag names" do
+        describe "with blank values" do
+          before :all do
+            @resource = create_taggable(:tag_list => "foo, , ,bar, , ")
+          end
+
+          it "should add new tags and reject blank names" do
+            @resource.reload.tags.should include(Tag["foo"], Tag["bar"])
+          end
+        end
+
+        describe "when tags are removed and added" do
+          before :all do
+            @resource = create_taggable(:tag_list => "foo, bar")
+            @resource.update(:tag_list => "foo, bar, pub")
+          end
+
+          it "should add new tags" do
+            @resource.reload.tags.should include(Tag["bar"], Tag["bar"], Tag["pub"])
+          end
+        end
+
+        describe "when tags are added" do
+          before :all do
+            @resource = create_taggable(:tag_list => "foo, bar")
+            @resource.update(:tag_list => "bar, pub")
+          end
+
+          it "should add new tags" do
+            @resource.reload.tags.should include(Tag["bar"], Tag["pub"])
+          end
+
+          it "should remove tags" do
+            @resource.reload.tags.should_not include(Tag["foo"])
+          end
+        end
+      end
+
+      describe "when no list of tag names is given" do
+        before :all do
+          @resource = create_taggable(:tag_list => "foo, bar")
+          @resource.update(:tag_list => "")
+        end
+
+        it "should destroy taggings" do
+          @resource.reload.taggings.should be_blank
+        end
+
+        it "should remove the tags" do
+          @resource.reload.tags.should be_blank
+        end
+      end
+    end
+
+    describe ".tag_list" do
+      before :all do
+        @tag_names = %w(red green blue)
+        @expected  = @tag_names.join(', ')
+        @resource  = create_taggable(:tag_list => @expected)
+      end
+
+      it "should return the list of tag names" do
+        @resource.tag_list.should eql(@expected)
+      end
+    end
+  end
+end
+