pictrails 0.5.0

data/vendor/plugins/acts_as_taggable_on_steroids/README

@@ -0,0 +1,148 @@
+= 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
+
+  ruby script/plugin install http://svn.viney.net.nz/things/rails/plugins/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, <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")
+
+=== 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
+
+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 = " "
+  
+You can also use a regexp as delimiter:
+
+  TagList.delimiter = /,|;/
+  
+The above code would parse the string and use ',' and ';' as delimiters.
+
+=== 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/vendor/plugins/acts_as_taggable_on_steroids/Rakefile

@@ -0,0 +1,22 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+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 << 'lib'
+  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/vendor/plugins/acts_as_taggable_on_steroids/generators/acts_as_taggable_migration/acts_as_taggable_migration_generator.rb

@@ -0,0 +1,11 @@
+class ActsAsTaggableMigrationGenerator < Rails::Generator::Base 
+  def manifest 
+    record do |m| 
+      m.migration_template 'migration.rb', 'db/migrate' 
+    end 
+  end
+  
+  def file_name
+    "acts_as_taggable_migration"
+  end
+end

data/vendor/plugins/acts_as_taggable_on_steroids/generators/acts_as_taggable_migration/templates/migration.rb

@@ -0,0 +1,26 @@
+class ActsAsTaggableMigration < ActiveRecord::Migration
+  def self.up
+    create_table :tags do |t|
+      t.column :name, :string
+    end
+    
+    create_table :taggings do |t|
+      t.column :tag_id, :integer
+      t.column :taggable_id, :integer
+      
+      # You should make sure that the column created is
+      # long enough to store the required class names.
+      t.column :taggable_type, :string
+      
+      t.column :created_at, :datetime
+    end
+    
+    add_index :taggings, :tag_id
+    add_index :taggings, [:taggable_id, :taggable_type]
+  end
+  
+  def self.down
+    drop_table :taggings
+    drop_table :tags
+  end
+end

data/vendor/plugins/acts_as_taggable_on_steroids/init.rb

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

data/vendor/plugins/acts_as_taggable_on_steroids/lib/acts_as_taggable.rb

