Module: ActiveRecord::Base::TaggingExtensions

These extensions make models taggable. This file is automatically generated and required by your app if you run the tagging generator included with has_many_polymorphs.

Public Instance Methods

_add_tags (incoming)

Add tags to self. Accepts a string of tagnames, an array of tagnames, an array of ids, or an array of Tags.

We need to avoid name conflicts with the built-in ActiveRecord association methods, thus the underscores. 

    # File generators/tagging/templates/tagging_extensions.rb, line 10
10:     def _add_tags incoming
11:       taggable?(true)
12:       tag_cast_to_string(incoming).each do |tag_name|
13:         begin
14:           tag = Tag.find_or_create_by_name(tag_name)
15:           raise Tag::Error, "tag could not be saved: #{tag_name}" if tag.new_record?
16:           tag.taggables << self
17:         rescue ActiveRecord::StatementInvalid => e
18:           raise unless e.to_s =~ /duplicate/i
19:         end
20:       end
21:     end

_remove_tags (outgoing)

Removes tags from self. Accepts a string of tagnames, an array of tagnames, an array of ids, or an array of Tags. 

    # File generators/tagging/templates/tagging_extensions.rb, line 24
24:     def _remove_tags outgoing
25:       taggable?(true)
26:       outgoing = tag_cast_to_string(outgoing)
27:   <% if options[:self_referential] %>  
28:       # because of http://dev.rubyonrails.org/ticket/6466
29:       taggings.destroy(*(taggings.find(:all, :include => :<%= parent_association_name -%>).select do |tagging| 
30:         outgoing.include? tagging.<%= parent_association_name -%>.name
31:       end))
32:   <% else -%>   
33:       <%= parent_association_name -%>s.delete(*(<%= parent_association_name -%>s.select do |tag|
34:         outgoing.include? tag.name    
35:       end))
36:   <% end -%>
37:     end

parse_tags (tags) 

     # File generators/tagging/templates/tagging_extensions.rb, line 142
142:     def parse_tags(tags)
143:       return [] if tags.blank?
144:       tags = Array(tags).first
145:       tags = tags.respond_to?(:flatten) ? tags.flatten : tags.split(Tag::DELIMITER)
146:       tags.map { |tag| tag.strip.squeeze(" ") }.flatten.compact.map(&:downcase).uniq
147:     end

tag_list ()

Returns the tags on self as a string. 

    # File generators/tagging/templates/tagging_extensions.rb, line 40
40:     def tag_list
41:       # Redefined later to avoid an RDoc parse error.
42:     end

tag_with (list)

Replace the existing tags on self. Accepts a string of tagnames, an array of tagnames, an array of ids, or an array of Tags. 

     # File generators/tagging/templates/tagging_extensions.rb, line 45
 45:     def tag_with list    
 46:       #:stopdoc:
 47:       taggable?(true)
 48:       list = tag_cast_to_string(list)
 49:              
 50:       # Transactions may not be ideal for you here; be aware.
 51:       Tag.transaction do 
 52:         current = <%= parent_association_name -%>s.map(&:name)
 53:         _add_tags(list - current)
 54:         _remove_tags(current - list)
 55:       end
 56:       
 57:       self
 58:       #:startdoc:
 59:     end
 60: 
 61:    # Returns the tags on <tt>self</tt> as a string.
 62:     def tag_list #:nodoc:
 63:       #:stopdoc:
 64:       taggable?(true)
 65:       <%= parent_association_name -%>s.reload
 66:       <%= parent_association_name -%>s.to_s
 67:       #:startdoc:
 68:     end
 69:     
 70:     private 
 71:     
 72:     def tag_cast_to_string obj #:nodoc:
 73:       case obj
 74:         when Array
 75:           obj.map! do |item|
 76:             case item
 77:               when /^\d+$/, Fixnum then Tag.find(item).name # This will be slow if you use ids a lot.
 78:               when Tag then item.name
 79:               when String then item
 80:               else
 81:                 raise "Invalid type"
 82:             end
 83:           end              
 84:         when String
 85:           obj = obj.split(Tag::DELIMITER).map do |tag_name| 
 86:             tag_name.strip.squeeze(" ")
 87:           end
 88:         else
 89:           raise "Invalid object of class #{obj.class} as tagging method parameter"
 90:       end.flatten.compact.map(&:downcase).uniq
 91:     end 
 92:   
 93:     # Check if a model is in the :taggables target list. The alternative to this check is to explicitly include a TaggingMethods module (which you would create) in each target model.  
 94:     def taggable?(should_raise = false) #:nodoc:
 95:       unless flag = respond_to?(:<%= parent_association_name -%>s)
 96:         raise "#{self.class} is not a taggable model" if should_raise
 97:       end
 98:       flag
 99:     end
