Skip to content
Tagging for Ruby on Rails
Find file
New pull request
Pull request Compare This branch is even with jviney:git-svn@294.
Fetching latest commit...
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


= acts_as_taggable_on_steroids

If you find this plugin useful, please consider a donation to show your support!
  Email address:
== Instructions

This plugin is based on acts_as_taggable by DHH but includes extras
such as tests, smarter tag assignment, and tag cloud calculations.

Thanks to for allowing this plugin to be released. Please check out
their site to show your support.

== Resources

  * script/plugin install

== Usage

=== Prepare database

Generate and apply the migration:

  ruby script/generate acts_as_taggable_migration
  rake db:migrate

=== Basic tagging

Using the examples from the tests, let's suppose we have users that have many posts and we want those
posts to be able to be tagged by the user.

As usual, we add +acts_as_taggable+ to the Post class:

  class Post < ActiveRecord::Base
    belongs_to :user
We can now use the tagging methods provided by acts_as_taggable, <tt>tag_list</tt> and <tt>tag_list=</tt>. Both these
methods work like regular attribute accessors.

  p = Post.find(:first)
  p.tag_list.to_s # ""
  p.tag_list = "Funny, Silly"
  p.reload.tag_list.to_s # "Funny, Silly"
You can also add or remove arrays of tags.

  p.tag_list.add("Great", "Awful")

=== Finding tagged objects

To retrieve objects tagged with a certain tag, use find_tagged_with.

  Post.find_tagged_with('Funny, Silly')
By default, find_tagged_with will find objects that have any of the given tags. To
find only objects that are tagged with all the given tags, use match_all.

  Post.find_tagged_with('Funny, Silly', :match_all => true)

=== Tag cloud calculations

To construct tag clouds, the frequency of each tag needs to be calculated.
Because we specified +acts_as_taggable+ on the <tt>Post</tt> class, we can
get a calculation of all the tag counts by using <tt>Post.tag_counts</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:

=== Caching

It is useful to cache the list of tags to reduce the number of queries executed. To do this,
add a column named <tt>cached_tag_list</tt> to the model which is being tagged.

  class CachePostTagList < ActiveRecord::Migration
    def self.up
      # You should make sure that the column is long enough to hold
      # the full tag list. In some situations the :text type may be more appropriate.
      add_column :posts, :cached_tag_list, :string

  class Post < ActiveRecord::Base
    # The caching column defaults to cached_tag_list, but can be changed:
    # set_cached_tag_list_column_name "my_caching_column_name"

The details of the caching are handled for you. Just continue to use the tag_list accessor as you normally would.
Note that the cached tag list will not be updated if you directly create Tagging objects or manually append to the
<tt>tags</tt> or <tt>taggings</tt> associations. To update the cached tag list you should call <tt>save_cached_tag_list</tt> manually.

=== Delimiter

If you want to change the delimiter used to parse and present tags, set TagList.delimiter.
For example, to use spaces instead of commas, add the following to config/environment.rb:

  TagList.delimiter = " "

=== Other

Problems, comments, and suggestions all welcome.  
== Credits
Something went wrong with that request. Please try again.