Many contributed features

.gitignore

@@ -1 +1,3 @@
-.redcar
+.redcar
+.bundle
+rdoc

.rspec

@@ -0,0 +1 @@
+--color

Gemfile

@@ -0,0 +1,4 @@
+# Use `bundle install` in order to install these gems
+# Use `bundle exec rake` in order to run the specs using the bundle
+source "http://rubygems.org"
+gemspec

Gemfile.lock

@@ -0,0 +1,46 @@
+PATH
+  remote: .
+  specs:
+    mongoid_taggable (0.3.0)
+      mongoid (~> 2.0.0.beta.20)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activemodel (3.0.5)
+      activesupport (= 3.0.5)
+      builder (~> 2.1.2)
+      i18n (~> 0.4)
+    activesupport (3.0.5)
+    bson (1.2.4)
+    builder (2.1.2)
+    database_cleaner (0.6.5)
+    diff-lcs (1.1.2)
+    i18n (0.5.0)
+    mongo (1.2.4)
+      bson (>= 1.2.4)
+    mongoid (2.0.0.rc.7)
+      activemodel (~> 3.0)
+      mongo (~> 1.2)
+      tzinfo (~> 0.3.22)
+      will_paginate (~> 3.0.pre)
+    rake (0.8.7)
+    rspec (2.1.0)
+      rspec-core (~> 2.1.0)
+      rspec-expectations (~> 2.1.0)
+      rspec-mocks (~> 2.1.0)
+    rspec-core (2.1.0)
+    rspec-expectations (2.1.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.1.0)
+    tzinfo (0.3.24)
+    will_paginate (3.0.pre2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  database_cleaner (~> 0.6.0)
+  mongoid_taggable!
+  rake (~> 0.8.7)
+  rspec (~> 2.1.0)

README.textile

@@ -4,7 +4,7 @@ Mongoid Taggable provides some helpers to create taggable documents.
 
 h2. Installation
 
-You can simple install from rubygems:
+You can simply install from rubygems:
 
 bc. gem install mongoid_taggable
 
@@ -18,17 +18,19 @@ bc. script/plugin install git://github.com/wilkerlucio/mongoid_taggable.git
 
 h2. Basic Usage
 
-To make a document taggable you just need to include Mongoid::Taggable into your document:
+To make a document taggable you need to include Mongoid::Taggable into your document and call the @taggable@ macro with optional arguments:
 
 bc.. class Post
   include Mongoid::Document
   include Mongoid::Taggable
 
   field :title
   field :content
+
+  taggable
 end
 
-p. Them in your form:
+p. Then in your form, for example:
 
 bc.. <% form_for @post do |f| %>
   <p>
@@ -41,22 +43,32 @@ bc.. <% form_for @post do |f| %>
   </p>
   <p>
     <%= f.label :tags %><br />
-    <%= f.text_field :tags %>
+    <%= text_field_tag 'post[tags]', (@post.tags.join(', ') if @post.tags) %>
   </p>
   <p>
     <button type="submit">Send</button>
   </p>
 <% end %>
 
-p. In this case, the text fields for tags should receive the list of tags separated by comma (below in this document you will see how to change the separator)
+p. You can of course use helpers or a @FormBuilder@ extension to express this in a prettier way. In this case, the text field for tags should receive the list of tags separated by comma (below in this document you will see how to change the separator).
+
+p. Your document will have a custom @tags=@ setter which can accept either an ordinary Array or this separator-delineated String.
+
+h2. Tag Aggregation with Counts
 
-p. Then your document will have the @tags@ and @tags_array@ getter and setter. The @tags@ you use as a plain string with tags separated by comma, and the @tags_array@ is an array with tags. These two properties are automatically synchronized.
+This lib can automatically create an aggregate collection of tags and their counts for you, updated as documents are saved. This is useful for getting a list of all tags used in documents of this collection or to create a tag cloud. This is disabled by default for sake of performance where it is unneeded -- see the following example to understand how to use it:
+
+bc.. class Post
+  include Mongoid::Document
+  include Mongoid::Taggable
 
-h2. Tags Indexing
+  field :title
+  field :content
 
-This lib will automatically create an index of tags and their counts for you after saving the document, useful for getting a list of all tags used in documents of this collection or to create a tag cloud. See the following example to understand how to use it:
+  taggable :aggregation => true
+end
 
-bc.. Post.create!(:tags => "food,ant,bee")
+Post.create!(:tags => "food,ant,bee")
 Post.create!(:tags => "juice,food,bee,zip")
 Post.create!(:tags => "honey,strip,food")
 
@@ -72,28 +84,17 @@ Post.tags_with_weight # will retrieve:
 #   ['zip', 1]
 # ]
 
-p. If you don't want to use this feature, it is good to disable it to improve performance:
-
-bc.. class Post
-  include Mongoid::Document
-  include Mongoid::Taggable
-
-  disable_tags_index! # will disable index creation
-
-  field :title
-  field :content
-end
-
 h2. Changing default separator
 
-To change the default separator you may call the @tags_separator@ class method:
+To change the default separator you may pass a @separator@ argument to the macro:
 
 bc.. class Post
   include Mongoid::Document
   include Mongoid::Taggable
 
-  tags_separator ';' # will change tags separator to ;
-
   field :title
   field :content
+
+  taggable :separator => ' '    # tags will be delineated by spaces
 end
+

Rakefile

@@ -1,23 +1,19 @@
+require 'bundler'
+Bundler.setup
+
 require 'rake'
 require 'rake/rdoctask'
 require 'rspec'
 require 'rspec/core/rake_task'
 
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gemspec|
-    gemspec.name = "mongoid_taggable"
-    gemspec.version = "0.1.2"
-    gemspec.summary = "Mongoid taggable behaviour"
-    gemspec.description = "Mongoid Taggable provides some helpers to create taggable documents."
-    gemspec.email = "wilkerlucio@gmail.com"
-    gemspec.homepage = "http://github.com/wilkerlucio/mongo_taggable"
-    gemspec.authors = ["Wilker Lucio", "Kris Kowalik"]
-  end
-rescue LoadError
-  puts "Jeweler not available. Install it with: gem install jeweler"
+task :gem => :build
+task :build do
+  system "gem build mongoid_taggable.gemspec"
 end
 
+task :install => :build do
+  system "gem install mongoid_taggable-#{Mongoid::Taggable::VERSION}.gem"
+end
 
 desc 'Default: run unit tests.'
 task :default => :spec
@@ -34,3 +30,6 @@ Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
+
+desc 'Default: run unit tests.'
+task :default => :spec

lib/mongoid/taggable.rb

@@ -13,70 +13,102 @@
 # limitations under the License.
 
 module Mongoid::Taggable
-  def self.included(base)
-    # create fields for tags and index it
-    base.field :tags_array, :type => Array
-    base.index [['tags_array', Mongo::ASCENDING]]
-
-    # add callback to save tags index
-    base.after_save do |document|
-      document.class.save_tags_index!
-    end
-
-    # extend model
-    base.extend         ClassMethods
-    base.send :include, InstanceMethods
-
-    # enable indexing as default
-    base.enable_tags_index!
+  extend ActiveSupport::Concern
+
+  included do
+    class_inheritable_reader :tags_field
+    class_inheritable_accessor :tags_separator, :tag_aggregation,
+      :instance_writer => false
+
+    delegate :convert_string_tags_to_array, :aggregate_tags, :to => 'self.class'
+
+    set_callback :create,  :after, :aggregate_tags
+    set_callback :destroy, :after, :aggregate_tags
+    set_callback :save,    :after, :aggregate_tags, :if => proc { previous_changes.include?(tags_field.to_s) }
   end
-  
+
   module ClassMethods
+    # Macro to declare a document class as taggable, specify field name
+    # for tags, and set options for tagging behavior.
+    #
+    # @example Define a taggable document.
+    #
+    #   class Article
+    #     include Mongoid::Document
+    #     include Mongoid::Taggable
+    #     taggable :keywords, :separator => ' ', :aggregation => true
+    #   end
+    #
+    # @param [ Symbol ] field The name of the field for tags.
+    # @param [ Hash ] options Options for taggable behavior.
+    #
+    # @option options [ String ] :separator The tag separator to
+    #   convert from; defaults to ','
+    # @option options [ true, false ] :aggregation Whether or not to
+    #   aggregate counts of tags within the document collection using
+    #   map/reduce; defaults to false
+    def taggable(*args)
+      options = args.extract_options!
+      options.reverse_merge!(
+        :separator => ',',
+        :aggregation => false
+      )
+
+      write_inheritable_attribute(:tags_field, args.blank? ? :tags : args.shift)
+      self.tags_separator  = options[:separator]
+      self.tag_aggregation = options[:aggregation]
+
+      field tags_field, :type => Array
+      index tags_field
+
+      define_tag_field_accessors(tags_field)
+    end
+
     # get an array with all defined tags for this model, this list returns
     # an array of distinct ordered list of tags defined in all documents
     # of this model
     def tags
-      db = Mongoid::Config.master
-      db.collection(tags_index_collection).find.to_a.map{ |r| r["_id"] }
+      db.collection(tags_aggregation_collection).find.to_a.map{ |r| r["_id"] }
     end
 
-    # retrieve the list of tags with weight(count), this is usefull for
+    # retrieve the list of tags with weight(count), this is useful for
     # creating tag clouds
     def tags_with_weight
-      db = Mongoid::Config.master
-      db.collection(tags_index_collection).find.to_a.map{ |r| [r["_id"], r["value"]] }
+      db.collection(tags_aggregation_collection).find.to_a.map{ |r| [r["_id"], r["value"]] }
     end
 
-    def disable_tags_index!
-      @do_tags_index = false
+    # Find documents tagged with all tags passed as a parameter, given
+    # as an Array or a String using the configured separator.
+    #
+    # @example Find matching all tags in an Array.
+    #   Article.tagged_with(['ruby', 'mongodb'])
+    # @example Find matching all tags in a String.
+    #   Article.tagged_with('ruby, mongodb')
+    #
+    # @param [ Array<String, Symbol>, String ] _tags Tags to match.
+    # @return [ Criteria ] A new criteria.
+    def tagged_with(_tags)
+      _tags = convert_string_tags_to_array(_tags) if _tags.is_a? String
+      criteria.all_in(tags_field => _tags)
     end
 
-    def enable_tags_index!
-      @do_tags_index = true
+    # Collection name for storing results of tag count aggregation
+    def tags_aggregation_collection
+      @tags_aggregation_collection ||= "#{collection_name}_tags_aggregation"
     end
 
-    def tags_separator(separator = nil)
-      @tags_separator = separator if separator
-      @tags_separator || ','
-    end
-
-    def tags_index_collection
-      "#{collection_name}_tags_index"
-    end
-
-    def save_tags_index!
-      return unless @do_tags_index
-
-      db = Mongoid::Config.master
-      coll = db.collection(collection_name)
+    # Execute map/reduce operation to aggregate tag counts for document
+    # class
+    def aggregate_tags
+      return unless tag_aggregation
 
       map = "function() {
-        if (!this.tags_array) {
+        if (!this.#{tags_field}) {
           return;
         }
 
-        for (index in this.tags_array) {
-          emit(this.tags_array[index], 1);
+        for (index in this.#{tags_field}) {
+          emit(this.#{tags_field}[index], 1);
         }
       }"
 
@@ -90,17 +122,30 @@ def save_tags_index!
         return count;
       }"
 
-      coll.map_reduce(map, reduce, :out => tags_index_collection)
+      collection.master.map_reduce(map, reduce, :out => tags_aggregation_collection)
     end
-  end
 
-  module InstanceMethods
-    def tags
-      (tags_array || []).join(self.class.tags_separator)
+  private
+
+    # Helper method to convert a String to an Array based on the
+    # configured tag separator.
+    def convert_string_tags_to_array(_tags)
+      (_tags).split(tags_separator)
     end
 
-    def tags=(tags)
-      self.tags_array = tags.split(self.class.tags_separator).map(&:strip)
+    # Define modifier for the configured tag field name that overrides
+    # the default to transparently convert tags given as a String.
+    def define_tag_field_accessors(name)
+      define_method "#{name}_with_taggable=" do |values|
+        case values
+        when String
+          values = convert_string_tags_to_array(values)
+        when Array
+          values = values.inject([]) { |final, value| final.concat convert_string_tags_to_array(value) }
+        end
+        send("#{name}_without_taggable=", values.map(&:strip).reject(&:blank?))
+      end
+      alias_method_chain "#{name}=", :taggable
     end
   end
 end

lib/mongoid/taggable/version.rb

@@ -0,0 +1,6 @@
+# encoding: utf-8
+module Mongoid #:nodoc
+  module Taggable #:nodoc
+    VERSION = '0.3.0'
+  end
+end

lib/mongoid_taggable.rb

@@ -1 +1,3 @@
+require 'active_support/concern'
+
 require File.join(File.dirname(__FILE__), 'mongoid/taggable')