easy_tag 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2013 YOURNAME
+
+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.md

@@ -0,0 +1,159 @@
+## EasyTag
+
+This is a very simple tagging system for Rails. Because it is so simple, you should fork and modify it for your own purpose.
+
+This gem is used in my other projects, thus, it will be kept updated, albeit slowly.
+
+## Install
+
+    rails generate easy_tag:migration
+    rake db:migrate
+    rake db:test:prepare
+
+## Basic Usage
+
+  EasyTag offers very few methods to manipulate tags. You mostly work
+  on adding and removing tags on taggable. For advanced usage, try
+  work on the assocation of EasyTag models, or fork this project
+  and extend its functionality.
+
+### Tagger
+
+  You need to define __acts_as_tagger__ in tagger model like this:
+
+    class User < ActiveRecord::Base
+      acts_as_tagger
+    end
+
+  Only **ONE** model can be tagger.
+
+  You can find tags of tagger:
+
+    tagger.tags
+
+  Tags in a context can be retrieved like this:
+
+    tagger.tags.in_context(:skill)
+
+### Taggable
+  
+  You need to define __acts_as_taggable__ in tagger model like this:
+
+    class Post < ActiveRecord::Base
+      acts_as_taggable
+    end
+
+  You can manage tags of taggable
+
+    taggable.tags: return tags associated with this taggable
+    taggable.tags=: set tags of this taggable without context and tagger
+    taggable.set_tags: set tags of this taggable and remove old tags
+
+  All of setting methods (except tags=) can add :context and :tagger as optioanl parameters.
+  For example:
+
+    taggable.set_tags ['ruby', 'rvm'], :context => 'skill', :tagger => current_user
+
+  :context and :tagger also accept number as id for faster database query:
+
+    taggable.set_tags, :context => 'skill', :tagger => current_user.id
+
+  If not specified, default context is nil and default tagger is nil.
+
+  Tags should be an array of strings, or by default, a string with comma(,) to 
+  divide tags.
+  Delimiter can be specified in :delimiter, for example:
+
+    taggable.set_tags 'rails; ruby', :context => 'skill', :delimiter => ';'
+
+  Space, single and double quotation will be trimmed automatically.
+  For more complicated processing of tag string, use block:
+
+    taggable.set_tags 'rails; ruby', :context => 'skill' do |tag_list|
+      return tag_list.split(',')
+    end
+
+  To retrieve tags in a context, use
+
+    taggable.tags.in_context(:skill)
+
+  To retreieve tags tagged by a tagger, use
+
+    taggable.tags.by_tagger(User.first)
+
+  __in_context__ and __by_tagger__ can be chained together. They are methods in scopes.
+
+  To retrieve taggable tagged with tags, use
+
+    Taggable.with_tags('ruby, rvm', :match => :any)
+
+  Options for __:match__ can be :any (default), :all (expensive).
+
+  __with_tags__ can also be used with __in_context__ and __by_tagger__
+
+  To delete tags, set __nil__:
+
+    taggable.set_tags(nil)
+
+  To delete tags associated with context and tagger, include options __context__ and __tagger__:
+
+    taggable.set_tags(nil, :context => :skill, :tagger = User.first)
+
+### Tag
+
+    tag.taggers: taggers who use this tag
+    tag.taggings.collect(&:taggable): array of taggable tagged with this tag
+
+  To retrieve tags in a context, use
+
+    tags.in_context(:skill)
+
+  To retreieve tags tagged by a tagger, use
+
+    tagger.tags
+
+### Tagging
+
+  No public methods for now. 
+
+  This is the core model to link together tag, context, taggable and tagger. 
+  If you need to work on low-level database query, you probably need to look
+  at this one.
+
+### Tag Context
+
+  No public methods for now.
+
+  Just a place to keep records on tag context.
+
+## FAQ
+
+#### How do I get tag list from returned EasyTag::Tag ?
+
+    tags.pluck(:name).join(', ')
+
+
+#### What's the difference between these two ?
+
+    user.posts.tags
+
+    user.posts.by_tagger(user)
+
+
+The first returns all tags associated with posts, including tags tagged by others. The second return all tags associated with posts AND tagged by tagger.
+
+#### What's the difference between these two ?
+
+    Post.with_tags('ruby')
+
+    Post.with_tags('ruby').in_context(nil)
+
+The first returns all tags with 'ruby', regardless the context. In another word, it return all taggables with any context. The second returns all tags with 'ruby' with nil context. In another word, it will not return taggables where context exists. The same idea applies to __by_tagger__.
+
+## Acknowledges
+
+EasyTag is heavily influenced by [rocket_tag](https://github.com/bradphelan/rocket_tag), but not a direct fork.
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,27 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'EasyTag'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+Bundler::GemHelper.install_tasks
+

data/app/models/easy_tag/tag.rb

@@ -0,0 +1,29 @@
+class EasyTag::Tag < ActiveRecord::Base
+  has_many :taggings, :dependent => :destroy, 
+                      :class_name => 'EasyTag::Tagging'
+  has_many :taggers, :through => :taggings
+
+  # Setup accessible (or protected) attributes for your model
+  attr_accessible :name
+
+  def self.compact_tag_list(tag_list, options = {})
+    options.reverse_merge! :downcase => true, 
+                           :delimiter => ','
+    if (tag_list.is_a?(String))
+      tag_list.downcase! if options[:downcase]
+      tags = tag_list.to_tags(options[:delimiter])
+    elsif (tag_list.is_a?(Array))
+      if options[:downcase]
+        tags = tag_list.collect { |t| t.downcase }
+      else
+        tags = tag_list
+      end
+    elsif tag_list.blank?
+      tags = nil
+    else
+      raise EasyTag::InvalidTagList
+    end
+
+    tags
+  end
+end

data/app/models/easy_tag/tag_context.rb

@@ -0,0 +1,19 @@
+class EasyTag::TagContext < ActiveRecord::Base
+  has_many :taggings, :dependent => :destroy,
+                      :class_name => 'EasyTag::Tagging'
+  has_many :tags, :through => :taggings
+
+  # Setup accessible (or protected) attributes for your model
+  attr_accessible :name
+
+  def self.get_id(context)
+    if context.is_a?(String) || context.is_a?(Symbol)
+      context_id = self.where(:name => context.to_s).first
+    elsif context.is_a?(Integer)
+      context_id = context
+    else
+      raise EasyTag::InvalidContext
+    end
+    context_id
+  end
+end

data/app/models/easy_tag/tagging.rb

@@ -0,0 +1,5 @@
+class EasyTag::Tagging < ActiveRecord::Base
+  belongs_to :tag, :class_name => 'EasyTag::Tag'
+  belongs_to :tag_context, :class_name => 'EasyTag::TagContext'
+  belongs_to :taggable, :polymorphic => true
+end

data/app/models/easy_tag.rb

@@ -0,0 +1,8 @@
+# For some reason, it does not work. Thus, it is put in lib/easy_tag.rb
+=begin
+module EasyTag
+  def self.table_name_prefix
+    'easy_tag_'
+  end
+end
+=end

data/config/routes.rb

@@ -0,0 +1,2 @@
+Rails.application.routes.draw do
+end

data/lib/easy_tag/engine.rb

@@ -0,0 +1,4 @@
+module EasyTag
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/easy_tag/taggable.rb

@@ -0,0 +1,141 @@
+module EasyTag
+  module Taggable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :taggings, :as => :taggable, :dependent => :destroy,
+               :class_name => 'EasyTag::Tagging'
+      has_many :tags, :through => :taggings, :uniq => true do
+        def in_context(context)
+          context_id = EasyTag::TagContext.get_id(context)
+          where('easy_tag_taggings.tag_context_id = ?', context_id)
+        end
+
+        def by_tagger(tagger)
+          tagger_id = EasyTag::Tagger.get_id(tagger)
+          where('easy_tag_taggings.tagger_id = ?', tagger_id)
+        end
+      end # end of has_many :tags
+
+      scope :with_tags, ->(tag_list, options = {}) {
+        options.reverse_merge! :match => :any
+
+        if block_given?
+          tags = yield(klass)
+        else
+          tags = EasyTag::Tag.compact_tag_list(tag_list, options.slice(:downcase, :delimiter))
+        end
+
+        return where('1 == 2') if tags.nil?
+
+        query = tags.collect { |t| "name = '#{t}'" }.join(' OR ')
+        tag_ids = EasyTag::Tag.where(query).pluck(:id)
+
+        if options[:match] == :all
+          ids = nil
+          tag_ids.each do |tag_id|
+#            p EasyTag::Tag.find(tag_id)
+            taggable_ids = EasyTag::Tagging.where(:tag_id => tag_id).where(:taggable_type => self.model_name).pluck(:taggable_id).to_a
+            if ids
+              ids = ids & taggable_ids
+            else
+              ids = taggable_ids # first tag
+            end
+          end
+          joins(:taggings).where(:id => ids).uniq
+        else
+          # :any
+          joins(:taggings).where('easy_tag_taggings.tag_id' => tag_ids).uniq
+        end
+
+      } do
+        def in_context(context)
+          context_id = EasyTag::TagContext.get_id(context)
+          where('easy_tag_taggings.tag_context_id = ?', context_id)
+        end
+
+        def by_tagger(tagger)
+          tagger_id = EasyTag::Tagger.get_id(tagger)
+          where('easy_tag_taggings.tagger_id = ?', tagger_id)
+        end
+      end # end of scope :with_tags
+    end # end of included
+
+    module ClassMethods
+    end # end of class methods
+
+    def set_tags(tag_list, options = {})
+      options.reverse_merge! :context => nil, 
+                             :tagger => nil, 
+                             :downcase => true,
+                             :delimiter => ','
+
+      if block_given?
+        tags = yield(klass)
+      else
+        tags = EasyTag::Tag.compact_tag_list(tag_list, options.slice(:downcase, :delimiter))
+      end
+
+      context = compact_context(options[:context])
+      tagger = compact_tagger(options[:tagger])
+
+      # Remove old tags
+      self.taggings.where(:tag_context_id => context.try(:id), :tagger_id => tagger.try(:id)).destroy_all
+      # TODO: should remove unused tags and contexts
+
+      if tags
+        tags.each do |t|
+          tag = EasyTag::Tag.where(:name => t).first_or_create
+          raise SimgleTag::InvalidTag if tag.nil?
+          self.taggings.where(:tagger_id => tagger.try(:id), :tag_context_id => context.try(:id), :tag_id => tag.id).first_or_create
+        end
+      end
+    end
+
+    def tags=(tag_list)
+      self.set_tags(tag_list)
+    end
+
+    def is_taggable?
+      return true
+    end
+
+    protected
+
+    def compact_context(context)
+      return nil if context.blank?
+
+      if (context.is_a?(String) || context.is_a?(Symbol))
+        return EasyTag::TagContext.where(:name => context.to_s).first_or_create
+      elsif (context.is_a?(Integer))
+        return EasyTag::TagContext.where(:id => context).first_or_create
+      end
+
+      raise EasyTag::InvalidTagContext
+    end
+
+    def compact_tagger(tagger)
+      return nil if tagger.blank?
+      return tagger if tagger.is_tagger?
+
+      if (tagger.is_a?(Integer))
+        if EasyTag::Tagger.class_variable_defined?(:@@tagger_class)
+          klass = EasyTag::Tagger.class_variable_get(:@@tagger_class)
+          return klass.where(:id => tagger).first_or_create
+        else
+          raise EasyTag::NoTaggerDefined
+        end
+      end
+
+      raise EasyTag::InvalidTagger
+    end
+  end
+end
+
+class String
+  def to_tags(delimiter = ',')
+    self.split(delimiter).collect do |t|
+      t.strip.gsub(/\A["']|["']\Z/, '')
+    end
+  end
+end

data/lib/easy_tag/tagger.rb

@@ -0,0 +1,36 @@
+module EasyTag
+  module Tagger
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :taggings, :dependent => :destroy,
+               :class_name => 'EasyTag::Tagging',
+               :foreign_key => 'tagger_id'
+      has_many :tags, :through => :taggings, :uniq => true do
+        def in_context(context)
+          context_id = EasyTag::TagContext.get_id(context)
+          where('easy_tag_taggings.tag_context_id = ?', context_id)
+        end
+      end
+    end # end of included
+
+    module ClassMethods
+      def get_id(tagger)
+        if tagger.is_a?(Integer)
+          tagger_id = tagger
+        elsif tagger.is_tagger?
+          tagger_id = tagger.id
+        else
+          raise EasyTag::InvalidTagger
+        end
+        tagger_id
+      end
+    end # end of class methods
+
+    extend ClassMethods # to be use in EasyTag::Tag module
+
+    def is_tagger?
+      return true
+    end
+  end
+end

data/lib/easy_tag/version.rb

@@ -0,0 +1,3 @@
+module EasyTag
+  VERSION = "0.1.0"
+end

data/lib/easy_tag.rb

@@ -0,0 +1,36 @@
+require 'easy_tag/engine'
+require 'easy_tag/taggable.rb'
+require 'easy_tag/tagger.rb'
+
+# For some reason, this does not work when set in app/models/easy_tag.rb
+# Therefore, it is put here.
+module EasyTag
+  def self.table_name_prefix
+    'easy_tag_'
+  end
+end
+
+if defined?(ActiveRecord::Base)
+  class ActiveRecord::Base
+    def is_taggable?
+      return false
+    end
+
+    def is_tagger?
+      return false
+    end
+
+    def self.acts_as_taggable(options = {})
+      options.reverse_merge!({})
+      include EasyTag::Taggable
+    end
+
+    def self.acts_as_tagger(options = {})
+      options.reverse_merge!({})
+      include EasyTag::Tagger
+
+      EasyTag::Tagger.class_variable_set(:@@tagger_class, self)
+      EasyTag::Tagging.belongs_to :tagger, :class_name => self.model_name
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+require 'rails/generators'
+require 'rails/generators/migration'
+require 'rails/generators/active_record'
+
+module EasyTag
+  class MigrationGenerator < Rails::Generators::Base
+    include Rails::Generators::Migration
+
+    desc 'add easy tag'
+
+    source_root File.expand_path('../templates', __FILE__)
+
+    def self.next_migration_number(path)
+      ActiveRecord::Generators::Base.next_migration_number(path)
+    end
+
+    def create_migration_file
+      migration_template 'migration.rb', 'db/migrate/easy_tag_migration'
+    end
+  end
+end

data/lib/generators/easy_tag/migration/templates/migration.rb

@@ -0,0 +1,34 @@
+class EasyTagMigration < ActiveRecord::Migration
+
+  def change
+    create_table :easy_tag_tags do |t|
+      t.string :name
+
+      t.timestamps
+    end
+
+    create_table :easy_tag_tag_contexts do |t|
+      t.string :name
+
+      t.timestamps
+    end
+
+    create_table :easy_tag_taggings do |t|
+      t.references :tag
+      t.references :tag_context
+      t.references :tagger
+
+      # You should make sure that the column created is
+      # long enough to store the required class names.
+      t.references :taggable, :polymorphic => true
+    
+      t.timestamps
+    end
+
+    add_index :easy_tag_taggings, :tag_id
+    add_index :easy_tag_taggings, :tagger_id
+    add_index :easy_tag_taggings, :tag_context_id
+    add_index :easy_tag_taggings, [:taggable_id, :taggable_type]
+  end
+
+end

data/lib/tasks/easy_tag_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :easy_tag do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: easy_tag
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Yen-Ju Chen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-01-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.11
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.2.11
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A very simple tagging system for Rails to be forked or extended.
+email:
+- yjchenx@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- app/models/easy_tag/tag.rb
+- app/models/easy_tag/tag_context.rb
+- app/models/easy_tag/tagging.rb
+- app/models/easy_tag.rb
+- config/routes.rb
+- lib/easy_tag/engine.rb
+- lib/easy_tag/taggable.rb
+- lib/easy_tag/tagger.rb
+- lib/easy_tag/version.rb
+- lib/easy_tag.rb
+- lib/generators/easy_tag/migration/migration_generator.rb
+- lib/generators/easy_tag/migration/templates/migration.rb
+- lib/tasks/easy_tag_tasks.rake
+- MIT-LICENSE
+- Rakefile
+- README.md
+homepage: https://github.com/yjchen/easy_tag
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: A very simple tagging system for Rails
+test_files: []