@@ -0,0 +1,214 @@
+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:
+        #   :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
+        def find_tagged_with(*args)
+          options = find_options_for_find_tagged_with(*args)
+          options.blank? ? [] : find(:all, options)
+        end
+
+        # will_paginate's method_missing function wants to hit
+        # find_all_tagged_with if you call paginate_tagged_with, which is
+        # obviously suboptimal
+        def find_all_tagged_with(*args)
+          find_tagged_with(*args)
+        end
+        
+        def find_options_for_find_tagged_with(tags, options = {})
+          tags = tags.is_a?(Array) ? TagList.new(tags.map(&:to_s)) : TagList.from(tags)
+          options = options.dup
+          
+          return {} if tags.empty?
+          
+          conditions = []
+          conditions << sanitize_sql(options.delete(:conditions)) if options[:conditions]
+          
+          taggings_alias, tags_alias = "#{table_name}_taggings", "#{table_name}_tags"
+          
+          if options.delete(:exclude)
+            conditions << <<-END
+              #{table_name}.id NOT IN
+                (SELECT #{Tagging.table_name}.taggable_id FROM #{Tagging.table_name}
+                 INNER JOIN #{Tag.table_name} ON #{Tagging.table_name}.tag_id = #{Tag.table_name}.id
+                 WHERE #{tags_condition(tags)} AND #{Tagging.table_name}.taggable_type = #{quote_value(base_class.name)})
+            END
+          else
+            if options.delete(:match_all)
+              conditions << <<-END
+                (SELECT COUNT(*) FROM #{Tagging.table_name}
+                 INNER JOIN #{Tag.table_name} ON #{Tagging.table_name}.tag_id = #{Tag.table_name}.id
+                 WHERE #{Tagging.table_name}.taggable_type = #{quote_value(base_class.name)} AND
+                 taggable_id = #{table_name}.id AND
+                 #{tags_condition(tags)}) = #{tags.size}
+              END
+            else
+              conditions << tags_condition(tags, tags_alias)
+            end
+          end
+          
+          { :select => "DISTINCT #{table_name}.*",
+            :joins => "INNER JOIN #{Tagging.table_name} #{taggings_alias} ON #{taggings_alias}.taggable_id = #{table_name}.#{primary_key} AND #{taggings_alias}.taggable_type = #{quote_value(base_class.name)} " +
+                      "INNER JOIN #{Tag.table_name} #{tags_alias} ON #{tags_alias}.id = #{taggings_alias}.tag_id",
+            :conditions => conditions.join(" AND ")
+          }.reverse_merge!(options)
+        end
+        
+        # Calculate the tag counts for all tags.
+        # 
+        # Options:
+        #  :start_at - Restrict the tags to those created after a certain time
+        #  :end_at - Restrict the tags to those created before a certain time
+        #  :conditions - A piece of SQL conditions to add to the query
+        #  :limit - The maximum number of tags to return
+        #  :order - A piece of SQL to order by. Eg 'tags.count desc' or 'taggings.created_at desc'
+        #  :at_least - Exclude tags with a frequency less than the given value
+        #  :at_most - Exclude tags with a frequency greater than the given value
+        def tag_counts(options = {})
+          Tag.find(:all, find_options_for_tag_counts(options))
+        end
+
+        # Find how many objects are tagged with a certain tag.
+        def count_by_tag(tag_name)
+          counts = tag_counts(:conditions => "tags.name = #{quote_value(tag_name)}")
+          counts[0].respond_to?(:count) ? counts[0].count : 0
+        end
+        
+        def find_options_for_tag_counts(options = {})
+          options.assert_valid_keys :start_at, :end_at, :conditions, :at_least, :at_most, :order, :limit
+          options = options.dup
+          
+          scope = scope(:find)
+          start_at = sanitize_sql(["#{Tagging.table_name}.created_at >= ?", options.delete(:start_at)]) if options[:start_at]
+          end_at = sanitize_sql(["#{Tagging.table_name}.created_at <= ?", options.delete(:end_at)]) if options[:end_at]
+          
+          conditions = [
+            "#{Tagging.table_name}.taggable_type = #{quote_value(base_class.name)}",
+            sanitize_sql(options.delete(:conditions)),
+            scope && scope[:conditions],
+            start_at,
+            end_at
+          ]
+          
+          conditions << type_condition unless descends_from_active_record? 
+          conditions.compact!
+          conditions = conditions.join(' AND ')
+          
+          joins = ["INNER JOIN #{Tagging.table_name} ON #{Tag.table_name}.id = #{Tagging.table_name}.tag_id"]
+          joins << "INNER JOIN #{table_name} ON #{table_name}.#{primary_key} = #{Tagging.table_name}.taggable_id"
+          joins << scope[:joins] if scope && scope[:joins]
+          
+          at_least  = sanitize_sql(['COUNT(*) >= ?', options.delete(:at_least)]) if options[:at_least]
+          at_most   = sanitize_sql(['COUNT(*) <= ?', options.delete(:at_most)]) if options[:at_most]
+          having    = [at_least, at_most].compact.join(' AND ')
+          group_by  = "#{Tag.table_name}.id, #{Tag.table_name}.name HAVING COUNT(*) > 0"
+          group_by << " AND #{having}" unless having.blank?
+          
+          { :select     => "#{Tag.table_name}.id, #{Tag.table_name}.name, COUNT(*) AS count", 
+            :joins      => joins.join(" "),
+            :conditions => conditions,
+            :group      => group_by
+          }.reverse_merge!(options)
+        end
+        
+        def caching_tag_list?
+          column_names.include?(cached_tag_list_column_name)
+        end
+        
+       private
+        def tags_condition(tags, table_name = Tag.table_name)
+          condition = tags.map { |t| sanitize_sql(["#{table_name}.name LIKE ?", t]) }.join(" OR ")
+          "(" + condition + ")"
+        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.find(:all, :conditions => ["tag_id IN (?)", 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.
+        #
+        # The possible options are the same as the tag_counts class method, excluding :conditions.
+        def tag_counts(options = {})
+          self.class.tag_counts({ :conditions => self.class.send(:tags_condition, tag_list) }.reverse_merge!(options))
+        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)

data/vendor/plugins/acts_as_taggable_on_steroids/lib/tag.rb

@@ -0,0 +1,26 @@
+class Tag < ActiveRecord::Base
+  has_many :taggings
+  
+  validates_presence_of :name
+  validates_uniqueness_of :name
+  
+  cattr_accessor :destroy_unused
+  self.destroy_unused = false
+  
+  # LIKE is used for cross-database case-insensitivity
+  def self.find_or_create_with_like_by_name(name)
+    find(:first, :conditions => ["name LIKE ?", name]) || create(:name => name)
+  end
+  
+  def ==(object)
+    super || (object.is_a?(Tag) && name == object.name)
+  end
+  
+  def to_s
+    name
+  end
+  
+  def count
+    read_attribute(:count).to_i
+  end
+end