tagtical 1.0.6

data/CHANGELOG

@@ -0,0 +1,25 @@
+== 2010-02-17
+* Converted the plugin to be compatible with Rails3
+
+== 2009-12-02
+
+* PostgreSQL is now supported (via morgoth)
+
+== 2008-07-17
+
+* Can now use a named_scope to find tags!
+
+== 2008-06-23
+
+* Can now find related objects of another class (tristanzdunn)
+* Removed extraneous down migration cruft (azabaj)
+
+== 2008-06-09
+
+ * Added support for Single Table Inheritance
+ * Adding gemspec and rails/init.rb for gemified plugin
+
+== 2007-12-12
+
+ * Added ability to use dynamic tag contexts
+ * Fixed missing migration generator

data/Gemfile

@@ -0,0 +1,20 @@
+source :gemcutter
+
+# Rails 3.0
+
+# Cannot require these as dependency until there the fix is released:
+# 
+#gem 'rails', '3.0.5'
+#gem 'rspec', '2.6.0'
+# http://rubyforge.org/tracker/?func=detail&atid=575&aid=29163&group_id=126
+
+gem 'sqlite3-ruby', :require => 'sqlite3'
+gem 'mysql'
+
+#gem 'pg'
+gem 'jeweler'
+gem 'rcov'
+
+group :test do
+  gem "mocha"
+end

data/Gemfile.lock

