From 7ecc266e9714d2df540e0b96f6d4c6659452b90c Mon Sep 17 00:00:00 2001 From: Billy Date: Mon, 5 Aug 2013 02:43:11 +0800 Subject: [PATCH 1/2] fix README: add parse:true documentation --- README.md | 47 +++++++++++++++++++++++++++++++++++++---------- 1 file changed, 37 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 6b2e269d8..cb28d96b1 100644 --- a/README.md +++ b/README.md @@ -65,6 +65,10 @@ If you want, add a `.ruby-version` file in the project root (and use rbenv or RV ## Usage +*Note: The following examples with delimiters inside string argument all +depend on `ActsAsTaggableOn.delimiter` being set to ',' which is the +default. See [configuration](#configuration) for more about delimiter.* + ```ruby class User < ActiveRecord::Base # Alias for acts_as_taggable_on :tags @@ -73,19 +77,42 @@ class User < ActiveRecord::Base 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.tags # => [,,] -@user.skills # => [,,] -@user.skill_list # => ["joking","clowning","boxing"] as TagList +# this should be familiar +@user.tag_list = "awesome, slick, hefty" + +# but you can do it for any context! +@user.skill_list = "joking, clowning, boxing" + +@user.tags +# => [,,] + +@user.skills +# => [,,] + +@user.skill_list +# => ["joking","clowning","boxing"] as TagList + +# remove a single tag +@user.tag_list.remove("awesome") + +# "remove" works with arrays too +@user.tag_list.remove("awesome", "slick") + +# "remove" works with string too, needing "parse: true" option. +@user.tag_list.remove("awesome, slick", parse: true) + +# add a single tag. alias for << +@user.tag_list.add("awesomer") + +# "add" also works with arrays +@user.tag_list.add("awesomer", "slicker") -@user.tag_list.remove("awesome") # remove a single tag -@user.tag_list.remove("awesome, slick") # works with arrays too -@user.tag_list.add("awesomer") # add a single tag. alias for << -@user.tag_list.add("awesomer, slicker") # also works with arrays +# "add" works with string too, needing "parse: true" option. +@user.tag_list.add("awesomer, slicker", parse: true) -User.skill_counts # => [,...] +User.skill_counts +# => [,...] ``` To preserve the order in which tags are created use `acts_as_ordered_taggable`: From 6c6281bf0bbc2061f1757a4b7d629fa658e3856c Mon Sep 17 00:00:00 2001 From: Billy Date: Wed, 1 Jan 2014 03:28:32 +0800 Subject: [PATCH 2/2] seperate usage to several blocks --- README.md | 72 +++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 46 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index cb28d96b1..1f61bfc70 100644 --- a/README.md +++ b/README.md @@ -65,51 +65,71 @@ If you want, add a `.ruby-version` file in the project root (and use rbenv or RV ## Usage -*Note: The following examples with delimiters inside string argument all -depend on `ActsAsTaggableOn.delimiter` being set to ',' which is the -default. See [configuration](#configuration) for more about delimiter.* +Setup ```ruby class User < ActiveRecord::Base - # Alias for acts_as_taggable_on :tags - acts_as_taggable + acts_as_taggable # Alias for acts_as_taggable_on :tags acts_as_taggable_on :skills, :interests end @user = User.new(:name => "Bobby") +``` -# this should be familiar -@user.tag_list = "awesome, slick, hefty" +Add and remove a single tag -# but you can do it for any context! -@user.skill_list = "joking, clowning, boxing" +```ruby +@user.tag_list.add("awesomer") # add a single tag. alias for << +@user.tag_list.remove("awesome") # remove a single tag +``` -@user.tags -# => [,,] +Add and remove multiple tags in an array -@user.skills -# => [,,] +```ruby +@user.tag_list.add("awesomer", "slicker") +@user.tag_list.remove("awesome", "slick") +``` -@user.skill_list -# => ["joking","clowning","boxing"] as TagList +You can also add and remove tags in format of String. This would +be convenient in some cases such as handling tag input param in a String. -# remove a single tag -@user.tag_list.remove("awesome") +Pay attention you need to add `parse: true` as option in this case. -# "remove" works with arrays too -@user.tag_list.remove("awesome", "slick") +You may also want to take a look at delimiter in the string. The default +is comma `,` so you don't need to do anything here. However, if you made +a change on delimiter setting, make sure the string will match. See +[configuration](#configuration) for more about delimiter. -# "remove" works with string too, needing "parse: true" option. +```ruby +@user.tag_list.add("awesomer, slicker", parse: true) @user.tag_list.remove("awesome, slick", parse: true) +``` -# add a single tag. alias for << -@user.tag_list.add("awesomer") +You can also add and remove tags by direct assignment. Note this will +remove existing tags so use it with attention. -# "add" also works with arrays -@user.tag_list.add("awesomer", "slicker") +```ruby +@user.tag_list = "awesome, slick, hefty" +@user.tags +# => [,,] +``` -# "add" works with string too, needing "parse: true" option. -@user.tag_list.add("awesomer, slicker", parse: true) +With the defined context in model, you have multiple new methods at disposal +to manage and view the tags in the context. For example, with `:skill` context +these methods are added to the model: `skill_list`(and `skill_list.add`, `skill_list.remove` +`skill_list=`), `skills`(plural), skill_counts + + +```ruby +@user.skill_list = "joking, clowning, boxing" + +@user.skills +# => [,,] + +@user.skill_list.add("coding") + +@user.skill_list +# => ["joking","clowning","boxing", "coding"] User.skill_counts # => [,...]