protolif-acts_as_taggable_on_steroids 2.1.1

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

@@ -0,0 +1,22 @@
+require 'rake'
+require 'rake/testtask'
+require 'rdoc/task'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the acts_as_taggable_on_steroids plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the acts_as_taggable_on_steroids plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Acts As Taggable On Steroids'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/app/helpers/tags_helper.rb

@@ -0,0 +1,13 @@
+module TagsHelper
+  # See the README for an example using tag_cloud.
+  def tag_cloud(tags, classes)
+    return if tags.all.empty?
+    
+    max_count = tags.sort_by(&:count).last.count.to_f
+    
+    tags.each do |tag|
+      index = ((tag.count / max_count) * (classes.size - 1)).round
+      yield tag, classes[index]
+    end
+  end
+end

data/app/models/tag.rb

@@ -0,0 +1,63 @@
+require 'active_support/core_ext/module/deprecation'
+
+class Tag < ActiveRecord::Base
+  cattr_accessor :destroy_unused
+  self.destroy_unused = false
+
+  has_many :taggings, :dependent => :delete_all
+
+  validates_presence_of :name
+  validates_uniqueness_of :name
+
+  def ==(object)
+    super || (object.is_a?(Tag) && name == object.name)
+  end
+  
+  def to_s
+    name
+  end
+  
+  def count
+    read_attribute(:count).to_i
+  end
+  
+  class << self
+    def find_or_create_with_like_by_name(name)
+      where(arel_table[:name].matches(name)).first || create(:name => name)
+    end
+
+    # Calculate the tag counts for all tags.
+    # 
+    # - +:start_at+ - restrict the tags to those created after a certain time
+    # - +:end_at+   - restrict the tags to those created before a certain time
+    # - +:at_least+ - exclude tags with a frequency less than the given value
+    # - +:at_most+  - exclude tags with a frequency greater than the given value
+    # 
+    # Deprecated:
+    # 
+    # - +:conditions+
+    # - +:limit+
+    # - +:order+
+    # 
+    def counts(options = {})
+      options.assert_valid_keys :start_at, :end_at, :at_least, :at_most, :conditions, :limit, :order, :joins
+      
+      tags = joins(:taggings)
+      tags = tags.having(["COUNT(#{quoted_table_name}.id) >= ?", options[:at_least]]) if options[:at_least]
+      tags = tags.having(["COUNT(#{quoted_table_name}.id) <= ?", options[:at_most]])  if options[:at_most]
+      tags = tags.where("#{Tagging.quoted_table_name}.created_at >= ?", options[:start_at]) if options[:start_at]
+      tags = tags.where("#{Tagging.quoted_table_name}.created_at <= ?", options[:end_at])   if options[:end_at]
+      
+      # TODO: deprecation warning
+      tags = tags.where(options[:conditions]) if options[:conditions]
+      tags = tags.limit(options[:limit])      if options[:limit]
+      tags = tags.order(options[:order])      if options[:order]
+      
+      if joins = options.delete(:joins)
+        tags = tags.joins(joins)
+      end
+      
+      tags.select("#{quoted_table_name}.id, #{quoted_table_name}.name, COUNT(#{quoted_table_name}.id) AS count").group('tags.id, tags.name')
+    end
+  end
+end

data/app/models/tag_list.rb

@@ -0,0 +1,109 @@
+class TagList < Array
+  cattr_accessor :delimiter
+  self.delimiter = ','
+  
+  def initialize(*args)
+    add(*args)
+  end
+  
+  # Add tags to the tag_list. Duplicate or blank tags will be ignored.
+  #
+  #   tag_list.add("Fun", "Happy")
+  # 
+  # Use the <tt>:parse</tt> option to add an unparsed tag string.
+  #
+  #   tag_list.add("Fun, Happy", :parse => true)
+  def add(*names)
+    extract_and_apply_options!(names)
+    concat(names)
+    clean!
+    self
+  end
+  
+  # Remove specific tags from the tag_list.
+  # 
+  #   tag_list.remove("Sad", "Lonely")
+  #
+  # Like #add, the <tt>:parse</tt> option can be used to remove multiple tags in a string.
+  # 
+  #   tag_list.remove("Sad, Lonely", :parse => true)
+  def remove(*names)
+    extract_and_apply_options!(names)
+    delete_if { |name| names.include?(name) }
+    self
+  end
+  
+  # Toggle the presence of the given tags.
+  # If a tag is already in the list it is removed, otherwise it is added.
+  def toggle(*names)
+    extract_and_apply_options!(names)
+    
+    names.each do |name|
+      include?(name) ? delete(name) : push(name)
+    end
+    
+    clean! 
+    self
+  end
+  
+  # Transform the tag_list into a tag string suitable for edting in a form.
+  # The tags are joined with <tt>TagList.delimiter</tt> and quoted if necessary.
+  #
+  #   tag_list = TagList.new("Round", "Square,Cube")
+  #   tag_list.to_s # 'Round, "Square,Cube"'
+  def to_s
+    clean!
+    
+    map do |name|
+      name.include?(delimiter) ? "\"#{name}\"" : name
+    end.join(delimiter.ends_with?(" ") ? delimiter : "#{delimiter} ")
+  end
+  
+ private
+  # Remove whitespace, duplicates, and blanks.
+  def clean!
+    reject!(&:blank?)
+    map!(&:strip)
+    uniq!
+  end
+  
+  def extract_and_apply_options!(args)
+    options = args.last.is_a?(Hash) ? args.pop : {}
+    options.assert_valid_keys :parse
+    
+    if options[:parse]
+      args.map! { |a| self.class.from(a) }
+    end
+    
+    args.flatten!
+  end
+  
+  class << self
+    # Returns a new TagList using the given tag string.
+    # 
+    #   tag_list = TagList.from("One , Two,  Three")
+    #   tag_list # ["One", "Two", "Three"]
+    def from(source)
+      tag_list = new
+      
+      case source
+      when Array
+        tag_list.add(source)
+      else
+        string = source.to_s.dup
+        
+        # Parse the quoted tags
+        [
+          /\s*#{delimiter}\s*(['"])(.*?)\1\s*/,
+          /^\s*(['"])(.*?)\1\s*#{delimiter}?/
+        ].each do |re|
+          string.gsub!(re) { tag_list << $2; "" }
+        end
+        
+        tag_list.add(string.split(delimiter))
+      end
+      
+      tag_list
+    end
+  end
+end

data/app/models/tagging.rb

@@ -0,0 +1,16 @@
+class Tagging < ActiveRecord::Base #:nodoc:
+  belongs_to :tag
+  belongs_to :taggable, :polymorphic => true
+  
+  after_destroy :destroy_tag_if_unused
+  
+  private
+  
+  def destroy_tag_if_unused
+    if Tag.destroy_unused
+      if tag.taggings.count.zero?
+        tag.destroy
+      end
+    end
+  end
+end

data/lib/acts_as_taggable.rb

@@ -0,0 +1,2 @@
+
+require File.join(File.dirname(__FILE__), 'acts_as_taggable/engine')

data/lib/acts_as_taggable/active_record_extension.rb

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