tagtical 1.0.6

data/lib/tagtical/tag.rb

@@ -0,0 +1,314 @@
+module Tagtical
+  class Tag < ::ActiveRecord::Base
+    
+    attr_accessible :value
+
+    ### ASSOCIATIONS:
+
+    has_many :taggings, :dependent => :destroy, :class_name => 'Tagtical::Tagging'
+
+    ### VALIDATIONS:
+    
+    validates :value, :uniqueness => {:scope => :type}, :presence => true # type is not required, it can be blank
+
+    ## POSSIBLE_VALUES SUPPORT:
+
+    class_attribute :possible_values
+    validate :validate_possible_values
+    
+    self.store_full_sti_class = false
+
+    ### CLASS METHODS:
+
+    class << self
+
+      def where_any(list, options={})
+        char = "%" if options[:wildcard]
+        operator = options[:case_insensitive] || options[:wildcard] ?
+          (using_postgresql? ? 'ILIKE' : 'LIKE') :
+          "="
+        conditions = Array(list).map { |tag| ["value #{operator} ?", "#{char}#{tag.to_s}#{char}"] }
+        where(conditions.size==1 ? conditions.first : conditions.map { |c| sanitize_sql(c) }.join(" OR "))
+      end
+
+      def using_postgresql?
+        connection.adapter_name=='PostgreSQL'
+      end
+
+      # Use this for case insensitive 
+      def where_any_like(list, options={})
+        where_any(list, options.update(:case_insensitive => true))
+      end
+
+      ### CLASS METHODS:
+
+      def find_or_create_with_like_by_value!(value)
+        where_any_like(value).first || create!(:value => value)
+      end
+
+      # Method used to ensure list of tags for the given Tag class.
+      # Returns a hash with the key being the value from the tag list and the value being the saved tag.
+      def find_or_create_tags(*tag_list)
+        tag_list = [tag_list].flatten
+        return {} if tag_list.empty?
+
+        existing_tags  = where_any_like(tag_list).all
+        tag_list.each_with_object({}) do |value, tag_lookup|
+          tag_lookup[detect_comparable(existing_tags, value) || create!(:value => value)] = value
+        end
+      end
+
+      def sti_name
+        return @sti_name if instance_variable_defined?(:@sti_name)
+        @sti_name = Tagtical::Tag==self ? nil : Type.new(name.demodulize).to_sti_name
+      end
+
+      protected
+
+      def compute_type(type_name)
+        @@compute_type ||= {}
+        # super is required when it gets called from a reflection.
+        @@compute_type[type_name] || super
+      rescue Exception => e
+        @@compute_type[type_name] = Type.new(type_name).klass!
+      end
+
+      private
+      
+      # Checks to see if a tags value is present in a set of tags and returns that tag.
+      def detect_comparable(tags, value)
+        value = comparable_value(value)
+        tags.detect { |tag| comparable_value(tag.value) == value }
+      end
+
+      def comparable_value(str)
+        RUBY_VERSION >= "1.9" ? str.downcase : str.mb_chars.downcase
+      end
+
+    end
+
+    ### INSTANCE METHODS:
+
+    def ==(object)
+      super || (object.is_a?(self.class) && value == object.value)
+    end
+
+    def relevance
+      (v = self["relevance"]) && v.to_f
+    end
+
+    # Try to sort by the relevance if provided.
+    def <=>(tag)
+      if (r1 = relevance) && (r2 = tag.relevance)
+        r1 <=> r2
+      else
+        value <=> tag.value
+      end
+    end
+
+    def to_s
+      value
+    end
+
+    # Overwrite these methods to provide your own storage mechanism for a tag.
+    def load_value(value) value end
+    def dump_value(value) value end
+
+    def value
+      @value ||= load_value(self[:value])
+    end
+
+    def value=(value)
+      @value = nil
+      self[:value] = dump_value(value)
+    end
+
+    # We return nil if we are *not* an STI class.
+    def type
+      type = self[:type]
+      type && Type[type]
+    end
+
+    def count
+      self[:count].to_i
+    end
+
+    private
+
+    def validate_possible_values
+      if possible_values && !possible_values.include?(value)
+        errors.add(:value, %{Value "#{value}" not found in list: #{possible_values.inspect}})
+      end
+    end
+
+    class Type < String
+
+      # "tag" should always correspond with demodulize name of the base Tag class (ie Tagtical::Tag).
+      BASE = "tag".freeze
+
+      # Default to simply "tag", if none is provided. This will return Tagtical::Tag on calls to #klass
+      def initialize(arg)
+        super(arg.to_s.singularize.underscore.gsub(/_tag$/, ''))
+      end
+
+      class << self
+        def find(input)
+          return input.map { |c| self[c] } if input.is_a?(Array)
+          input.is_a?(self) ? input : new(input)
+        end
+        alias :[] :find
+      end
+
+      # The STI name for the Tag model is the same as the tag type.
+      def to_sti_name
+        self
+      end
+
+      # Leverages current type_condition logic from ActiveRecord while also allowing for type conditions
+      # when no Tag subclass is defined. Also, it builds the type condition for STI inheritance.
+      #
+      # Options:
+      #   <tt>sql</tt> - Set to true to return sql string. Set to :append to return a sql string which can be appended as a condition.
+      #   <tt>only</tt> - An array of the following: :parents, :current, :children. Will construct conditions to query the current, parent, and/or children STI classes.
+      #
+      def finder_type_condition(options={})
+        only = Array.wrap(options[:only] || (klass ? [:current, :children] : :current))
+
+        # If we want [:current, :children] or [:current, :children, :parents] and we don't need the finder type condition,
+        # then that means we don't need a condition at all since we are at the top-level sti class and we are essentially
+        # searching the whole range of sti classes.
+        if klass && !klass.finder_needs_type_condition?
+          only.delete(:parents) # we are at the topmost level.
+          only = [] if only==[:current, :children] # no condition is required if we want the current AND the children.
+        end
+
+        sti_names = []
+        if only.include?(:current)
+          sti_names << (klass ? klass.sti_name : to_sti_name)
+        end
+        if only.include?(:children) && klass
+          sti_names.concat(klass.descendants.map(&:sti_name))
+        end
+        if only.include?(:parents) && klass # include searches up the STI chain
+          parent_class = klass.superclass
+          while parent_class <= Tagtical::Tag
+            sti_names << parent_class.sti_name
+            parent_class = parent_class.superclass
+          end
+        end
+
+        sti_column = Tagtical::Tag.arel_table[Tagtical::Tag.inheritance_column]
+        condition = sti_names.inject(nil) do |conds, sti_name|
+          cond = sti_column.eq(sti_name)
+          conds.nil? ? cond : conds.or(cond)
+        end
+        
+        if condition && options[:sql]
+          condition = condition.to_sql
+          condition.insert(0, " AND ") if options[:sql]==:append
+        end
+        condition
+      end
+
+      def scoping(options={}, &block)
+        finder_type_condition = finder_type_condition(options)
+        if block_given?
+          if finder_type_condition
+            Tagtical::Tag.send(:with_scope, :find => Tagtical::Tag.where(finder_type_condition), :create => {:type => self}) do
+              Tagtical::Tag.instance_exec(&block)
+            end
+          else
+            Tagtical::Tag.instance_exec(&block)
+          end
+        else
+          Tagtical::Tag.send(*(finder_type_condition ? [:where, finder_type_condition] : :unscoped))
+        end
+      end
+      
+      # Return the Tag subclass
+      def klass
+        instance_variable_get(:@klass) || instance_variable_set(:@klass, find_tag_class)
+      end
+
+      # Return the Tag class or return top-level
+      def klass!
+        klass || Tagtical::Tag
+      end
+
+      def has_many_name
+        pluralize.to_sym
+      end
+      alias scope_name has_many_name
+
+      def base?
+        !!klass && klass.descends_from_active_record?
+      end
+
+      def ==(val)
+        super(self.class[val])
+      end
+
+      def tag_list_name(prefix=nil)
+        prefix = prefix.to_s.dup
+        prefix << "_" unless prefix.blank?
+        "#{prefix}#{self}_list"
+      end
+
+      def tag_list_ivar(*args)
+        "@#{tag_list_name(*args)}"
+      end
+
+      # Returns the level from which it extends from Tagtical::Tag
+      def active_record_sti_level
+        @active_record_sti_level ||= begin
+          count, current_class = 0, klass!
+          while !current_class.descends_from_active_record?
+            current_class = current_class.superclass
+            count += 1
+          end
+          count
+        end
+      end
+
+      private
+
+      # Returns an array of potential class names for this specific type.
+      def derive_class_candidates
+        [].tap do |arr|
+          [classify, "#{classify}Tag"].each do |name| # support Interest and InterestTag class names.
+            "Tagtical::Tag".tap do |longest_candidate|
+              longest_candidate << "::#{name}" unless name=="Tag"
+            end.scan(/^|::/) { arr << $' } # Klass, Tag::Klass, Tagtical::Tag::Klass
+          end
+        end
+      end
+
+      def find_tag_class
+        candidates = derive_class_candidates
+
+        # Attempt to find the preloaded class instead of having to do NameError catching below.
+        candidates.each do |candidate|
+          constants = ActiveSupport::Dependencies::Reference.send(:class_variable_get, :@@constants)
+          if constants.key?(candidate) && (constant = constants[candidate]) <= Tagtical::Tag # must check for key first, do not want to trigger default proc.
+            return constant
+          end
+        end
+
+        # Logic comes from ActiveRecord::Base#compute_type.
+        candidates.each do |candidate|
+          begin
+            constant = ActiveSupport::Dependencies.constantize(candidate)
+            return constant if candidate == constant.to_s && constant <= Tagtical::Tag
+          rescue NameError => e
+            # We don't want to swallow NoMethodError < NameError errors
+            raise e unless e.instance_of?(NameError)
+          rescue ArgumentError
+          end
+        end
+
+        nil
+      end
+    end
+
+  end
+end

data/lib/tagtical/tag_list.rb

@@ -0,0 +1,133 @@
+module Tagtical
+  class TagList < Array
+    class TagValue < String
+      attr_accessor :relevance
+      def initialize(value, relevance=nil)
+        @relevance = relevance
+        super(value.to_s)
+      end
+    end
+    
+    cattr_accessor :delimiter
+    self.delimiter = ','
+
+    attr_accessor :owner
+
+    def initialize(*args)
+      add(*args)
+    end
+  
+    ##
+    # Returns a new TagList using the given tag string.
+    #
+    # Example:
+    #   tag_list = TagList.from("One , Two,  Three")
+    #   tag_list # ["One", "Two", "Three"]
+    def self.from(string)
+      if string.is_a?(Hash)
+        new(string)
+      else
+        glue   = delimiter.ends_with?(" ") ? delimiter : "#{delimiter} "
+        string = string.join(glue) if string.respond_to?(:join)
+
+        new.tap do |tag_list|
+          string = string.to_s.dup
+
+          # Parse the quoted tags
+          string.gsub!(/(\A|#{delimiter})\s*"(.*?)"\s*(#{delimiter}\s*|\z)/) { tag_list << $2; $3 }
+          string.gsub!(/(\A|#{delimiter})\s*'(.*?)'\s*(#{delimiter}\s*|\z)/) { tag_list << $2; $3 }
+
+          tag_list.add(string.split(delimiter))
+        end
+      end
+    end
+
+    def concat(values)
+      super(values.map! { |v| convert_tag_value(v) })
+    end
+
+    def push(value)
+      super(convert_tag_value(value))
+    end
+    alias << push
+
+    ##
+    # Add tags to the tag_list. Duplicate or blank tags will be ignored.
+    # Use the <tt>:parse</tt> option to add an unparsed tag string.
+    #
+    # Example:
+    #   tag_list.add("Fun", "Happy")
+    #   tag_list.add("Fun, Happy", :parse => true)
+    #   tag_list.add("Fun" => "0.546", "Happy" => 0.465) # add relevance
+    def add(*values)
+      extract_and_apply_options!(values)
+      concat(values)
+      clean!
+      self
+    end
+
+    ##
+    # Remove specific tags from the tag_list.
+    # Use the <tt>:parse</tt> option to add an unparsed tag string.
+    #
+    # Example:
+    #   tag_list.remove("Sad", "Lonely")
+    #   tag_list.remove("Sad, Lonely", :parse => true)
+    def remove(*values)
+      extract_and_apply_options!(values)
+      delete_if { |value| values.include?(value) }
+      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.
+    #
+    # Example:
+    #   tag_list = TagList.new("Round", "Square,Cube")
+    #   tag_list.to_s # 'Round, "Square,Cube"'
+    def to_s
+      tags = frozen? ? self.dup : self
+      tags.send(:clean!)
+
+      tags.map do |value|
+        value.include?(delimiter) ? "\"#{value}\"" : value
+      end.join(delimiter.ends_with?(" ") ? delimiter : "#{delimiter} ")
+    end
+
+    # Builds an option statement for an ActiveRecord table.
+    def to_sql_conditions(options={})
+      options.reverse_merge!(:class => Tagtical::Tag, :column => "value", :operator => "=")
+      "(" + map { |t| options[:class].send(:sanitize_sql, ["#{options[:class].table_name}.#{options[:column]} #{options[:operator]} ?", t]) }.join(" OR ") + ")"
+    end
+
+    private
+  
+    # Remove whitespace, duplicates, and blanks.
+    def clean!
+      reject!(&:blank?)
+      each(&:strip!)
+      uniq!(&:downcase)
+    end
+
+    def extract_and_apply_options!(args)
+      if args.size==1 && args[0].is_a?(Hash)
+        args.replace(args[0].map { |value, relevance| TagValue.new(value, relevance) })
+      else
+        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
+    end
+
+    def convert_tag_value(value)
+      value.is_a?(TagValue) ? value : TagValue.new(value)
+    end
+
+  end
+end

data/lib/tagtical/taggable/cache.rb

@@ -0,0 +1,53 @@
+module Tagtical::Taggable
+  module Cache
+    def self.included(base)
+      # Skip adding caching capabilities if table not exists or no cache columns exist
+      return unless base.table_exists? && base.tag_types.any? { |context| base.column_names.include?("cached_#{context.to_s.singularize}_list") }
+
+      base.send :include, Tagtical::Taggable::Cache::InstanceMethods
+      base.extend Tagtical::Taggable::Cache::ClassMethods
+      
+      base.class_eval do
+        before_save :save_cached_tag_list        
+      end
+      
+      base.initialize_tagtical_cache
+    end
+    
+    module ClassMethods
+      def initialize_tagtical_cache
+        tag_types.map(&:to_s).each do |tag_type|
+          class_eval %(
+            def self.caching_#{tag_type.singularize}_list?
+              caching_tag_list_on?("#{tag_type}")
+            end        
+          )
+        end        
+      end
+      
+      def acts_as_taggable(*args)
+        super(*args)
+        initialize_tagtical_cache
+      end
+      
+      def caching_tag_list_on?(context)
+        column_names.include?("cached_#{context.to_s.singularize}_list")
+      end
+    end
+    
+    module InstanceMethods      
+      def save_cached_tag_list
+        tag_types.each do |tag_type|
+          if self.class.send("caching_#{tag_type.singularize}_list?")
+            if tag_list_cache_set_on?(tag_type)
+              list = tag_list_cache_on(tag_type.singularize).to_a.flatten.compact.join(', ')
+              self["cached_#{tag_type.singularize}_list"] = list
+            end
+          end
+        end
+        
+        true
+      end
+    end
+  end
+end

data/lib/tagtical/taggable/collection.rb

@@ -0,0 +1,141 @@
+module Tagtical::Taggable
+  module Collection
+    def self.included(base)
+      base.send :include, Tagtical::Taggable::Collection::InstanceMethods
+      base.extend Tagtical::Taggable::Collection::ClassMethods
+      base.initialize_tagtical_collection
+    end
+    
+    module ClassMethods
+      def initialize_tagtical_collection
+        tag_types.each do |tag_type|
+          class_eval %(
+            def self.#{tag_type.singularize}_counts(options={})
+              tag_counts_on('#{tag_type}', options)
+            end
+
+            def #{tag_type.singularize}_counts(options = {})
+              tag_counts_on('#{tag_type}', options)
+            end
+
+            def top_#{tag_type}(limit = 10)
+              tag_counts_on('#{tag_type}', :order => 'count desc', :limit => limit.to_i)
+            end
+
+            def self.top_#{tag_type}(limit = 10)
+              tag_counts_on('#{tag_type}', :order => 'count desc', :limit => limit.to_i)
+            end        
+          )
+        end        
+      end
+      
+      def acts_as_taggable(*args)
+        super(*args)
+        initialize_tagtical_collection
+      end
+      
+      def tag_counts_on(context, options = {})
+        all_tag_counts(options.merge({:on => context.to_s}))
+      end
+      
+      ##
+      # Calculate the tag counts for all tags.
+      #
+      # @param [Hash] options 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
+      #                       * :on         - Scope the find to only include a certain tag type
+      def all_tag_counts(options = {})
+        options.assert_valid_keys :start_at, :end_at, :conditions, :at_least, :at_most, :order, :limit, :on, :id
+
+        scope = if ActiveRecord::VERSION::MAJOR >= 3
+                  {}
+                else
+                  scope(:find) || {}           
+                end
+
+        ## Generate conditions:
+        options[:conditions] = sanitize_sql(options[:conditions]) if options[:conditions]     
+
+        start_at_conditions  = sanitize_sql(["#{Tagtical::Tagging.table_name}.created_at >= ?", options.delete(:start_at)])  if options[:start_at]
+        end_at_conditions    = sanitize_sql(["#{Tagtical::Tagging.table_name}.created_at <= ?", options.delete(:end_at)])    if options[:end_at]
+        
+        taggable_conditions  = sanitize_sql(["#{Tagtical::Tagging.table_name}.taggable_type = ?", base_class.name])
+        taggable_conditions  << sanitize_sql([" AND #{Tagtical::Tagging.table_name}.taggable_id = ?", options.delete(:id)])  if options[:id]
+
+        sti_conditions = Tagtical::Tag::Type[options[:on]].finder_type_condition if options[:on]
+
+        tagging_conditions = [
+          taggable_conditions,
+          scope[:conditions],
+          start_at_conditions,
+          end_at_conditions
+        ].compact.reverse
+
+        tag_conditions = [
+          options[:conditions],
+          sti_conditions
+        ].compact.reverse
+        
+        ## Generate joins:
+        taggable_join = "INNER JOIN #{table_name} ON #{table_name}.#{primary_key} = #{Tagtical::Tagging.table_name}.taggable_id"
+        taggable_join << " AND #{table_name}.#{inheritance_column} = '#{name}'" unless descends_from_active_record? # Current model is STI descendant, so add type checking to the join condition      
+
+        tagging_joins = [
+          taggable_join,
+          scope[:joins]
+        ].compact
+
+        tag_joins = [
+        ].compact
+
+        [tagging_joins, tag_joins].each(&:reverse!) if ActiveRecord::VERSION::MAJOR < 3
+
+        ## Generate scope:
+        tagging_scope = Tagtical::Tagging.select("#{Tagtical::Tagging.table_name}.tag_id, COUNT(#{Tagtical::Tagging.table_name}.tag_id) AS tags_count")
+        tag_scope = Tagtical::Tag.select("#{Tagtical::Tag.table_name}.*, #{Tagtical::Tagging.table_name}.tags_count AS count").order(options[:order]).limit(options[:limit])
+
+        # Joins and conditions
+        tagging_joins.each      { |join|      tagging_scope = tagging_scope.joins(join)      }        
+        tagging_conditions.each { |condition| tagging_scope = tagging_scope.where(condition) }
+
+        tag_joins.each          { |join|      tag_scope     = tag_scope.joins(join)          }
+        tag_conditions.each     { |condition| tag_scope     = tag_scope.where(condition)     }
+
+        # GROUP BY and HAVING clauses:
+        at_least  = sanitize_sql(['tags_count >= ?', options.delete(:at_least)]) if options[:at_least]
+        at_most   = sanitize_sql(['tags_count <= ?', options.delete(:at_most)]) if options[:at_most]
+        having    = ["COUNT(#{Tagtical::Tagging.table_name}.tag_id) > 0", at_least, at_most].compact.join(' AND ')
+
+        group_columns = "#{Tagtical::Tagging.table_name}.tag_id"
+
+        if ActiveRecord::VERSION::MAJOR >= 3
+          # Append the current scope to the scope, because we can't use scope(:find) in RoR 3.0 anymore:
+          scoped_select = "#{table_name}.#{primary_key}"
+          tagging_scope = tagging_scope.where("#{Tagtical::Tagging.table_name}.taggable_id IN(#{select(scoped_select).to_sql})").
+                                        group(group_columns).
+                                        having(having)
+        else
+          # Having is not available in 2.3.x:
+          group_by  = "#{group_columns} HAVING COUNT(*) > 0"
+          group_by << " AND #{having}" unless having.blank?
+          tagging_scope = tagging_scope.group(group_by)
+        end
+
+        tag_scope = tag_scope.joins("JOIN (#{tagging_scope.to_sql}) AS taggings ON taggings.tag_id = tags.id")
+        tag_scope
+      end
+    end
+    
+    module InstanceMethods
+      def tag_counts_on(context, options={})
+        self.class.tag_counts_on(context, options.merge(:id => id))
+      end
+    end
+  end
+end