If you're building an ecommerce website that sells a number of different kinds of goods, you might want to institute tagging. This mainstay of many Internet sites makes it easier to categorize items, and can assist your visitors in finding what they're looking for. This four-part article series shows you how to add tagging support to your site using Ruby on Rails. This article is excerpted from chapter seven of the book Practical Rails Projects, written by Eldon Alameda (Apress; ISBN: 1590597818).
Tagging Support - Using the Tagging RubyGem (Page 3 of 4 )
Implementing a tagging system is a complex task and requires a fair amount of code and SQL to be written. Fortunately, we can save days (or weeks) of coding and bug fixing by using the acts_as_taggable gem. acts_as_taggableis an ActiveRecord mix-in that allows you to add tagging capabilities to your ActiveRecord models. Originally coded by Demetrius Nunes,acts_as_taggableis an open source project hosted by RubyForge. The API documentation can be found athttp://taggable.rubyforge.org, and the projectís homepage is http:// rubyforge.org/projects/taggable/.
To installacts_as_taggable, simply execute the following command:
$ sudo gem install acts_as_taggable
-------------------------------------------- Bulk updating Gem source index for: http://gems.rubyforge.org Successfully installed acts_as_taggable-2.0.2 Installing ri documentation for acts_as_taggable-2.0.2... Installing RDoc documentation for acts_as_taggable-2.0.2... --------------------------------------------
The location of the repository depends on your system and RubyGems configuration. On our machine, the gem was installed in/usr/lib/ruby/gems/1.8/gems/acts_as_taggable-2.0.2/.
Tip If desired, you can turn the gem into a plugin. First, change the current directory to thevendor/pluginsdirectory withcd vendor/plugins, and then executegem unpack acts_as_taggable. Next, create a file calledinit.rbin theacts_as_taggablefolder and put the following code in it:require 'taggable'.
We need to tell Rails to load theacts_as_taggablegem at startup, since we are using a gem and not a Rails plugin. To do this, add the linerequire_gem 'acts_as_taggable'to the last line ofconfig/environment.rb, as shown here:
# Include your application configuration below require_gem 'acts_as_taggable'
After you have saved the changes and restarted WEBrick, you can specify that an ActiveRecord model should be taggable by adding the lineacts_as_taggableto the code. This gives you access to the instance methods shown in Table 7-1 and the class methods shown in Table 7-2.
Tip See the online documentation athttp://taggable.rubyforge.org/for the complete and latest version information aboutacts_as_taggable.
Table 7-1.Instance Methods Introduced by acts_as_taggable
Assigns the specified tags to the book. This is done by parsing the tagsparameter. The tagsparameter is a string, and tags are separated by spaces. A different separator can be used by adding the :separator => ' 'option to the optionshash. Add the :clear => true option to remove all existing tags before assigning the new ones.
Returns an array of tags that have been assigned to the book. The collection can be forced to be reloaded from the database by setting reload to true.
Finds books that share most of the same tags as the current book. The optionshash can be used for specifying how many books should be returned by the method. The default is five. To specify a different value, add :limit => nto the optionshash. Note that you need to specify the separator with the separator parameter, if you are not using the default separator.
Returns trueif the book has been assigned the specified tag. The reloadparameter can be used to force a reload of the book, before the check is performed.
Tip The RubyGems packaging system provides a handy command that can be used for accessing the documentation of packages installed with RubyGems, includingacts_as_taggable. This is useful, for example, if you are working offline and canít read the online documentation. Executegem_serverto start a web server on your local machine, which allows you to access the documentation athttp://localhost:8808.
Table 7-2. Class Methods Introduced by acts_as_taggable
Finds related books and returns them as an array. The method returns the five books that share the most tags with the specified book. Theoptionshash can be used to set the maximum amount of books returned.
Returns tags that are related to the ones specified with thetagsparameter. Theoptionshash can be used to set the maximum amount of tags returned.
Finds books that are tagged with the specified options. This can be used to find books that have any or all of the specified tags, for example. See the online documentation for a complete list of available options.