Permalink
Browse files

Replace format documentation to Markdown

  • Loading branch information...
1 parent 62f5fea commit 9ad25f81d04204391f87b5d0a0487bf71e75bb36 caedes committed Dec 19, 2012
Showing with 298 additions and 257 deletions.
  1. +8 −8 CHANGELOG → CHANGELOG.md
  2. +1 −1 MIT-LICENSE → MIT-LICENSE.md
  3. +289 −0 README.md
  4. +0 −248 README.rdoc
View
@@ -1,4 +1,4 @@
-== 2011-08-21
+## 2011-08-21
* escape _ and % for mysql and postgres (@tilsammans)
* Now depends on mysql2 gem
* tagged_with :any is chainable now (@jeffreyiacono)
@@ -8,28 +8,28 @@
* remove warning for rails 3.1 about class_inheritable_attribute
* use ActiveRecord migration_number to avoid clashs (@atd)
-== 2010-02-17
+## 2010-02-17
* Converted the plugin to be compatible with Rails3
-== 2009-12-02
+## 2009-12-02
* PostgreSQL is now supported (via morgoth)
-== 2008-07-17
+## 2008-07-17
* Can now use a named_scope to find tags!
-== 2008-06-23
+## 2008-06-23
* Can now find related objects of another class (tristanzdunn)
* Removed extraneous down migration cruft (azabaj)
-== 2008-06-09
+## 2008-06-09
* Added support for Single Table Inheritance
* Adding gemspec and rails/init.rb for gemified plugin
-== 2007-12-12
+## 2007-12-12
* Added ability to use dynamic tag contexts
- * Fixed missing migration generator
+ * Fixed missing migration generator
@@ -1,4 +1,4 @@
-Copyright (c) 2007 Michael Bleigh and Intridea Inc.
+__Copyright (c) 2007 Michael Bleigh and Intridea Inc.__
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
View
289 README.md
@@ -0,0 +1,289 @@
+# ActsAsTaggableOn
+[![Build Status](https://secure.travis-ci.org/mbleigh/acts-as-taggable-on.png)](http://travis-ci.org/mbleigh/acts-as-taggable-on)
+
+This plugin was originally based on Acts as Taggable on Steroids by Jonathan Viney.
+It has evolved substantially since that point, but all credit goes to him for the
+initial tagging functionality that so many people have used.
+
+For instance, in a social network, a user might have tags that are called skills,
+interests, sports, and more. There is no real way to differentiate between tags and
+so an implementation of this type is not possible with acts as taggable on steroids.
+
+Enter Acts as Taggable On. Rather than tying functionality to a specific keyword
+(namely `tags`), acts as taggable on allows you to specify an arbitrary number of
+tag "contexts" that can be used locally or in combination in the same way steroids
+was used.
+
+## Installation
+
+### Rails 2.x
+
+Not supported any more! It is time for update guys.
+
+### Rails 3.x
+
+To use it, add it to your Gemfile:
+
+```ruby
+gem 'acts-as-taggable-on', '~> 2.3.1'
+```
+
+#### Post Installation
+
+```shell
+rails generate acts_as_taggable_on:migration
+rake db:migrate
+```
+
+## Testing
+
+Acts As Taggable On uses RSpec for its test coverage. Inside the gem
+directory, you can run the specs for RoR 3.x with:
+
+```shell
+rake spec
+```
+
+## Usage
+
+```ruby
+class User < ActiveRecord::Base
+ # Alias for acts_as_taggable_on :tags
+ acts_as_taggable
+ acts_as_taggable_on :skills, :interests
+end
+
+@user = User.new(:name => "Bobby")
+@user.tag_list = "awesome, slick, hefty" # this should be familiar
+@user.skill_list = "joking, clowning, boxing" # but you can do it for any context!
+@user.skill_list # => ["joking","clowning","boxing"] as TagList
+@user.save
+
+@user.tags # => [<Tag name:"awesome">,<Tag name:"slick">,<Tag name:"hefty">]
+@user.skills # => [<Tag name:"joking">,<Tag name:"clowning">,<Tag name:"boxing">]
+
+@frankie = User.create(:name => "Frankie", :skill_list => "joking, flying, eating")
+User.skill_counts # => [<Tag name="joking" count=2>,<Tag name="clowning" count=1>...]
+@frankie.skill_counts
+```
+
+To preserve the order in which tags are created use `acts_as_ordered_taggable`:
+
+```ruby
+class User < ActiveRecord::Base
+ # Alias for acts_as_ordered_taggable_on :tags
+ acts_as_ordered_taggable
+ acts_as_ordered_taggable_on :skills, :interests
+end
+
+@user = User.new(:name => "Bobby")
+@user.tag_list = "east, south"
+@user.save
+
+@user.tag_list = "north, east, south, west"
+@user.save
+
+@user.reload
+@user.tag_list # => ["north", "east", "south", "west"]
+```
+
+### Finding Tagged Objects
+
+Acts As Taggable On utilizes named_scopes to create an association for tags.
+This way you can mix and match to filter down your results, and it also improves
+compatibility with the [will_paginate](https://github.com/mislav/will_paginate) gem:
+
+```ruby
+class User < ActiveRecord::Base
+ acts_as_taggable_on :tags, :skills
+ scope :by_join_date, order("created_at DESC")
+end
+
+User.tagged_with("awesome").by_date
+User.tagged_with("awesome").by_date.paginate(:page => params[:page], :per_page => 20)
+
+# Find a user with matching all tags, not just one
+User.tagged_with(["awesome", "cool"], :match_all => true)
+
+# Find a user with any of the tags:
+User.tagged_with(["awesome", "cool"], :any => true)
+
+# Find a user that not tags with awesome or cool:
+User.tagged_with(["awesome", "cool"], :exclude => true)
+
+# Find a user with any of tags based on context:
+User.tagged_with(['awesome, cool'], :on => :tags, :any => true).tagged_with(['smart', 'shy'], :on => :skills, :any => true)
+```
+
+You can also use `:wild => true` option along with `:any` or `:exclude` option. It will looking for `%awesome%` and `%cool%` in sql.
+
+__Tip:__ `User.tagged_with([])` or '' will return `[]`, but not all records.
+
+### Relationships
+
+You can find objects of the same type based on similar tags on certain contexts.
+Also, objects will be returned in descending order based on the total number of
+matched tags.
+
+```ruby
+@bobby = User.find_by_name("Bobby")
+@bobby.skill_list # => ["jogging", "diving"]
+
+@frankie = User.find_by_name("Frankie")
+@frankie.skill_list # => ["hacking"]
+
+@tom = User.find_by_name("Tom")
+@tom.skill_list # => ["hacking", "jogging", "diving"]
+
+@tom.find_related_skills # => [<User name="Bobby">,<User name="Frankie">]
+@bobby.find_related_skills # => [<User name="Tom">]
+@frankie.find_related_skills # => [<User name="Tom">]
+```
+
+### Dynamic Tag Contexts
+
+In addition to the generated tag contexts in the definition, it is also possible
+to allow for dynamic tag contexts (this could be user generated tag contexts!)
+
+```ruby
+@user = User.new(:name => "Bobby")
+@user.set_tag_list_on(:customs, "same, as, tag, list")
+@user.tag_list_on(:customs) # => ["same","as","tag","list"]
+@user.save
+@user.tags_on(:customs) # => [<Tag name='same'>,...]
+@user.tag_counts_on(:customs)
+User.tagged_with("same", :on => :customs) # => [@user]
+```
+
+### Tag Ownership
+
+Tags can have owners:
+
+```ruby
+class User < ActiveRecord::Base
+ acts_as_tagger
+end
+
+class Photo < ActiveRecord::Base
+ acts_as_taggable_on :locations
+end
+
+@some_user.tag(@some_photo, :with => "paris, normandy", :on => :locations)
+@some_user.owned_taggings
+@some_user.owned_tags
+Photo.tagged_with("paris", :on => :locations, :owned_by => @some_user)
+@some_photo.locations_from(@some_user) # => ["paris", "normandy"]
+@some_photo.owner_tags_on(@some_user, :locations) # => [#<ActsAsTaggableOn::Tag id: 1, name: "paris">...]
+@some_photo.owner_tags_on(nil, :locations) # => Ownerships equivalent to saying @some_photo.locations
+@some_user.tag(@some_photo, :with => "paris, normandy", :on => :locations, :skip_save => true) #won't save @some_photo object
+```
+
+### Dirty objects
+
+```ruby
+@bobby = User.find_by_name("Bobby")
+@bobby.skill_list # => ["jogging", "diving"]
+
+@boddy.skill_list_changed? #=> false
+@boddy.changes #=> {}
+
+@bobby.skill_list = "swimming"
+@bobby.changes.should == {"skill_list"=>["jogging, diving", ["swimming"]]}
+@boddy.skill_list_changed? #=> true
+
+@bobby.skill_list_change.should == ["jogging, diving", ["swimming"]]
+```
+
+### Tag cloud calculations
+
+To construct tag clouds, the frequency of each tag needs to be calculated.
+Because we specified `acts_as_taggable_on` on the `User` class, we can
+get a calculation of all the tag counts by using `User.tag_counts_on(:customs)`. But what if we wanted a tag count for
+an single user's posts? To achieve this we call tag_counts on the association:
+
+```ruby
+User.find(:first).posts.tag_counts_on(:tags)
+```
+
+A helper is included to assist with generating tag clouds.
+
+Here is an example that generates a tag cloud.
+
+Helper:
+
+```ruby
+module PostsHelper
+ include ActsAsTaggableOn::TagsHelper
+end
+```
+
+Controller:
+
+```ruby
+class PostController < ApplicationController
+ def tag_cloud
+ @tags = Post.tag_counts_on(:tags)
+ end
+end
+```
+
+View:
+
+```erb
+<% tag_cloud(@tags, %w(css1 css2 css3 css4)) do |tag, css_class| %>
+ <%= link_to tag.name, { :action => :tag, :id => tag.name }, :class => css_class %>
+<% end %>
+```
+
+CSS:
+
+```css
+.css1 { font-size: 1.0em; }
+.css2 { font-size: 1.2em; }
+.css3 { font-size: 1.4em; }
+.css4 { font-size: 1.6em; }
+```
+
+## Configuration
+
+If you would like to remove unused tag objects after removing taggings, add:
+
+```ruby
+ActsAsTaggableOn.remove_unused_tags = true
+```
+
+If you want force tags to be saved downcased:
+
+```ruby
+ActsAsTaggableOn.force_lowercase = true
+```
+
+If you want tags to be saved parametrized (you can redefine to_param as well):
+
+```ruby
+ActsAsTaggableOn.force_parameterize = true
+```
+
+If you would like tags to be case-sensitive and not use LIKE queries for creation:
+
+```ruby
+ActsAsTaggableOn.strict_case_match = true
+```
+
+## Changelog
+
+See [CHANGELOG](https://github.com/mbleigh/acts-as-taggable-on/blob/master/CHANGELOG.md).
+
+## Contributors
+
+We have a long list of valued contributors. [Check them all](https://github.com/mbleigh/acts-as-taggable-on/contributors)
+
+## Maintainers
+
+* [Artem Kramarenko](https://github.com/artemk) (artemk)
+
+## Author
+
+* [Michael Bleigh](https://github.com/mbleigh)
+
+Copyright (c) 2007-2011 Michael Bleigh (http://mbleigh.com/) and Intridea Inc. (http://intridea.com/), released under the [MIT license](https://github.com/mbleigh/acts-as-taggable-on/blob/master/MIT-LICENSE.md)
Oops, something went wrong.

0 comments on commit 9ad25f8

Please sign in to comment.