100: 
101:   end
102:   
103:   module TaggingFinders
104:     # 
105:     # Find all the objects tagged with the supplied list of tags
106:     # 
107:     # Usage : Model.tagged_with("ruby")
108:     #         Model.tagged_with("hello", "world")
109:     #         Model.tagged_with("hello", "world", :limit => 10)
110:     #
111:     def tagged_with(*tag_list)
112:       options = tag_list.last.is_a?(Hash) ? tag_list.pop : {}
113:       tag_list = parse_tags(tag_list)
114:       
115:       scope = scope(:find)
116:       options[:select] ||= "#{table_name}.*"
117:       options[:from] ||= "#{table_name}, tags, taggings"
118:       
119:       sql  = "SELECT #{(scope && scope[:select]) || options[:select]} "
120:       sql << "FROM #{(scope && scope[:from]) || options[:from]} "
121: 
122:       add_joins!(sql, options, scope)
123:       
124:       sql << "WHERE #{table_name}.#{primary_key} = taggings.taggable_id "
125:       sql << "AND taggings.taggable_type = '#{ActiveRecord::Base.send(:class_name_of_active_record_descendant, self).to_s}' "
126:       sql << "AND taggings.tag_id = tags.id "
127:       
128:       tag_list_condition = tag_list.map {|t| "'#{t}'"}.join(", ")
129:       
130:       sql << "AND (tags.name IN (#{sanitize_sql(tag_list_condition)})) "
131:       sql << "AND #{sanitize_sql(options[:conditions])} " if options[:conditions]
132:       sql << "GROUP BY #{table_name}.id "
133:       sql << "HAVING COUNT(taggings.tag_id) = #{tag_list.size}"
134:       
135:       add_order!(sql, options[:order], scope)
136:       add_limit!(sql, options, scope)
137:       add_lock!(sql, options, scope)
138:       
139:       find_by_sql(sql)
140:     end
141:     
142:     def parse_tags(tags)
143:       return [] if tags.blank?
144:       tags = Array(tags).first
145:       tags = tags.respond_to?(:flatten) ? tags.flatten : tags.split(Tag::DELIMITER)
146:       tags.map { |tag| tag.strip.squeeze(" ") }.flatten.compact.map(&:downcase).uniq
147:     end
148:     
149:   end
150: 
151:   include TaggingExtensions
152:   extend  TaggingFinders
153: end

tagged_with (*tag_list) 

     # File generators/tagging/templates/tagging_extensions.rb, line 111
111:     def tagged_with(*tag_list)
112:       options = tag_list.last.is_a?(Hash) ? tag_list.pop : {}
113:       tag_list = parse_tags(tag_list)
114:       
115:       scope = scope(:find)
116:       options[:select] ||= "#{table_name}.*"
117:       options[:from] ||= "#{table_name}, tags, taggings"
118:       
119:       sql  = "SELECT #{(scope && scope[:select]) || options[:select]} "
120:       sql << "FROM #{(scope && scope[:from]) || options[:from]} "
121: 
122:       add_joins!(sql, options, scope)
123:       
124:       sql << "WHERE #{table_name}.#{primary_key} = taggings.taggable_id "
125:       sql << "AND taggings.taggable_type = '#{ActiveRecord::Base.send(:class_name_of_active_record_descendant, self).to_s}' "
126:       sql << "AND taggings.tag_id = tags.id "
127:       
128:       tag_list_condition = tag_list.map {|t| "'#{t}'"}.join(", ")
129:       
130:       sql << "AND (tags.name IN (#{sanitize_sql(tag_list_condition)})) "
131:       sql << "AND #{sanitize_sql(options[:conditions])} " if options[:conditions]
132:       sql << "GROUP BY #{table_name}.id "
133:       sql << "HAVING COUNT(taggings.tag_id) = #{tag_list.size}"
134:       
135:       add_order!(sql, options[:order], scope)
136:       add_limit!(sql, options, scope)
137:       add_lock!(sql, options, scope)
138:       
139:       find_by_sql(sql)
140:     end