Mongoid Taggable

Mongoid Taggable provides some helpers to create taggable documents.

Installation

This project is a fork that has drifted quite a bit from the original maintainer's version, and currently has not been re-released as a gem. See details on the fork changes in the CHANGELOG file.

Using Bundler, in your Gemfile:

gem 'mongoid_taggable', :git => 'https://github.com/ches/mongoid_taggable.git',
                        :branch => 'integration'

or as a Rails Plugin:

rails plugin install git://github.com/ches/mongoid_taggable.git

Basic Usage

To make a document taggable you need to include Mongoid::Taggable into your document and call the taggable macro with optional arguments:

class Post
  include Mongoid::Document
  include Mongoid::Taggable
  
  field :title
  field :content
  
  taggable
end

Then in your form, for example:

<% form_for @post do |f| %>
  <p>
    <%= f.label :title %><br />
    <%= f.text_field :title %>
  </p>
  <p>
    <%= f.label :content %><br />
    <%= f.text_area :content %>
  </p>
  <p>
    <%= f.label :tags %><br />
    <%= f.text_field :tags %>
  </p>
  <p>
    <button type="submit">Send</button>
  </p>
<% end %>

The text field should receive a list of tags separated by comma (below in this document you will see how to change the separator).

Your document will have a custom tags= setter which can accept either an ordinary Array or this separator-delineated String.

Tag Aggregation with Counts

This lib can automatically create an aggregate collection of tags and their counts for you, updated as documents are saved. This is useful for getting a list of all tags used in documents of this collection or to create a tag cloud. This is disabled by default for sake of performance where it is unneeded -- see the following example to understand how to use it:

class Post
  include Mongoid::Document
  include Mongoid::Taggable

  field :title
  field :content

  taggable :aggregation => true
end

Post.create!(:tags => "food,ant,bee")
Post.create!(:tags => "juice,food,bee,zip")
Post.create!(:tags => "honey,strip,food")

Post.tags
# => ["ant", "bee", "food", "honey", "juice", "strip", "zip"]

Post.tags_with_weight # will retrieve:
# [
#   ['ant', 1],
#   ['bee', 2],
#   ['food', 3],
#   ['honey', 1],
#   ['juice', 1],
#   ['strip', 1],
#   ['zip', 1]
# ]

You may also trigger aggregation on-demand rather than setting the automatic option, to run it from a background task for instance, by calling Post.aggregate_tags!.

If you need to modify the criteria used for the aggregation you may do so as an option to 'taggable':

class Post
  include Mongoid::Document
  include Mongoid::Taggable
  
  field :title
  field :content
  field :published, :type => Boolean
  
  taggable :aggregation_options => { :query => { :published => true } }
end

A full list of available options can be found at the ruby driver API (consult the appropriate version).

Changing default separator

To change the default separator you may pass a separator argument to the macro:

class Post
  include Mongoid::Document
  include Mongoid::Taggable

  field :title
  field :content

  taggable :separator => ' '    # tags will be delineated by spaces
end

TODO:

• Should subclasses output map/reduce aggregation results to their own collections?
• Perhaps implement operators, <<, etc. for full-on set semantics. See: https://github.com/mlabs/mongoid_taggable/commit/13195805e110a7113b9f04710d9bade39440b63e