README.txt

Please go to http://github.com/aq1018/dm-is-taggable/tree/master/README.textile for a pretty readme

h1. dm-is-taggable

dm-is-taggable is a tagging system built for datamapper. It has supports for multiple tagger types and taggable types.
Each tagger can tag different taggable objects.


h2. Installation

h3. Download the plugin

In your console:
<pre><code>
git clone git://github.com/aq1018/dm-is-taggable.git
</code></pre>

h3. Install the gem

In your console:
<pre><code>
cd dm-is-taggable
sudo rake install
</code></pre>

h3. Include it Merb

In merb init.rb:

<pre><code>
dependency "dm-is-taggable"
</code></pre>


h2. Using dm-is-taggable in your code

h3. Define taggers

<pre><code>
  class User
    include DataMapper::Resource
    property :id, Serial
    property :name, String
    is :tagger, :on => ["Article", "Picture"]
  end

  class Bot
    include DataMapper::Resource
    property :id, Serial
    property :name, String
    is :tagger, :on => ["Article", "Picture"]
  end
</code></pre>

h3. Define taggables

<pre><code>
  class Article
    include DataMapper::Resource
    property :id, Serial
    is :taggable, :by => ["User", "Bot"]
  end

  class Picture
    include DataMapper::Resource
    property :id, Serial
    is :taggable, :by => ["User", "Bot"]
  end
</code></pre>

h3. Create tags

<pre><code>
  
  @picture = Picture.first
  @scott = User.first
  
  # You can tag like this
  @picture.tag(:with => "shanghai, bar, beer", :by => @scott)
  
  # or like this
  # Note: this doesn't remove the previous tags
  Tag.as(@scott) do
    @picture.tag(:with => "cool, tag1, tag2")
  end
  
  # or like this
  # Note, this removes all previous tags
  Tag.as(@scott) do
    @picture.taglist("cool, tag1, tag2")
  end
</code></pre>

h3. Retrieve objects with tags

<pre><code>
  
  # find pictures tagged with tag1 and tag2
  Picture.find(:with => "tag1, tag2")
  
  # find pictures tagged with tag1 or tag2
  Picture.find(:with => "tag1, tag2", :match => :any)
  
  # find pictures tagged with tag1 or tag2, tagged by @user1
  Picture.find(:with => "tag1, tag2", :match => :any, :by => @user1)
  
  # find pictures tagged with tag1 or tag2, tagged by all users
  Picture.find(:with => "tag1, tag2", :match => :any, :by => User)
  
  # or you can do scoped way
  
  # find pictures tagged with tag1 or tag2, tagged by all users
  Tag.as(User) do
    Picture.find(:with => "tag1, tag2", :match => :any)
  end
  
  # find pictures tagged with tag1 or tag2, tagged by @user1
  Tag.as(@user1) do
    Picture.find(:with => "tag1, tag2", :match => :any)
  end
  
    
  # You can tag like this
  @picture.tag(:with => "shanghai, bar, beer", :by => @scott)
  
  # or like this
  # Note: this doesn't remove the previous tags
  Tag.as(@scott) do
    @picture.tag(:with => "cool, tag1, tag2")
  end
  
  # or like this
  # Note, this removes all previous tags
  Tag.as(@scott) do
    @picture.taglist("cool, tag1, tag2")
  end
</code></pre>

h3. Retrieve tags with objects

<pre><code>
  
  @picture1 = Picture.first
  
  # get all tags associated with @picture2 as a string
  @picture1.taglist
  
  # or as tag objects
  @picture1.tags
  
  # tags tagged by users
  @picture1.tags_by_users
  
  # find tags by all users
  Tag.by(User)

  # find tags by a user
  Tag.by(@user)

  # find tags on all pictures
  Tag.on(Picture)
  
  # find tags on a picture
  Tag.on(@picture1)
  
  # find tags by a user, on all pictures
  Tag.by(@user).on(Pictures)
  
  # find tags by all users on a picture
  Tag.by(User).on(@picture)
  
  # find tags by a user on a picture
  Tag.by(@user).on(@picture)
  
</code></pre>

h3. Counting tags

<pre><code>
  
  # Count how many articles are tagged by @user1
  Tag.tagged_count(:by => @user1, :on => Article)
  
  # Count how many articles are tagged by @user1 with "tag1"
  Tag.tagged_count(:by => @user1, :on => Article, :with => "tag1")
    
</code></pre>