acts-as-taggable-on 1.0.7 → 1.1.0

data/CHANGELOG

@@ -1,3 +1,7 @@
+== 2009-12-02
+
+* PostgreSQL is now supported (via morgoth)
+
 == 2008-07-17
 
 * Can now use a named_scope to find tags!

data/README.rdoc

@@ -0,0 +1,199 @@
+= ActsAsTaggableOn
+
+This plugin was originally based on Acts as Taggable on Steroids by Jonathan Viney.
+It has evolved substantially since that point, but all credit goes to him for the
+initial tagging functionality that so many people have used.
+
+For instance, in a social network, a user might have tags that are called skills,
+interests, sports, and more. There is no real way to differentiate between tags and
+so an implementation of this type is not possible with acts as taggable on steroids.
+
+Enter Acts as Taggable On. Rather than tying functionality to a specific keyword
+(namely "tags"), acts as taggable on allows you to specify an arbitrary number of
+tag "contexts" that can be used locally or in combination in the same way steroids
+was used.
+
+== Installation
+
+=== Plugin
+
+Acts As Taggable On is available both as a gem and as a traditional plugin. For the
+traditional plugin you can install like so (Rails 2.1 or later):
+
+  script/plugin install git://github.com/mbleigh/acts-as-taggable-on.git
+  
+=== GemPlugin
+
+Acts As Taggable On is also available as a gem plugin using Rails 2.1's gem dependencies.
+To install the gem, add this to your config/environment.rb:
+  
+  config.gem "acts-as-taggable-on", :source => "http://gemcutter.org"
+  
+After that, you can run "rake gems:install" to install the gem if you don't already have it.
+
+=== Post Installation (Rails)
+
+1. script/generate acts_as_taggable_on_migration
+2. rake db:migrate
+
+=== Testing
+
+Acts As Taggable On uses RSpec for its test coverage. Inside the plugin
+directory, you can run the specs with:
+
+rake spec
+
+If you already have RSpec on your application, the specs will run while using:
+
+rake spec:plugins
+
+
+== Usage
+
+    class User < ActiveRecord::Base
+      acts_as_taggable_on :tags, :skills, :interests
+    end
+
+    @user = User.new(:name => "Bobby")
+    @user.tag_list = "awesome, slick, hefty"      # this should be familiar
+    @user.skill_list = "joking, clowning, boxing" # but you can do it for any context!
+    @user.skill_list # => ["joking","clowning","boxing"] as TagList
+    @user.save
+
+    @user.tags # => [<Tag name:"awesome">,<Tag name:"slick">,<Tag name:"hefty">]
+    @user.skills # => [<Tag name:"joking">,<Tag name:"clowning">,<Tag name:"boxing">]
+
+    # The old way
+    User.find_tagged_with("awesome", :on => :tags) # => [@user]
+    User.find_tagged_with("awesome", :on => :skills) # => []
+
+    # The better way (utilizes named_scope)
+    User.tagged_with("awesome", :on => :tags) # => [@user]
+    User.tagged_with("awesome", :on => :skills) # => []
+
+    @frankie = User.create(:name => "Frankie", :skill_list => "joking, flying, eating")
+    User.skill_counts # => [<Tag name="joking" count=2>,<Tag name="clowning" count=1>...]
+    @frankie.skill_counts
+
+=== Finding Tagged Objects
+
+Acts As Taggable On utilizes Rails 2.1's named_scope to create an association
+for tags. This way you can mix and match to filter down your results, and it
+also improves compatibility with the will_paginate gem:
+
+    class User < ActiveRecord::Base
+      acts_as_taggable_on :tags
+      named_scope :by_join_date, :order => "created_at DESC"
+    end
+
+    User.tagged_with("awesome").by_date
+    User.tagged_with("awesome").by_date.paginate(:page => params[:page], :per_page => 20)
+
+=== Relationships
+
+You can find objects of the same type based on similar tags on certain contexts.
+Also, objects will be returned in descending order based on the total number of 
+matched tags.
+
+    @bobby = User.find_by_name("Bobby")
+    @bobby.skill_list # => ["jogging", "diving"]
+
+    @frankie = User.find_by_name("Frankie")
+    @frankie.skill_list # => ["hacking"]
+
+    @tom = User.find_by_name("Tom")
+    @tom.skill_list # => ["hacking", "jogging", "diving"]
+
+    @tom.find_related_skills # => [<User name="Bobby">,<User name="Frankie">]
+    @bobby.find_related_skills # => [<User name="Tom">] 
+    @frankie.find_related_skills # => [<User name="Tom">] 
+
+=== Dynamic Tag Contexts
+
+In addition to the generated tag contexts in the definition, it is also possible
+to allow for dynamic tag contexts (this could be user generated tag contexts!)
+
+    @user = User.new(:name => "Bobby")
+    @user.set_tag_list_on(:customs, "same, as, tag, list")
+    @user.tag_list_on(:customs) # => ["same","as","tag","list"]
+    @user.save
+    @user.tags_on(:customs) # => [<Tag name='same'>,...]
+    @user.tag_counts_on(:customs)
+    User.find_tagged_with("same", :on => :customs) # => [@user]
+
+=== Tag Ownership
+
+Tags can have owners:
+
+    class User < ActiveRecord::Base
+      acts_as_tagger
+    end
+
+    class Photo < ActiveRecord::Base
+      acts_as_taggable_on :locations
+    end
+
+    @some_user.tag(@some_photo, :with => "paris, normandy", :on => :locations)
+    @some_user.owned_taggings
+    @some_user.owned_tags
+    @some_photo.locations_from(@some_user)
+    
+=== Tag cloud calculations
+
+To construct tag clouds, the frequency of each tag needs to be calculated.
+Because we specified +acts_as_taggable_on+ on the <tt>User</tt> class, we can
+get a calculation of all the tag counts by using <tt>User.tag_counts_on(:customs)</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_on(:tags)
+
+A helper is included to assist with generating tag clouds.
+
+Here is an example that generates a tag cloud.
+
+Helper:
+
+  module PostsHelper
+    include TagsHelper
+  end
+
+Controller:
+
+  class PostController < ApplicationController
+    def tag_cloud
+      @tags = Post.tag_counts_on(:tags)
+    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; }
+
+== Contributors
+
+* TomEric (i76) - Maintainer
+* Michael Bleigh - Original Author
+* Brendan Lim - Related Objects
+* Pradeep Elankumaran - Taggers
+* Sinclair Bain - Patch King
+
+== Patch Contributors
+
+* tristanzdunn - Related objects of other classes
+* azabaj - Fixed migrate down
+* Peter Cooper - named_scope fix
+* slainer68 - STI fix
+* harrylove - migration instructions and fix-ups
+* lawrencepit - cached tag work
+* sobrinho - fixed tag_cloud helper
+
+Copyright (c) 2007-2009 Michael Bleigh (http://mbleigh.com/) and Intridea Inc. (http://intridea.com/), released under the MIT license

data/Rakefile

@@ -9,7 +9,7 @@ begin
     gemspec.email = "michael@intridea.com"
     gemspec.homepage = "http://github.com/mbleigh/acts-as-taggable-on"
     gemspec.authors = ["Michael Bleigh"]
-    gemspec.files =  FileList["[A-Z]*", "{lib,spec,rails}/**/*"] - FileList["**/*.log"]
+    gemspec.files =  FileList["[A-Z]*", "{generators,lib,spec,rails}/**/*"] - FileList["**/*.log"]
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError
@@ -21,3 +21,9 @@ task :default => :spec
 Spec::Rake::SpecTask.new do |t|
   t.spec_files = FileList["spec/**/*_spec.rb"]
 end
+
+Spec::Rake::SpecTask.new('rcov') do |t|
+  t.spec_files = FileList["spec/**/*_spec.rb"]
+  t.rcov = true
+  t.rcov_opts = ['--exclude', 'spec']
+end

data/VERSION

@@ -1 +1 @@
-1.0.7
+1.1.0

data/generators/acts_as_taggable_on_migration/acts_as_taggable_on_migration_generator.rb

@@ -0,0 +1,7 @@
+class ActsAsTaggableOnMigrationGenerator < Rails::Generator::Base 
+  def manifest 
+    record do |m| 
+      m.migration_template 'migration.rb', 'db/migrate', :migration_file_name => "acts_as_taggable_on_migration"
+    end
+  end
+end

data/generators/acts_as_taggable_on_migration/templates/migration.rb

@@ -0,0 +1,29 @@
+class ActsAsTaggableOnMigration < 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
+      t.column :tagger_id, :integer
+      t.column :tagger_type, :string
+      
+      # You should make sure that the column created is
+      # long enough to store the required class names.
+      t.column :taggable_type, :string
+      t.column :context, :string
+      
+      t.column :created_at, :datetime
+    end
+    
+    add_index :taggings, :tag_id
+    add_index :taggings, [:taggable_id, :taggable_type, :context]
+  end
+  
+  def self.down
+    drop_table :taggings
+    drop_table :tags
+  end
+end

data/lib/acts-as-taggable-on.rb

@@ -1,3 +1,4 @@
+require 'acts_as_taggable_on/group_helper'
 require 'acts_as_taggable_on/acts_as_taggable_on'
 require 'acts_as_taggable_on/acts_as_tagger'
 require 'acts_as_taggable_on/tag'