70 lines
2.8 KiB
Plaintext
70 lines
2.8 KiB
Plaintext
= The Acts As Taggable Mixin
|
||
|
||
== Installation
|
||
|
||
To install or update the gem, simply execute:
|
||
|
||
gem install acts_as_taggable
|
||
|
||
To use the 'acts_as_taggable' library in your Rails application after installing
|
||
the gem, add this line at the end of your 'config/environment.rb' file:
|
||
|
||
require_gem 'acts_as_taggable'
|
||
|
||
== Usage Instructions
|
||
|
||
To use the acts_as_taggable mixin with your ActiveRecord objects, you must use
|
||
a normalized database schema for tagging (also know as folksnomies).
|
||
|
||
This means that you must have a table solely for holding tag names. Usually,
|
||
this table is named 'tags' having at least 2 columns: primary key (usually
|
||
an autoincrement integer called 'id' - the AR standard for PKs) and a 'name'
|
||
columns, usually a varchar. You must also have a defined ActiveRecord model
|
||
class that relates to this table, by default called 'Tag'.
|
||
|
||
For associating tags to your objects you also must have join tables that are
|
||
composed of at least 2 columns: the tags table foreign key (by default 'tag_id')
|
||
and your taggable object table foreign key.
|
||
|
||
If you´re using the simple has_and_belongs_to_many model, you must NOT have a
|
||
primary key (usually an 'id' column) defined on the join table. If you´re using
|
||
a full join model, you must add a primary key column to the join table. Please
|
||
see the RDoc documentation on acts_as_taggable macro and the :join_class_name
|
||
option for the differences between these two approaches.
|
||
|
||
For example, suppose you are tagging photos and you hold your photo data thru
|
||
the Photo model and on the 'photos' table. Your database schema would look
|
||
something like this (example suited for MySQL):
|
||
|
||
CREATE TABLE `tags` (
|
||
`id` int(11) NOT NULL auto_increment,
|
||
`name` varchar(255) default NULL,
|
||
PRIMARY KEY (`id`)
|
||
)
|
||
|
||
CREATE TABLE `tags_photos` (
|
||
`tag_id` int(11) NOT NULL,
|
||
`photo_id` int(11) NOT NULL
|
||
)
|
||
|
||
CREATE TABLE `photos` (
|
||
`id` int(11) NOT NULL auto_increment,
|
||
`title` varchar(255) default NULL,
|
||
`author_name` varchar(255) default NULL,
|
||
`image_path` varchar(255) default NULL,
|
||
PRIMARY KEY (`id`)
|
||
)
|
||
|
||
You would normally define 2 models to relate to these tables:
|
||
|
||
class Tag < ActiveRecord::Base
|
||
end
|
||
|
||
class Photo < ActiveRecord::Base
|
||
acts_as_taggable
|
||
end
|
||
|
||
Now you can easily apply and search for tags on photos in your Rails application.
|
||
|
||
This assumes you´re using only default naming conventions. For using the mix-in
|
||
with non-standard naming conventions, please see the proper RDoc documentation. |