@@ -0,0 +1,25 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    git (1.2.5)
+    jeweler (1.6.2)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+    mocha (0.9.12)
+    mysql (2.8.1)
+    rake (0.9.2)
+    rcov (0.9.9)
+    sqlite3 (1.3.3)
+    sqlite3-ruby (1.3.3)
+      sqlite3 (>= 1.3.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  jeweler
+  mocha
+  mysql
+  rcov
+  sqlite3-ruby

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2007 Michael Bleigh and Intridea Inc.
+
+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.rdoc

@@ -0,0 +1,306 @@
+= Tagtical
+
+This plugin was originally based on acts_as_taggable_on by Michael Bleigh (http://mbleigh.com/). That plugin
+was based on acts_as_taggable_on_steroids by Jonathan Viney.
+
+While a lot concepts are the same (taggings + tags tables using polymorphism), this adaption introduces
+the concept of "relevance" for a tag and allows for the creation of subclasses on Tag.
+
+For instance, if you want to tag a photo with "Mood Tags". You would simply subclass Tag with
+Tag::Mood and you could add functionality specific to that model. This involves moving the "context"
+off of Tagging and moving it onto Tag as a "type" column. It acts not only as a "context", but also
+as a designator for the STI class. Subsequently, you could also add a "relevance" for how applicable
+that mood is.
+
+Tagtical allows for an arbitrary number of Tag subclasses, each of which can be extended to the needs
+of the application. However, a tag subclass is not required! If you have many custom tag types that you
+create on the fly, you can wait until a later time to create a tag subclass.
+
+Here are the main differences between tagtical and acts_as_taggable_on:
+
+1. Add "relevance" to the Tagging class so you can weight the tags to the object.
+2. Tagtical removes "context" off the taggings table and adds "type" onto the tags table.
+3. The traditional functionality of tags is preserved while laying the foundation for STI on the Tag class.
+You can choose to extend the Tag class at a later time.
+4. Tag "name" now becomes tag "value". The difference is small, but significant. If you had
+GeoTag's, for example, you wouldn't refer to its "name", you would refer to its "value". The value
+could be a serialized field of long and lat if you wanted.
+5. Support a config/tagtical.yml to further configure the application. For example, since most people
+usually have one User class for their application, there is no reason to do polymorphic on "tagger",
+so I give the user the option to specify the class_name specifically for tagger.
+
+Additions include:
+1. Scopes are created on Tag so you can do photo.tags.color and grab all the tags of type Tag::Color, for example.
+2. Scopes are also created on the Taggable model so you could do Model.with_colors("red", "blue") and it would return everything tagged with those colors.
+
+== Installation
+
+=== Rails & Ruby Versions
+
+Tagtical was developed on Rails 3.05 and Ruby 1.9.2
+
+It can probably work with older versions, but would take a few tweaks.
+
+==== Plugin
+
+Tagtical is available both as a gem and as a traditional plugin. For the
+traditional plugin you can install like so:
+
+  script/plugin install git://github.com/Mixbook/tagtical.git
+
+==== Post Installation
+
+1. script/generate tagtical_migration
+2. rake db:migrate
+
+=== Rails 3.0
+To use it, add it to your Gemfile:
+  
+  gem 'tagtical'
+
+==== Post Installation
+
+1. rails generate tagtical:migration
+2. rake db:migrate
+
+== Testing
+
+Tagtical uses RSpec for its test coverage. Inside the plugin
+directory, you can run the specs for RoR 3.0.0 with:
+
+  rake spec
+
+Rails 2.3 is not supported, however I left the stub code from acts_as_taggable_on in there in case
+someone wants to try to get it working:
+
+  rake rails2.3:spec
+
+If you already have RSpec on your application, the specs will run while using:
+
+rake spec:plugins
+
+
+== Usage
+
+    class User < ActiveRecord::Base
+      # Alias for <tt>tagtical :tags</tt>:
+      acts_as_taggable :activities, :interests, :sports # top level, generic :tags is already included.
+    end
+    module Tag
+      class Activity < Tagtical::Tag
+      end
+      class Sport < Activity
+        def ball?
+          value=~/ball$/i
+        end
+      end
+    end
+
+    @user = User.new(:name => "Bobby")
+    @user.tag_list = "awesome, slick, hefty" # this should be familiar
+    @user.activity_list = "joking, clowning, boxing" # but you can do it for any context!
+    @user.activity_list                      # => ["joking","clowning","boxing"] as TagList
+    @user.save
+
+    @user.tags # => [<Tag value:"awesome">,<Tag value:"slick">,<Tag value:"hefty">]
+    @user.activities # => [<Tag::Activity value:"joking">,<Tag::Activity value:"clowning">,<Tag::Activity value:"boxing">]
+    @user.activities.first.athletic? # => false
+
+    @frankie = User.create(:name => "Frankie", :activity_list => "joking, flying, eating")
+    User.activity_counts # => [<Tag::Activity value="joking" count=2>,<Tag::Activity value="clowning" count=1>...]
+    @frankie.activity_counts
+
+    @user.sport_list = {"boxing" => 4.5  # Since Sport's parent is Activity, it will move "boxing" down
+                                         # from Activity to Sport and give it a relevance of 4.5.
+    @user.save
+
+    @user.activities # => [<Tag::Activity value:"joking">,<Tag::Activity value:"clowning">,<Tag::Sport value:"boxing">]
+    @user.activities(:only => :children) # => [<Tag::Sport value:"boxing">] - look at only the STI subclasses
+    @user.activities(:only => :current) # => [<Tag::Activity value:"joking">,<Tag::Activity value:"clowning">] - look at only the current STI class
+    @user.activities.first.athletic? # => false
+    @user.sports.all(&:ball?) # => true
+
+--- Defining Subclasses
+
+There is a lot of flexibility when it comes to naming subclasses. Lets say the type column had a value
+of "color". You could define the subclass any of these ways:
+
+    module Tagtical
+      module Tag
+        class Color < Tagtical::Tag
+        end
+      end
+    end
+    module Tag
+      class Color < Tagtical::Tag
+      end
+    end
+    class Color < Tagtical::Tag
+    end
+    module Tagtical
+      module Tag
+        class ColorTag < Tagtical::Tag
+        end
+      end
+    end
+    module Tag
+      class ColorTag < Tagtical::Tag
+      end
+    end
+    class ColorTag < Tagtical::Tag
+    end
+
+This allows for a wide range of folder structures. You could nest files (with corresponding models) like this:
+app/models/tagtical/tag/color.rb
+app/models/tag/color.rb
+app/models/color.rb
+app/models/tagtical/tag/color_tag.rb
+app/models/tag/color_tag.rb
+app/models/color_tag.rb
+
+=== Finding Tagged Objects
+
+Tagtical utilizes named_scopes 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
+      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)
+
+    # Find a user with matching all tags, not just one
+    User.tagged_with(["awesome", "cool"], :match_all => :true)
+    
+    # Find a user with any of the tags:
+    User.tagged_with(["awesome", "cool"], :any => true)
+
+=== 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.activity_list # => ["jogging", "diving"]
+
+    @frankie = User.find_by_name("Frankie")
+    @frankie.activity_list # => ["hacking"]
+
+    @tom = User.find_by_name("Tom")
+    @tom.activity_list # => ["hacking", "jogging", "diving"]
+
+    @tom.find_related_activities # => [<User name="Bobby">,<User name="Frankie">]
+    @bobby.find_related_activities # => [<User name="Tom">] 
+    @frankie.find_related_activities # => [<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 value='same'>,...]
+    @user.tag_counts_on(:customs)
+    User.tagged_with("same", :on => :customs) # => [@user]
+
+In the future, lets say you wanted to add additional methods for these specific tags. You would simply
+just define the subclass and the code will automatically instantiate it as that class. Just do:
+
+    class CustomTag < Tagtical::Tag
+      def some_custom_function
+      end
+    end
+
+Now moving forward, these classes will be instantiated with this model. Wow cool!
+
+
+=== Tag Ownership
+
+Tags can have owners:
+
+    class User < ActiveRecord::Base
+      acts_as_tagger
+    end
+
+    class Photo < ActiveRecord::Base
+      acts_as_taggable :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 +tagtical+ 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 Tagtical::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.value, { :action => :tag, :id => tag.value }, :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
+
+* Aryk Grosz - Original Author
+* Jonathan Nevelson - Taggable Scopes
+
+== Contributors (from the acts_as_taggable_on project)
+
+* TomEric (i76) - Maintainer
+* Michael Bleigh - Original Author of acts_as_taggable_on
+* Szymon Nowak - Rails 3.0 compatibility
+* Jelle Vandebeeck - Rails 3.0 compatibility
+* Brendan Lim - Related Objects
+* Pradeep Elankumaran - Taggers
+* Sinclair Bain - Patch King
+
+=== Patch Contributors (from the acts_as_taggable_on project)
+
+* 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) 2011 Aryk Grosz (http://mixbook.com/) released under the MIT license

data/Rakefile

@@ -0,0 +1,59 @@
+begin
+  # RSpec 1.3.0
+  require 'spec/rake/spectask'
+
+  desc 'Default: run specs'
+  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
+  
+rescue LoadError
+  # RSpec 2.0
+  require 'rspec/core/rake_task'
+
+  desc 'Default: run specs'
+  task :default => :spec  
+  RSpec::Core::RakeTask.new do |t|
+    t.pattern = "spec/**/*_spec.rb"
+  end
+  
+  RSpec::Core::RakeTask.new('rcov') do |t|
+    t.pattern = "spec/**/*_spec.rb"
+    t.rcov = true
+    t.rcov_opts = ['--exclude', 'spec']
+  end
+
+rescue LoadError
+  puts "RSpec not available. Install it with: gem install rspec"  
+end
+
+namespace 'rails2.3' do
+  task :spec do
+    gemfile = File.join(File.dirname(__FILE__), 'lib', 'tagtical', 'compatibility', 'Gemfile')
+    ENV['BUNDLE_GEMFILE'] = gemfile
+    Rake::Task['spec'].invoke    
+  end
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "tagtical"
+    gemspec.summary = "Tagtical is a tagging plugin for Rails that provides weighting, contexts, and inheritance for tags."
+    gemspec.description = "Tagtical allows you do create subclasses for Tag and add additional functionality in an STI fashion. For example. You could do Tag::Color.find_by_name('blue').to_rgb. It also supports storing weights or relevance on the taggings."
+    gemspec.email = "aryk@mixbook.com"
+    gemspec.homepage = "https://github.com/Mixbook/tagtical"
+    gemspec.authors = ["Aryk Grosz"]
+    gemspec.files =  FileList["[A-Z]*", "{generators,lib,spec,rails}/**/*"] - FileList["**/*.log"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: gem install jeweler"
+end

data/VERSION

@@ -0,0 +1 @@
+1.0.6

data/generators/tagtical_migration/tagtical_migration_generator.rb

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

data/generators/tagtical_migration/templates/migration.rb

@@ -0,0 +1,34 @@
+class TagticalMigration < ActiveRecord::Migration
+  def self.up
+    create_table :tags do |t|
+      t.column :value, :string
+      t.column :type, :string
+    end
+    add_index :tags, [:type, :value], :unique => true
+    add_index :tags, :value
+
+    create_table :taggings do |t|
+      t.column :relevance, :float
+      t.column :tag_id, :integer
+      t.column :taggable_id, :integer
+      t.column :tagger_id, :integer
+      t.column :tagger_type, :string if Tagtical.config.polymorphic_tagger?
+      
+      # 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]
+    add_index :taggings, Tagtical.config.polymorphic_tagger? ? [:tagger_id, :tagger_type] : [:tagger_id]
+  end
+  
+  def self.down
+    drop_table :taggings
+    drop_table :tags
+  end
+
+end

data/lib/generators/tagtical/migration/migration_generator.rb

@@ -0,0 +1,32 @@
+require 'rails/generators/migration'
+
+module Tagtical
+  class MigrationGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+
+    desc "Generates migration for Tag and Tagging models"
+
+    def self.orm
+      Rails::Generators.options[:rails][:orm]
+    end
+
+    def self.source_root
+      File.join(File.dirname(__FILE__), 'templates', (orm.to_s unless orm.class.eql?(String)) )
+    end
+
+    def self.orm_has_migration?
+      [:active_record].include? orm
+    end
+
+    def self.next_migration_number(path)
+      Time.now.utc.strftime("%Y%m%d%H%M%S")
+    end
+
+    def create_migration_file
+      if self.class.orm_has_migration?
+        migration_template 'migration.rb', 'db/migrate/tagtical_migration'
+      end
+    end
+  end
+end
+

data/lib/generators/tagtical/migration/templates/active_record/migration.rb

@@ -0,0 +1,35 @@
+class TagticalMigration < ActiveRecord::Migration
+  def self.up
+    create_table :tags do |t|
+      t.string :value
+      t.string :type
+    end
+    add_index :tags, [:type, :value], :unique => true
+    add_index :tags, :value
+
+    create_table :taggings do |t|
+      t.float :relevance
+      t.references :tag
+
+      # You should make sure that the column created is
+      # long enough to store the required class names.
+      t.references :taggable, :polymorphic => true
+      if Tagtical.config.polymorphic_tagger?
+        t.references :tagger, :polymorphic => true
+      else
+        t.integer :tagger_id
+      end
+
+      t.datetime :created_at
+    end
+
+    add_index :taggings, :tag_id
+    add_index :taggings, [:taggable_id, :taggable_type]
+    add_index :taggings,  Tagtical.config.polymorphic_tagger? ? [:tagger_id, :tagger_type] : [:tagger_id]
+  end
+
+  def self.down
+    drop_table :taggings
+    drop_table :tags
+  end
+end

data/lib/tagtical/acts_as_tagger.rb

@@ -0,0 +1,69 @@
+module Tagtical
+  module Tagger
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      ##
+      # Make a model a tagger. This allows an instance of a model to claim ownership
+      # of tags.
+      #
+      # Example:
+      #   class User < ActiveRecord::Base
+      #     acts_as_tagger
+      #   end
+      def acts_as_tagger(opts={})
+        class_eval do
+          opts.update(:as => :tagger) if Tagtical.config.polymorphic_tagger?
+          has_many :owned_taggings, opts.merge(:dependent => :destroy,
+                                               :include => :tag, :class_name => "Tagtical::Tagging")
+          has_many :owned_tags, :through => :owned_taggings, :source => :tag, :uniq => true, :class_name => "Tagtical::Tag"
+        end
+
+        include Tagtical::Tagger::InstanceMethods
+        extend Tagtical::Tagger::SingletonMethods
+      end
+
+      def is_tagger?
+        false
+      end
+    end
+
+    module InstanceMethods
+      ##
+      # Tag a taggable model with tags that are owned by the tagger. 
+      #
+      # @param taggable The object that will be tagged
+      # @param [Hash] options An hash with options. Available options are:
+      #               * <tt>:with</tt> - The tags that you want to
+      #               * <tt>:overwrite</tt> - true if you want to replace the tags with this new list.
+      #               * <tt>:on</tt>   - The context on which you want to tag
+      #
+      # Example:
+      #   @user.tag(@photo, :with => "paris, normandy", :on => :locations)
+      def tag(taggable, opts={})
+        opts.reverse_merge!(:force => true)
+
+        return false unless taggable.respond_to?(:is_taggable?) && taggable.is_taggable?
+
+        raise "You need to specify a tag context using :on"                unless opts.has_key?(:on)
+        raise "You need to specify some tags using :with"                  unless opts.has_key?(:with)
+        raise "No context :#{opts[:on]} defined in #{taggable.class.to_s}" unless (opts[:force] || taggable.tag_types.include?(opts[:on]))
+
+        taggable.set_owner_tag_list_on(self, opts[:on].to_s, opts[:with])
+        taggable.save
+      end
+
+      def is_tagger?
+        self.class.is_tagger?
+      end
+    end
+
+    module SingletonMethods
+      def is_tagger?
+        true
+      end
+    end
+  end
+end

data/lib/tagtical/compatibility/Gemfile

@@ -0,0 +1,8 @@
+source :gemcutter
+
+# Rails 2.3
+gem 'rails',        '2.3.5'
+gem 'rspec',        '1.3.0', :require => 'spec'
+gem 'sqlite3-ruby', '1.2.5', :require => 'sqlite3'
+gem 'mysql'
+gem 'pg'

data/lib/tagtical/compatibility/active_record_backports.rb

@@ -0,0 +1,21 @@
+module Tagtical
+  module ActiveRecord
+    module Backports
+      def self.included(base)
+        base.class_eval do
+          named_scope :where,    lambda { |conditions| { :conditions => conditions } }  
+          named_scope :joins,    lambda { |joins|      { :joins => joins } }
+          named_scope :group,    lambda { |group|      { :group => group } }
+          named_scope :order,    lambda { |order|      { :order => order } }
+          named_scope :select,   lambda { |select|     { :select => select } }
+          named_scope :limit,    lambda { |limit|      { :limit => limit } }
+          named_scope :readonly, lambda { |readonly|   { :readonly => readonly } }
+          
+          def self.to_sql
+            construct_finder_sql({})
+          end
+        end
+      end
+    end
+  end
+end