bborn-acts_as_taggable_on_steroids 2.0.beta3 → 2.1

data/README.markdown

@@ -0,0 +1,157 @@
+ActsAsTaggableOnSteroids
+========================
+
+[![Build Status](https://secure.travis-ci.org/bborn/acts_as_taggable_on_steroids.png)](http://travis-ci.org/bborn/acts_as_taggable_on_steroids)
+
+  
+Instructions
+------------
+
+This plugin is based on acts_as_taggable by DHH but includes extras
+such as tests, smarter tag assignment, and tag cloud calculations.
+
+Installation
+------------
+
+	gem "bborn-acts_as_taggable_on_steroids"
+
+
+Usage
+=====
+
+Prepare database
+----------------
+
+Generate and apply the migration:
+
+	ruby script/generate acts_as_taggable_migration
+	rake db:migrate
+
+Basic tagging
+-------------
+
+Let's suppose users have many posts and we want those posts to have tags.
+The first step is to add `acts_as_taggable` to the Post class:
+
+	class Post < ActiveRecord::Base
+		acts_as_taggable
+
+		belongs_to :user
+	end
+  
+We can now use the tagging methods provided by acts_as_taggable, `#tag_list` and `#tag_list=`. Both these
+methods work like regular attribute accessors.
+
+	p = Post.find(:first)
+	p.tag_list # []
+	p.tag_list = "Funny, Silly"
+	p.save
+	p.tag_list # ["Funny", "Silly"]
+  
+You can also add or remove arrays of tags.
+
+	p.tag_list.add("Great", "Awful")
+	p.tag_list.remove("Funny")
+  
+In your views you should use something like the following:
+
+	<%= f.label :tag_list %>
+	<%= f.text_field :tag_list, :size => 80 %>
+
+Finding tagged objects
+----------------------
+
+To retrieve objects tagged with a certain tag, use find_tagged_with.
+
+	Post.tagged_with('Funny, Silly')
+  
+By default, find_tagged_with will find objects that have any of the given tags. To
+find only objects that are tagged with all the given tags, use match_all.
+
+	Post.tagged_with('Funny, Silly', :match_all => true)
+  
+See `ActsAsTaggable::ActiveRecordExtension::InstanceMethods` for more methods and options.
+
+Tag cloud calculations
+----------------------
+
+To construct tag clouds, the frequency of each tag needs to be calculated.
+Because we specified `acts_as_taggable` on the `Post` class, we can
+get a calculation of all the tag counts by using `Post.tag_counts`. But what if we wanted a tag count for
+an single user's posts? To achieve this we call tag_counts on the association:
+
+	User.find(:first).posts.tag_counts
+  
+A helper is included to assist with generating tag clouds. Include it in your helper file:
+
+	module ApplicationHelper
+	  include TagsHelper
+	end
+  
+You can also use the `counts` method on `Tag` to get the counts for all tags in the database.
+
+	Tag.counts
+
+Here is an example that generates a tag cloud.
+
+Controller:
+
+	class PostController < ApplicationController
+	  def tag_cloud
+	    @tags = Post.tag_counts
+	  end
+	end
+  
+View:
+
+	<% tag_cloud @tags, %w(css1 css2 css3 css4) do |tag, css_class| %>
+	  <%= link_to tag.name, { :action => :tag, :id => tag.name }, :class => css_class %>
+	<% end %>
+  
+CSS:
+
+	.css1 { font-size: 1.0em; }
+	.css2 { font-size: 1.2em; }
+	.css3 { font-size: 1.4em; }
+	.css4 { font-size: 1.6em; }
+
+Caching
+-------
+
+It is useful to cache the list of tags to reduce the number of queries executed. To do this,
+add a column named `cached_tag_list` to the model which is being tagged. The column should be long enough to hold
+the full tag list and must have a default value of null, not an empty string.
+
+	class CachePostTagList < ActiveRecord::Migration
+	  def self.up
+	    add_column :posts, :cached_tag_list, :string
+	  end
+	end
+
+	class Post < ActiveRecord::Base
+	  acts_as_taggable
+  
+	  # The caching column defaults to cached_tag_list, but can be changed:
+	  # 
+	  # set_cached_tag_list_column_name "my_caching_column_name"
+	end
+
+The details of the caching are handled for you. Just continue to use the tag_list accessor as you normally would.
+Note that the cached tag list will not be updated if you directly create Tagging objects or manually append to the
+`tags` or `taggings` associations. To update the cached tag list you should call `save_cached_tag_list` manually.
+
+Delimiter
+---------
+
+If you want to change the delimiter used to parse and present tags, set TagList.delimiter.
+For example, to use spaces instead of commas, add the following to your `application.rb`:
+
+	TagList.delimiter = " "
+
+Unused tags
+-----------
+
+Set Tag.destroy_unused to remove tags when they are no longer being
+used to tag any objects. Defaults to false.
+
+	Tag.destroy_unused = true

data/lib/acts_as_taggable.rb

@@ -1,246 +1,2 @@
-require 'tag_list'
-require 'tag'
-require 'tagging'
-require 'tags_helper'
-
-module ActiveRecord #:nodoc:
-  module Acts #:nodoc:
-    module Taggable #:nodoc:
-      def self.included(base)
-        base.extend(ClassMethods)
-      end
-      
-      module ClassMethods
-        def acts_as_taggable
-          has_many :taggings, :as => :taggable, :dependent => :destroy, :include => :tag
-          has_many :tags, :through => :taggings
-          
-          before_save :save_cached_tag_list
-          after_save  :save_tags
-          
-          include ActiveRecord::Acts::Taggable::InstanceMethods
-          extend ActiveRecord::Acts::Taggable::SingletonMethods
-          
-          alias_method_chain :reload, :tag_list
-        end
-        
-        def cached_tag_list_column_name
-          "cached_tag_list"
-        end
-        
-        def set_cached_tag_list_column_name(value = nil, &block)
-          define_attr_method :cached_tag_list_column_name, value, &block
-        end
-      end
-      
-      module SingletonMethods
-        # Pass either a tag, string, or an array of strings or tags.
-        # 
-        # Options:
-        # - +:match_any+ - match any of the given tags (default).
-        # - +:match_all+ - match all of the given tags.
-        # 
-        def tagged_with(tags, options = {})
-          tags = tags.is_a?(Array) ? TagList.new(tags.map(&:to_s)) : TagList.from(tags)
-          return [] if tags.empty?
-          
-          records = select("DISTINCT #{quoted_table_name}.*")
-          
-          if options[:match_all]
-            records.search_all_tags(tags)
-          else
-            records.search_any_tags(tags)
-          end
-        end
-        
-        # Matches records that have none of the given tags.
-        def not_tagged_with(tags)
-          tags = tags.is_a?(Array) ? TagList.new(tags.map(&:to_s)) : TagList.from(tags)
-          
-          sub = Tagging.select("#{Tagging.table_name}.taggable_id").joins(:tag).
-            where(:taggable_type => base_class.name, "#{Tag.table_name}.name" => tags)
-          
-          where("#{quoted_table_name}.#{primary_key} NOT IN (" + sub.to_sql + ")")
-        end
-        
-        # Returns an array of related tags. Related tags are all the other tags
-        # that are found on the models tagged with the provided tags.
-        def related_tags(tags)
-          search_related_tags(tags)
-        end
-        
-        # Counts the number of occurences of all tags.
-        # See <tt>Tag.counts</tt> for options.
-        def tag_counts(options = {})
-          tags = Tag.joins(:taggings).
-            where("#{Tagging.table_name}.taggable_type" => base_class.name)
-          
-          if options[:tags]
-            tags = tags.where("#{Tag.table_name}.name" => options.delete(:tags))
-          end
-          
-          unless descends_from_active_record?
-            tags = tags.joins("INNER JOIN #{quoted_table_name} ON " +
-              "#{quoted_table_name}.#{primary_key} = #{Tagging.quoted_table_name}.taggable_id")
-            tags = tags.where(type_condition)
-          end
-          
-          if scoped != unscoped
-            sub  = scoped.except(:select).select("#{quoted_table_name}.#{primary_key}")
-            tags = tags.where("#{Tagging.quoted_table_name}.taggable_id IN (#{sub.to_sql})")
-          end
-          
-          tags.counts(options)
-        end
-        
-        # Returns an array of related tags.
-        # Related tags are all the other tags that are found on the models
-        # tagged with the provided tags.
-        # 
-        # Pass either a tag, string, or an array of strings or tags.
-        # 
-        # Options:
-        # - +:order+ - SQL Order how to order the tags. Defaults to "count_all DESC, tags.name".
-        # - +:include+
-        # 
-        # DEPRECATED: use #related_tags instead.
-        def find_related_tags(tags, options = {})
-          rs = related_tags(tags).order(options[:order] || "count DESC, #{Tag.quoted_table_name}.name")
-          rs = rs.includes(options[:include]) if options[:include]
-          rs
-        end
-        
-        # Pass either a tag, string, or an array of strings or tags.
-        # 
-        # Options:
-        # - +:exclude+    - Find models that are not tagged with the given tags
-        # - +:match_all+  - Find models that match all of the given tags, not just one
-        # - +:conditions+ - A piece of SQL conditions to add to the query
-        # - +:include+
-        # 
-        # DEPRECATED: use #tagged_with and #not_tagged_with instead.
-        def find_tagged_with(*args)
-          options = args.extract_options!
-          tags = args.first
-          
-          records = self
-          records = records.where(options[:conditions]) if options[:conditions]
-          records = records.includes(options[:include]) if options[:include]
-          records = records.order(options[:order])      if options[:order]
-          
-          if options[:exclude]
-            records.not_tagged_with(tags)
-          else
-            records.tagged_with(tags, options)
-          end
-        end
-        
-        def caching_tag_list?
-          column_names.include?(cached_tag_list_column_name)
-        end
-        
-        protected
-          def joins_tags(options = {}) # :nodoc:
-            options[:suffix] = "_#{options[:suffix]}" if options[:suffix]
-            
-            taggings_alias = connection.quote_table_name(Tagging.table_name + options[:suffix].to_s)
-            tags_alias = connection.quote_table_name(Tag.table_name + options[:suffix].to_s)
-            
-            taggings = "INNER JOIN #{Tagging.quoted_table_name} AS #{taggings_alias} " +
-              "ON #{taggings_alias}.taggable_id = #{quoted_table_name}.#{primary_key} " +
-              "AND #{taggings_alias}.taggable_type = #{quote_value(base_class.name)}"
-            
-            tags = "INNER JOIN #{Tag.quoted_table_name} AS #{tags_alias} " +
-              "ON #{tags_alias}.id = #{taggings_alias}.tag_id "
-            tags += "AND #{tags_alias}.name LIKE #{quote_value(options[:tag_name])}" if options[:tag_name]
-            
-            joins([taggings, tags])
-          end
-          
-          def search_all_tags(tags)
-            records = self
-            
-            tags.dup.each_with_index do |tag_name, index|
-              records = records.joins_tags(:suffix => index, :tag_name => tag_name)
-            end
-            
-            records
-          end
-          
-          def search_any_tags(tags)
-            joins(:tags).where(Tag.arel_table[:name].matches_any(tags.dup))
-          end
-          
-          def search_related_tags(tags)
-            tags = tags.is_a?(Array) ? TagList.new(tags.map(&:to_s)) : TagList.from(tags)
-            sub = select("#{quoted_table_name}.#{primary_key}").search_any_tags(tags)
-            _tags = tags.map { |tag| tag.downcase }
-            
-            Tag.select("#{Tag.quoted_table_name}.*, COUNT(#{Tag.quoted_table_name}.id) AS count").
-              joins(:taggings).
-              where("#{Tagging.table_name}.taggable_type" => base_class.name).
-              where("#{Tagging.quoted_table_name}.taggable_id IN (" + sub.to_sql + ")").
-              group("#{Tag.quoted_table_name}.name").
-              having(Tag.arel_table[:name].does_not_match_all(_tags))
-          end
-      end
-      
-      module InstanceMethods
-        def tag_list
-          return @tag_list if @tag_list
-          
-          if self.class.caching_tag_list? and !(cached_value = send(self.class.cached_tag_list_column_name)).nil?
-            @tag_list = TagList.from(cached_value)
-          else
-            @tag_list = TagList.new(*tags.map(&:name))
-          end
-        end
-        
-        def tag_list=(value)
-          @tag_list = TagList.from(value)
-        end
-        
-        def save_cached_tag_list
-          if self.class.caching_tag_list?
-            self[self.class.cached_tag_list_column_name] = tag_list.to_s
-          end
-        end
-        
-        def save_tags
-          return unless @tag_list
-          
-          new_tag_names = @tag_list - tags.map(&:name)
-          old_tags = tags.reject { |tag| @tag_list.include?(tag.name) }
-          
-          self.class.transaction do
-            if old_tags.any?
-              taggings.where(:tag_id => old_tags.map(&:id)).each(&:destroy)
-              taggings.reset
-            end
-            
-            new_tag_names.each do |new_tag_name|
-              tags << Tag.find_or_create_with_like_by_name(new_tag_name)
-            end
-          end
-          
-          true
-        end
-        
-        # Calculate the tag counts for the tags used by this model.
-        # See <tt>Tag.counts</tt> for available options.
-        def tag_counts(options = {})
-          return [] if tag_list.blank?
-          self.class.tag_counts(options.merge(:tags => tag_list))
-        end
-        
-        def reload_with_tag_list(*args) #:nodoc:
-          @tag_list = nil
-          reload_without_tag_list(*args)
-        end
-      end
-    end
-  end
-end
-
-ActiveRecord::Base.send(:include, ActiveRecord::Acts::Taggable)
 
+require File.join(File.dirname(__FILE__), 'acts_as_taggable/engine')

data/lib/acts_as_taggable/active_record_extension.rb

@@ -0,0 +1,246 @@
+
+module ActsAsTaggable #:nodoc:
+  module ActiveRecordExtension
+    extend ActiveSupport::Concern    
+    
+    included do      
+      self.extend(ClassMethods)
+    end
+    
+    module ClassMethods
+      def acts_as_taggable
+        has_many :taggings, :as => :taggable, :dependent => :destroy, :include => :tag
+        has_many :tags, :through => :taggings
+        
+        before_save :save_cached_tag_list
+        after_save  :save_tags
+        
+        include ActsAsTaggable::ActiveRecordExtension::InstanceMethods
+        extend ActsAsTaggable::ActiveRecordExtension::SingletonMethods
+        
+        alias_method_chain :reload, :tag_list
+      end
+      
+      def cached_tag_list_column_name
+        "cached_tag_list"
+      end
+      
+      def set_cached_tag_list_column_name(value = nil, &block)
+        define_attr_method :cached_tag_list_column_name, value, &block
+      end
+    end
+    
+    module SingletonMethods
+      # Pass either a tag, string, or an array of strings or tags.
+      # 
+      # Options:
+      # - +:match_any+ - match any of the given tags (default).
+      # - +:match_all+ - match all of the given tags.
+      # 
+      def tagged_with(tags, options = {})
+        tags = tags.is_a?(Array) ? TagList.new(tags.map(&:to_s)) : TagList.from(tags)
+        return [] if tags.empty?
+        
+        records = select("DISTINCT #{quoted_table_name}.*")
+        
+        if options[:match_all]
+          records.search_all_tags(tags)
+        else
+          records.search_any_tags(tags)
+        end
+      end
+      
+      # Matches records that have none of the given tags.
+      def not_tagged_with(tags)
+        tags = tags.is_a?(Array) ? TagList.new(tags.map(&:to_s)) : TagList.from(tags)
+        
+        sub = Tagging.select("#{Tagging.table_name}.taggable_id").joins(:tag).
+          where(:taggable_type => base_class.name, "#{Tag.table_name}.name" => tags)
+        
+        where("#{quoted_table_name}.#{primary_key} NOT IN (" + sub.to_sql + ")")
+      end
+      
+      # Returns an array of related tags. Related tags are all the other tags
+      # that are found on the models tagged with the provided tags.
+      def related_tags(tags)
+        search_related_tags(tags)
+      end
+      
+      # Counts the number of occurences of all tags.
+      # See <tt>Tag.counts</tt> for options.
+      def tag_counts(options = {})
+        tags = Tag.joins(:taggings).
+          where("#{Tagging.table_name}.taggable_type" => base_class.name)
+        
+        if options[:tags]
+          tags = tags.where("#{Tag.table_name}.name" => options.delete(:tags))
+        end
+        
+        unless descends_from_active_record?
+          tags = tags.joins("INNER JOIN #{quoted_table_name} ON " +
+            "#{quoted_table_name}.#{primary_key} = #{Tagging.quoted_table_name}.taggable_id")
+          tags = tags.where(type_condition)
+        end
+        
+        if scoped != unscoped
+          sub  = scoped.except(:select).select("#{quoted_table_name}.#{primary_key}")
+          tags = tags.where("#{Tagging.quoted_table_name}.taggable_id IN (#{sub.to_sql})")
+        end
+        
+        tags.counts(options)
+      end
+      
+      # Returns an array of related tags.
+      # Related tags are all the other tags that are found on the models
+      # tagged with the provided tags.
+      # 
+      # Pass either a tag, string, or an array of strings or tags.
+      # 
+      # Options:
+      # - +:order+ - SQL Order how to order the tags. Defaults to "count_all DESC, tags.name".
+      # - +:include+
+      # 
+      # DEPRECATED: use #related_tags instead.
+      def find_related_tags(tags, options = {})
+        ActiveSupport::Deprecation.warn "#find_related_tags() is deprecated and will be removed in the next release. Use #related_tags", caller
+        
+        rs = related_tags(tags).order(options[:order] || "count DESC, #{Tag.quoted_table_name}.name")
+        rs = rs.includes(options[:include]) if options[:include]
+        rs
+      end
+      
+      # Pass either a tag, string, or an array of strings or tags.
+      # 
+      # Options:
+      # - +:exclude+    - Find models that are not tagged with the given tags
+      # - +:match_all+  - Find models that match all of the given tags, not just one
+      # - +:conditions+ - A piece of SQL conditions to add to the query
+      # - +:include+
+      # 
+      # DEPRECATED: use #tagged_with and #not_tagged_with instead.
+      def find_tagged_with(*args)
+        ActiveSupport::Deprecation.warn "#find_tagged_with() is deprecated and will be removed in the next release. Use #tagged_with and #not_tagged_with instead", caller        
+        options = args.extract_options!
+        tags = args.first
+        
+        records = self
+        records = records.where(options[:conditions]) if options[:conditions]
+        records = records.includes(options[:include]) if options[:include]
+        records = records.order(options[:order])      if options[:order]
+        
+        if options[:exclude]
+          records.not_tagged_with(tags)
+        else
+          records.tagged_with(tags, options)
+        end
+      end
+      
+      def caching_tag_list?
+        column_names.include?(cached_tag_list_column_name)
+      end
+      
+      protected
+        def joins_tags(options = {}) # :nodoc:
+          options[:suffix] = "_#{options[:suffix]}" if options[:suffix]
+          
+          taggings_alias = connection.quote_table_name(Tagging.table_name + options[:suffix].to_s)
+          tags_alias = connection.quote_table_name(Tag.table_name + options[:suffix].to_s)
+          
+          taggings = "INNER JOIN #{Tagging.quoted_table_name} AS #{taggings_alias} " +
+            "ON #{taggings_alias}.taggable_id = #{quoted_table_name}.#{primary_key} " +
+            "AND #{taggings_alias}.taggable_type = #{quote_value(base_class.name)}"
+          
+          tags = "INNER JOIN #{Tag.quoted_table_name} AS #{tags_alias} " +
+            "ON #{tags_alias}.id = #{taggings_alias}.tag_id "
+          tags += "AND #{tags_alias}.name LIKE #{quote_value(options[:tag_name])}" if options[:tag_name]
+          
+          joins([taggings, tags])
+        end
+        
+        def search_all_tags(tags)
+          records = self
+          
+          tags.dup.each_with_index do |tag_name, index|
+            records = records.joins_tags(:suffix => index, :tag_name => tag_name)
+          end
+          
+          records
+        end
+        
+        def search_any_tags(tags)
+          joins(:tags).where(Tag.arel_table[:name].matches_any(tags.dup))
+        end
+        
+        def search_related_tags(tags)
+          tags = tags.is_a?(Array) ? TagList.new(tags.map(&:to_s)) : TagList.from(tags)
+
+          return where('1=0') if tags.empty?
+          
+          sub = select("#{quoted_table_name}.#{primary_key}").search_any_tags(tags)
+          _tags = tags.map { |tag| tag.downcase }
+          
+          Tag.select("#{Tag.quoted_table_name}.*, COUNT(#{Tag.quoted_table_name}.id) AS count").
+            joins(:taggings).
+            where("#{Tagging.table_name}.taggable_type" => base_class.name).
+            where("#{Tagging.quoted_table_name}.taggable_id IN (" + sub.to_sql + ")").
+            group("#{Tag.quoted_table_name}.name").
+            having(Tag.arel_table[:name].does_not_match_all(_tags))
+        end
+    end
+    
+    module InstanceMethods
+      def tag_list
+        return @tag_list if @tag_list
+        
+        if self.class.caching_tag_list? and !(cached_value = send(self.class.cached_tag_list_column_name)).nil?
+          @tag_list = TagList.from(cached_value)
+        else
+          @tag_list = TagList.new(*tags.map(&:name))
+        end
+      end
+      
+      def tag_list=(value)
+        @tag_list = TagList.from(value)
+      end
+      
+      def save_cached_tag_list
+        if self.class.caching_tag_list?
+          self[self.class.cached_tag_list_column_name] = tag_list.to_s
+        end
+      end
+      
+      def save_tags
+        return unless @tag_list
+        
+        new_tag_names = @tag_list - tags.map(&:name)
+        old_tags = tags.reject { |tag| @tag_list.include?(tag.name) }
+        
+        self.class.transaction do
+          if old_tags.any?
+            taggings.where(:tag_id => old_tags.map(&:id)).each(&:destroy)
+            taggings.reset
+          end
+          
+          new_tag_names.each do |new_tag_name|
+            tags << Tag.find_or_create_with_like_by_name(new_tag_name)
+          end
+        end
+        
+        true
+      end
+      
+      # Calculate the tag counts for the tags used by this model.
+      # See <tt>Tag.counts</tt> for available options.
+      def tag_counts(options = {})
+        return [] if tag_list.blank?
+        self.class.tag_counts(options.merge(:tags => tag_list))
+      end
+      
+      def reload_with_tag_list(*args) #:nodoc:
+        @tag_list = nil
+        reload_without_tag_list(*args)
+      end
+    end
+  end
+end
+