acts_as_taggable3 2.0.beta2

data/CHANGELOG

@@ -0,0 +1,212 @@
+[11 Jun 09]
+
+* Remove deprecated TagCountsExtension.
+
+* Update tests to use foxy fixtures [Jonas Wagner]
+
+* Allow hash conditions to be passed to Tag.counts [Jonas Wagner]
+
+[3 Jun 09]
+
+* Upgrade tests for Rails 2.3
+
+[18 Mar 09]
+
+* Change callbacks used to save tags.
+
+[18 Feb 09]
+
+* Greatly improve speed when using find_tagged_with and :match_all [notonthehighstreet.com].
+
+[17 Sep 08]
+
+* Sanitize scope conditions in find_options_for_tag_counts [Rémy-Christophe Schermesser]
+
+[23 Aug 08]
+
+* Fix tag_counts instance method when no tags are present.
+
+* Make tag_counts instance_method merge any :conditions passed to it.
+
+[30 Mar 08]
+
+* Make TagList.from accept array arguments.
+
+[29 Mar 08]
+
+* Improve parsing of quotes inside tags [Arturas Slajus].
+
+* Add Tag.counts method.
+
+[28 Mar 08]
+
+* Make Tag#taggings :dependent => :destroy.
+
+[27 Mar 08]
+
+* Fix documentation for tag_counts.
+
+[18 Mar 08]
+
+* Add TagList#toggle [Pete Yandell].
+
+# Add find_related_tags method [Austin Foncaier].
+
+[30 Jan 08]
+
+* Fix Tag.destroy_unused on Rails 2.0.
+
+[23 October 2007]
+
+* Make find_options_for_tag_counts and find_options_for_tagged_with dup their options.
+
+* Apply conditions properly in find_options_for_tag_counts.
+
+* Fix tag_cloud when no tags are present.
+
+[22 October 2007]
+
+* Fix find_tagged_with using :match_all and :include.
+
+* Use inner joins instead of left outer joins.
+
+[15 October 2007]
+
+* Make find_tagged_with correctly apply :conditions
+
+* Add Tag.destroy_unused option.
+
+[11 October 2007]
+
+* Make tag_counts work correctly with STI.
+
+[3 October 2007]
+
+* Improve documentation.
+
+* Fix TagsHelper and test.
+
+[2 October 2007]
+
+* Remove TagList.parse, use TagList.from instead.
+
+* Add :parse option to TagList#new, TagList#add, and TagList#remove.
+
+    tag_list = TagList.new("One, Two", :parse => true) # ["One", "Two"]
+    
+    tag_list # ["One", "Two"]
+    tag_list.add("Three, Four", :parse => true) # ["One", "Two", "Three", "Four"]
+    
+* Remove TagList#names.
+
+[29 September 2007]
+
+* Add TagsHelper to assist with generating tag clouds and provide a simple example.
+
+[27 September 2007]
+
+* Add #tag_counts method to get tag counts for a specific object's tags.
+
+* BACKWARDS INCOMPATIBILITY: Rename #find_options_for_tagged_with to #find_options_for_find_tagged_with
+
+[17 September 2007]
+
+* Fix clearing of cached tag list when all tags removed.
+
+[12 September 2007]
+
+* Make the TagList class inherit from Array.
+
+* Deprecate obsolete TagList#names.
+
+[6 September 2007]
+
+* Add TagList#include? and TagList#empty?
+
+[26 August 2007]
+
+* Remove deprecated Tag.delimiter. Use TagList.delimiter instead.
+
+[25 August 2007]
+
+* Make tag_counts work with has_many :through
+
+[23 August 2007]
+
+* Make search comparisons case-insensitive across different databases. [Moisés Machado]
+
+* Improve compatiblity with STI. [Moisés Machado]
+
+[25 July 2007]
+
+* Respect custom table names for the Tag and Tagging classes.
+
+* Fix the :exclude option for find_tagged_with
+
+[17 July 2007]
+
+* Make the migration work on edge rails
+
+[8 July 2007]
+
+* find_options_for_tagged_with should not alter its arguments
+
+[1 July 2007]
+
+* Fix incorrect tagging when the case of the tag list is changed.
+
+* Fix deprecated Tag.delimiter accessor.
+
+[23 June 2007]
+
+* Add validation to Tag model.
+
+* find_options_for_tagged_with should always return a hash.
+
+* find_tagged_with passing in no tags should return an empty array.
+
+* Improve compatibility with PostgreSQL.
+
+[21 June 2007]
+
+* Remove extra .rb from generated migration file name.
+
+[15 June 2007]
+
+* Introduce TagList class.
+
+* Various cleanups and improvements.
+
+* Use TagList.delimiter now, not Tag.delimiter. Tag.delimiter will be removed at some stage.
+
+[11 June 2007]
+
+* Restructure the creation of the options for find_tagged_with [Thijs Cadier]
+
+* Add an example migration with a generator.
+
+* Add caching.
+
+* Fix compatibility with Ruby < 1.8.6
+
+[23 April 2007]
+
+* Make tag_list to respect Tag.delimiter
+
+[31 March 2007]
+
+* Add Tag.delimiter accessor to change how tags are parsed.
+
+* Fix :include => :tags when used with find_tagged_with
+
+[7 March 2007]
+
+* Fix tag_counts for SQLServer [Brad Young]
+
+[21 Feb 2007]
+
+* Use scoping instead of TagCountsExtension [Michael Schuerig]
+
+[7 Jan 2007]
+
+* Add :match_all to find_tagged_with [Michael Sheakoski]

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006 Jonathan Viney
+
+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

@@ -0,0 +1,157 @@
+= acts_as_taggable_on_steroids
+
+If you find this plugin useful, please consider a donation to show your support!
+
+  http://www.paypal.com/cgi-bin/webscr?cmd=_send-money
+  
+  Email address: jonathan.viney@gmail.com
+  
+== 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
+
+Rails 2.*
+
+  ruby script/plugin install git://github.com/jviney/acts_as_taggable_on_steroids.git
+
+Rails 3:
+
+  rails plugin install git://github.com/jviney/acts_as_taggable_on_steroids.git
+
+== 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, <tt>#tag_list</tt> and <tt>#tag_list=</tt>. 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.find_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.find_tagged_with('Funny, Silly', :match_all => true)
+  
+See <tt>ActiveRecord::Acts::Taggable::InstanceMethods</tt> 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 <tt>Post</tt> class, we can
+get a calculation of all the tag counts by using <tt>Post.tag_counts</tt>. 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 <tt>counts</tt> method on <tt>Tag</tt> 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 <tt>cached_tag_list</tt> 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
+<tt>tags</tt> or <tt>taggings</tt> associations. To update the cached tag list you should call <tt>save_cached_tag_list</tt> 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 config/environment.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
+
+=== Other
+
+Problems, comments, and suggestions all welcome. jonathan.viney@gmail.com  

data/lib/acts_as_taggable.rb

@@ -0,0 +1,246 @@
+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)
+