Table of Contents generated with DocToc

• EasyTags
  • Migrating from ActsAsTaggableOn
  • Installation
    • Post Installation
  • Usage
    • Setup
    • Interface
    • Examples
      • Adding/Removing tags
      • Querying
        • Context relations
        • Global relations
    • Callbacks
      • Instance scope callbacks
      • Active Support Instrumentation custom notifications
        • Tag notifications
        • Tagging notifications
    • Dirty objects
  • Configuration
  • Testing
  • Development
  • Contributing
  • License

Easy contextual tagging for Rails

This gem was inspired by ActsAsTaggableOn. It was built on similar model, but rewritten from scratch and simplified with better maintainability in mind. Considerable amount of features has been removed and we've made some breaking changes. Please refer to ActsAsTaggableOn migration notes if you want to migrate

Add this line to your application's Gemfile:

gem 'easy_tags'

And then execute:

$ bundle

generate migration with:

rails g easy_tags:migration

in your ActiveRecord model add:

include EasyTags::Taggable

easy_tags_on :highlights

with multiple tag contexts:

include EasyTags::Taggable

easy_tags_on :highlights, :tags, :notes

upon the easy_tags_on declaration:

easy_tags_on :highlights

the following methods will be auto-generated and made available for your model instance (highlights being an example context name):

• the String accessor is helpful when working with client side tagging UI solutions such as ie. select2
• the Array accessor gives you convenient array item manipulation

Using Array accessor

# assign/replace tags (comma separated using the default parser)
model.highlights = ['My Tag', 'Second Tag', 'Some Other tag']
# => [
#      [0] "My Tag",
#      [1] "Second Tag",
#      [2] "Some Other tag"
#  ]

# add tags
model.highlights.add('One More', 'And Another')
model.highlights
# => [
#     [0] "My Tag",
#     [1] "Second Tag",
#     [2] "Some Other tag",
#     [3] "One More",
#     [4] "And Another"
#  ]

# remove a single tag
model.highlights.remove('One More')
model.highlights
# => [
#     [0] "My Tag",
#     [1] "Second Tag",
#     [2] "Some Other tag",
#     [3] "And Another"
#  ]

# remember to persist changes
model.save

Using String accessor

# add multiple tags (comma separated using the default parser)
model.highlights_list = 'My Tag, Second Tag, Some Other tag'
# > "My Tag, Second Tag, Some Other tag"

# remove a single tag
model.highlights_list = 'My Tag, Second Tag'
# > "My Tag, Second Tag"

# remove all tags
model.highlights_list = ''

# remember to persist changes
model.save

EasyTags does not offer any query helper scopes, but it's fairly easy to query without them.

Upon the easy_tags_on declaration:

easy_tags_on :highlights

the following relations will be auto-generated and made available for your model instance (highlights being an example context name):

• EasyTags::Tag model represents a single tag name
• EasyTags::Taggings represents a join table between your model and the EasyTags::Tag model, it also holds the tag context value

Find all model instances with a specific tag name:

MyModel.joins(:highlights_tags).where(tags: { name: 'My Tag' })

Eager loading:

MyModel.includes(:highlights_tags)

Upon the EasyTags::Taggable inclusion

include EasyTags::Taggable

the fallowing context independent relations will be auto-generated and made available for your model instance:

You can use them for querying multiple contexts

MyModel.joins(:base_tags).where(taggings: { context: %w[highlights billing_highlights] })

include EasyTags::Taggable

easy_tags_on(
  highlights: { after_add: :add_tag_callback, after_remove: -> (tagging) { puts "removed #{tagging.tag.name}" } }
)

def add_tag_callback(tagging)
  puts "added #{tagging.tag.name}"
end

ActiveSupport::Notifications.subscribe 'easy_tag.tag_added' do |tag|
  puts "added #{tag.name}"
end

ActiveSupport::Notifications.subscribe 'easy_tag.tag_removed' do |tag|
  puts "removed #{tag.name}"
end

ActiveSupport::Notifications.subscribe 'easy_tag.tagging_added.YOUR_MODEL_TABLEIZED.CONTEXT_NAME' do |tagging|
  puts "added #{tagging.tag.name}"
end

ActiveSupport::Notifications.subscribe 'easy_tag.tagging_added.YOUR_MODEL_TABLEIZED.CONTEXT_NAME' do |tagging|
  puts "removed #{tagging.tag.name}"
end

EasyTags implements ActiveModel::Dirty attribute changes tracking fot all the context String accessors (the CONTEXT_NAME_list attributes)

model.highlights
# []

model.highlights = ['Tag One', 'Tag Two']
# [
#     [0] "Tag One",
#     [1] "Tag Two"
# ]

model.changed?
# true

model.highlights_list_changed?
# true

model.highlights_list_was
# ""

model.highlights_list_change
# [
#     [0] "",
#     [1] "Tag One,Tag Two"
# ]

model.save
# true

model.changed?
# false

model.highlights_list_changed?
# false

model.previous_changes
# {
#     "highlights_list" => [
#         [0] nil,
#         [1] "Tag One,Tag Two"
#     ]
# }

model.highlights_list_previously_changed?
# true

model.highlights_list_previous_change
# [
#     [0] nil,
#     [1] "Tag One,Tag Two"
# ]

# config/initializers/easy_tags.rb

EasyTags.setup do |config|
  config.tags_table = :tags
  config.taggings_table = :taggings
  config.parser = EasyTags::Parsers::Default
  config.generator = EasyTags::Generators::Default
end

You can customize db table names with tags_table and taggings_table options.

You can customize the parser and the generator to use different separators, filtering or processing. The default parser uses comma as separator and is case sensitive.

bundle exec appraisal install
bundle exec appraisal rspec

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/easy_tags. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

The gem is available as open source under the terms of the MIT License.