make_taggable 0.7.4 → 1.0.0

data/docs/caching.md

@@ -0,0 +1,93 @@
+# Caching tag lists
+
+Displaying a record's tags normally means loading its tags. If you show tags on an index page, that
+is a query per record or an `includes` on every page. Caching stores the rendered list in a column
+on the taggable itself, so showing it costs nothing extra.
+
+## Turning it on
+
+There is no setting. Add a column named `cached_<singular context>_list` and caching switches
+itself on for that context:
+
+```ruby
+class AddCachedTagListToBooks < ActiveRecord::Migration[8.0]
+  def change
+    add_column :books, :cached_tag_list, :string
+    add_column :books, :cached_genre_list, :string
+  end
+end
+```
+
+`:tags` gives `cached_tag_list`, `:genres` gives `cached_genre_list` — singular, the same
+inflection the generated methods use.
+
+Check whether a context is cached:
+
+```ruby
+Book.caching_tag_list?         # generated per context
+Book.caching_tag_list_on?(:genres)
+```
+
+## Using it
+
+Nothing changes in how you read or write tags. The column is filled on save:
+
+```ruby
+book = Book.create!(title: "Dune", tag_list: "sci-fi, classic")
+book.cached_tag_list  # => "sci-fi, classic"
+```
+
+Reading `tag_list` on a record loaded from the database parses the cached column instead of
+querying the tags table:
+
+```ruby
+book = Book.first
+book.tag_list  # no query against tags or taggings
+```
+
+Show the cached string directly when you only need to display it:
+
+```erb
+<%= book.cached_tag_list %>
+```
+
+## What it costs
+
+The cache is a denormalisation, with the usual consequences.
+
+- **It is written on save of the taggable, and only then.** Renaming or destroying a
+  `MakeTaggable::Tag` row directly does not touch any cached column. If you let tags be edited,
+  re-save the affected records, or clear the column and let it rebuild.
+- **It stores the rendered string**, joined with the delimiter in force at save time. Changing
+  `MakeTaggable.delimiter` afterwards leaves old rows joined the old way.
+- **A `string` column has a length limit.** A record with many tags can exceed it and have its
+  cached list truncated by the database. Use `text` if lists may be long.
+- **It does not include owned tags**, because it is built from the same list `tag_list` returns.
+  See [ownership.md](ownership.md).
+
+Caching is worth it for read-heavy displays of tags that rarely change. It is not a substitute for
+querying — `tagged_with` always goes to the taggings table, cached column or not.
+
+## Rebuilding
+
+Saving a record is **not** enough to rebuild its cached list. The column is only rewritten when the
+tag list has been loaded or assigned during that request, and reading the list on a cached record
+parses the column itself — so a stale value refreshes to the same stale value:
+
+```ruby
+book = Book.find(id)   # cached_tag_list is "one, two", but the tag is now named "uno"
+book.save!
+book.reload.cached_tag_list # => "one, two"   <- unchanged
+```
+
+Clear the column first, so reading the list falls through to the tags table:
+
+```ruby
+Book.find_each do |book|
+  book.update_column(:cached_tag_list, nil)
+  book.tag_list  # now read from tags, not from the column
+  book.save!
+end
+```
+
+That is the reliable way to repair cached lists after renaming or merging tags out of band.

data/docs/configuration.md

@@ -0,0 +1,108 @@
+# Configuration
+
+Settings live on `MakeTaggable`. Set them in an initializer:
+
+```ruby
+# config/initializers/make_taggable.rb
+MakeTaggable.setup do |config|
+  config.force_lowercase = true
+  config.remove_unused_tags = true
+end
+```
+
+Or assign them directly — `MakeTaggable` forwards to the same configuration object:
+
+```ruby
+MakeTaggable.force_lowercase = true
+```
+
+## Settings
+
+| Setting | Default | Effect |
+|---|---|---|
+| `force_lowercase` | `false` | Downcase tag names before saving |
+| `force_parameterize` | `false` | Parameterize tag names before saving |
+| `strict_case_match` | `false` | Match tags case sensitively |
+| `remove_unused_tags` | `false` | Destroy a tag row when its last tagging goes |
+| `tags_counter` | `true` | Maintain the `taggings_count` counter cache |
+| `default_parser` | `MakeTaggable::DefaultParser` | Class used to parse tag input |
+| `delimiter` | `","` | Delimiter, or delimiters, separating tags |
+| `tags_table` | `:tags` | Table backing `MakeTaggable::Tag` |
+| `taggings_table` | `:taggings` | Table backing `MakeTaggable::Tagging` |
+| `force_binary_collation` | `false` | MySQL only: exact matching including accents |
+
+### `force_lowercase`
+
+Tags are downcased as they are cleaned, so `"Ruby"` is stored as `"ruby"`.
+
+### `force_parameterize`
+
+Tags are parameterized, so `"Ruby on Rails"` is stored as `"ruby-on-rails"`. Applied after
+`force_lowercase` if both are on.
+
+### `strict_case_match`
+
+Off, tag lookups are case insensitive and `"Ruby"` finds `"ruby"`; a list containing both keeps one.
+On, they are two distinct tags and lookups match exactly.
+
+Note the interaction with the database: the shipped migrations put a **case-sensitive** unique index
+on `tags.name`, so `"Ruby"` and `"ruby"` can both exist as rows even with `strict_case_match` off.
+The library avoids creating both, but data loaded another way can still contain them.
+
+### `remove_unused_tags`
+
+When the last tagging referencing a tag is destroyed, the tag row is destroyed too. Requires
+`tags_counter`, since it reads the counter cache to decide.
+
+### `tags_counter`
+
+Keeps `tags.taggings_count` up to date. Turning it off avoids a write to the tags row on every
+tagging, at the cost of `Tag.most_used`, `Tag.least_used` and `remove_unused_tags`, all of which
+read that counter.
+
+Changing this on an existing application leaves the existing counts frozen at their current values
+rather than resetting them.
+
+### `default_parser`
+
+See [parsers.md](parsers.md).
+
+### `delimiter`
+
+Deprecated in favour of a parser, and warns when Active Record has a logger. Delimiters are literal
+strings — metacharacters are escaped for you. See [parsers.md](parsers.md).
+
+### `tags_table` and `taggings_table`
+
+Rename the tables, for instance to keep them out of the way of another tagging library:
+
+```ruby
+MakeTaggable.tags_table = "mt_tags"
+MakeTaggable.taggings_table = "mt_taggings"
+```
+
+These are read when `MakeTaggable::Tag` and `MakeTaggable::Tagging` are first loaded and when the
+migrations run, so set them in an initializer, before anything touches the models. Changing them on
+an application that already has data means renaming the tables yourself.
+
+### `force_binary_collation`
+
+MySQL only. Switches the `tags.name` column to `utf8mb4_bin`, so names compare exactly including
+accented and other multi-byte characters, and forces `strict_case_match` on.
+
+Note that the shipped migrations already apply `utf8mb4_bin` to the column on MySQL. What this
+setting adds is `strict_case_match`, which is what actually makes the library's lookups case
+sensitive — see [database.md](database.md).
+
+```ruby
+MakeTaggable.force_binary_collation = true
+```
+
+Or as a one-off migration:
+
+```shell
+rails make_taggable_engine:tag_names:collate_bin
+```
+
+Setting `strict_case_match = false` afterwards has no effect while binary collation is on. See
+[database.md](database.md).

data/docs/contexts.md

@@ -0,0 +1,147 @@
+# Tag contexts
+
+A context is a named group of tags on a model. One model can tag in as many contexts as you like,
+and the tags in each are kept apart: adding `"ruby"` to `skill_list` says nothing about
+`interest_list`.
+
+```ruby
+class User < ApplicationRecord
+  make_taggable                        # the :tags context
+  make_taggable :skills, :interests
+end
+```
+
+## What each context generates
+
+Given `make_taggable :skills`, these appear on the model. Singular and plural forms are worked out
+with Active Support's inflector, so `:skills` gives `skill_list` and `skills`.
+
+| Method | Kind | What it gives you |
+|---|---|---|
+| `skill_list` | instance | The tag names, as a `MakeTaggable::TagList` |
+| `skill_list=` | instance | Replaces the whole list |
+| `all_skills_list` | instance | The names including tags applied by an owner |
+| `skills` | instance | The `MakeTaggable::Tag` records, through the association |
+| `skill_taggings` | instance | The `MakeTaggable::Tagging` join records |
+| `skill_counts` | class and instance | Tags used, each carrying a `count` |
+| `top_skills(limit = 10)` | class and instance | The most used tags, most first |
+| `skills_from(owner)` | instance | Only the tags that owner applied |
+| `find_related_skills` | instance | Other records sharing these tags |
+| `find_related_skills_for(klass)` | instance | The same, against another model |
+| `caching_skill_list?` | class | Whether this context is cached in a column |
+
+`skill_list` takes part in dirty tracking like any other attribute:
+
+```ruby
+user.skill_list = "diving"
+user.skill_list_changed?          # => true
+user.skill_list_was               # => ["jogging"]
+user.skill_list_change            # => [["jogging"], ["diving"]]
+user.will_save_change_to_skill_list?
+```
+
+## Adding contexts later
+
+Calling `make_taggable` again adds contexts rather than replacing them, which is what lets a
+subclass extend its parent:
+
+```ruby
+class Manual < Book
+  make_taggable :audiences
+end
+
+Manual.tag_types # => [:tags, :audiences]
+```
+
+## Preserving tag order
+
+By default tags come back in whatever order the database returns. To keep them in the order they
+were added, declare the model with `make_ordered_taggable`:
+
+```ruby
+class Route < ApplicationRecord
+  make_ordered_taggable            # the :tags context, ordered
+  make_ordered_taggable :stops
+end
+
+route.tag_list = "east, south"
+route.save
+route.tag_list = "north, east, south, west"
+route.save
+
+route.reload.tag_list # => ["north", "east", "south", "west"]
+```
+
+Ordering is a property of the model, not of a single context: the last call wins for every context
+on that model. It also changes what counts as a change — reordering the same tags marks the list
+dirty on an ordered model, and does not on an unordered one.
+
+## Contexts created at runtime
+
+You do not have to declare a context up front. Anything you write through `set_tag_list_on` is
+saved and read back, which is how user-defined tag groups are built:
+
+```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)       # => [#<MakeTaggable::Tag name: "same">, ...]
+user.tag_counts_on(:customs)
+
+User.tagged_with("same", on: :customs) # => [user]
+```
+
+`tagging_contexts` lists everything the record tags in, declared and dynamic together:
+
+```ruby
+user.tagging_contexts # => ["tags", "skills", "interests", "customs"]
+```
+
+Dynamic contexts get none of the generated methods in the table above — there is no
+`custom_list` — so reach them through `tag_list_on`, `set_tag_list_on` and `tags_on`.
+
+## A separate vocabulary for one context
+
+Tags are shared across contexts and models by default: one `tags` row named `"ruby"` serves
+everything. To keep a context's tags separate, subclass `MakeTaggable::Tag` and override the hook
+that resolves names to records:
+
+```ruby
+class Market < MakeTaggable::Tag
+end
+
+class Company < ApplicationRecord
+  make_taggable :markets, :locations
+
+  private
+
+  def find_or_create_tags_from_list_with_context(tag_list, context)
+    if context.to_sym == :markets
+      Market.find_or_create_all_with_like_by_name(tag_list)
+    else
+      super
+    end
+  end
+end
+```
+
+This only genuinely separates the vocabularies if the tags table has a `type` column. Without one,
+Active Record has nowhere to record the subclass: rows created through `Market` are saved as plain
+tags, `Market.count` returns every tag in the table, and reloading a record gives you a
+`MakeTaggable::Tag` back. Add the column to get real separation:
+
+```ruby
+class AddTypeToTags < ActiveRecord::Migration[8.0]
+  def change
+    add_column MakeTaggable.tags_table, :type, :string
+    add_index MakeTaggable.tags_table, :type
+  end
+end
+```
+
+Note that the shipped migrations put a unique index on `tags.name`, so two tags cannot share a name
+even across subclasses. If a market and a genre both need to be called "Energy", widen that index to
+cover `[:name, :type]`.

data/docs/database.md

@@ -0,0 +1,106 @@
+# Database
+
+## Schema
+
+Two tables, installed by `rails make_taggable_engine:install:migrations`.
+
+**`tags`** — one row per distinct tag name.
+
+| Column | Type | Notes |
+|---|---|---|
+| `name` | string | Limited to 255 characters by a validation; uniquely indexed |
+| `taggings_count` | integer | Counter cache, maintained unless `tags_counter` is off |
+| `created_at`, `updated_at` | datetime | |
+
+**`taggings`** — joins a tag to the record it was applied to.
+
+| Column | Type | Notes |
+|---|---|---|
+| `tag_id` | reference | Foreign key to `tags` |
+| `taggable_type`, `taggable_id` | polymorphic reference | The record being tagged |
+| `tagger_type`, `tagger_id` | polymorphic reference | Who applied it; null when unowned |
+| `context` | string(128) | The tag context, e.g. `"skills"` |
+| `created_at`, `updated_at` | datetime | |
+
+Both table names are configurable — see [configuration.md](configuration.md).
+
+## Indexes
+
+The shipped migrations index `taggings` heavily: the polymorphic references index themselves, and
+migration 5 adds standalone indexes on `taggable_id`, `tagger_id`, `taggable_type` and `context`,
+plus four composites.
+
+That suits read-heavy tagging. If your application writes taggings in bulk, the write cost is worth
+looking at — every index is maintained on insert, and several of the standalone ones are prefixes of
+composites that already exist. Drop what your queries do not use.
+
+### The unique index does not stop duplicate unowned taggings
+
+`taggings_idx` is unique across
+`[tag_id, taggable_id, taggable_type, context, tagger_id, tagger_type]`. Because `tagger_id` and
+`tagger_type` are null for unowned taggings, and SQL treats nulls as distinct, **the database will
+accept two identical unowned taggings**. Only the Active Record uniqueness validation prevents them,
+and a validation cannot prevent a race between two concurrent writes.
+
+If duplicate taggings would be a problem for you, add a partial unique index. On PostgreSQL:
+
+```ruby
+add_index :taggings,
+  [:tag_id, :taggable_id, :taggable_type, :context],
+  unique: true,
+  where: "tagger_id IS NULL",
+  name: "taggings_unowned_idx"
+```
+
+## PostgreSQL
+
+- `named_like` uses `ILIKE`, so partial matching is case insensitive regardless of collation.
+- Tag counts group by every tag column, as PostgreSQL requires.
+- Nothing extra is needed for non-ASCII tags.
+
+## MySQL
+
+**The shipped migrations collate tag names as `utf8mb4_bin`.** Migration 3 applies it
+unconditionally on MySQL, so the `tags.name` column is case- and accent-sensitive at the database
+level whatever `force_binary_collation` is set to.
+
+That matters if you query the column yourself: `WHERE name LIKE '%ruby%'` will not match `"Ruby"` on
+MySQL, though it does on SQLite and PostgreSQL. The library's own lookups are unaffected, because
+`Tag.named` and `Tag.named_any` compare with `LOWER()` on both sides rather than relying on the
+collation.
+
+To go back to a case-insensitive column, run `rails make_taggable_engine:tag_names:collate_ci`.
+
+Other notes:
+
+- For exact matching including accented characters *and* case-sensitive library lookups, turn on
+  binary collation through the configuration, which also flips `strict_case_match`:
+
+  ```ruby
+  MakeTaggable.force_binary_collation = true
+  ```
+
+  or run `rails make_taggable_engine:tag_names:collate_bin`. To go back,
+  `rails make_taggable_engine:tag_names:collate_ci`.
+
+  Binary collation forces `strict_case_match` on, and `strict_case_match = false` has no effect
+  while it is on.
+
+- Tag count queries fetch matching ids first rather than using a subquery, which MySQL optimises
+  poorly.
+
+## SQLite
+
+Fine for development and for the test suite, with one real limitation:
+
+**SQLite cannot change the case of non-ASCII characters.** Its built-in `LOWER()` and `UPPER()`
+handle ASCII only, so case-insensitive matching of, say, Cyrillic or Greek tags does not work. `"ПРИВЕТ"`
+and `"привет"` are two different tags as far as SQLite is concerned.
+
+If that matters, load the [ICU extension](https://www.sqlite.org/src/artifact?ci=trunk&filename=ext/icu/README.txt),
+or set `MakeTaggable.strict_case_match = true` so the behaviour is at least consistent.
+
+## Tag length
+
+`name` is validated at 255 characters, and the column is a `string`. Tags longer than that fail
+validation rather than being truncated.

data/docs/getting-started.md

@@ -0,0 +1,114 @@
+# Getting started
+
+## Requirements
+
+MakeTaggable needs Ruby 3.2 or newer and Active Record 7.2 or newer. It is tested against Rails
+7.2, 8.0 and 8.1 on SQLite, MySQL and PostgreSQL.
+
+## Install
+
+Add the gem:
+
+```shell
+bundle add make_taggable
+```
+
+Copy the migrations into your application and run them:
+
+```shell
+rails make_taggable_engine:install:migrations
+rails db:migrate
+```
+
+That creates two tables: `tags`, holding each distinct tag name, and `taggings`, joining a tag to
+the record it was applied to. Both table names are configurable — see
+[configuration.md](configuration.md).
+
+## Make a model taggable
+
+```ruby
+class Book < ApplicationRecord
+  make_taggable
+end
+```
+
+Called with no arguments, `make_taggable` tags on the `:tags` context, which is the default the
+rest of the library assumes. Name your own contexts instead, or as well:
+
+```ruby
+class Book < ApplicationRecord
+  make_taggable :genres, :moods
+end
+```
+
+Each context generates its own set of methods. `:genres` gives you `genre_list`, `genres`,
+`genre_counts`, `top_genres` and more — see [contexts.md](contexts.md) for the full list.
+
+## Read and write tags
+
+A tag list behaves like an array of strings:
+
+```ruby
+book = Book.new(title: "Dune")
+
+book.tag_list = "sci-fi, classic"
+book.save
+
+book.tag_list           # => ["sci-fi", "classic"]
+book.tags               # => [#<MakeTaggable::Tag name: "sci-fi">, #<MakeTaggable::Tag name: "classic">]
+```
+
+Add and remove individual tags. Nothing is written until you save:
+
+```ruby
+book.tag_list.add("desert")
+book.tag_list.remove("classic")
+book.save
+```
+
+To pass a delimited string rather than separate arguments, ask for it to be parsed:
+
+```ruby
+book.tag_list.add("desert, epic", parse: true)
+```
+
+Assigning replaces the whole list, so `tag_list =` removes anything not in the new value.
+
+## Permit the parameter
+
+`tag_list` is an ordinary attribute as far as your controller is concerned:
+
+```ruby
+class BooksController < ApplicationController
+  private
+
+  def book_params
+    params.expect(book: [:title, :tag_list])
+  end
+end
+```
+
+To accept an array of tags from a multi-select, permit it as one:
+
+```ruby
+params.expect(book: [:title, {tag_list: []}])
+```
+
+## Find tagged records
+
+```ruby
+Book.tagged_with("sci-fi")                          # carries this tag
+Book.tagged_with(["sci-fi", "classic"])             # carries both
+Book.tagged_with(["sci-fi", "classic"], any: true)  # carries either
+```
+
+`tagged_with` returns a relation, so it chains with your own scopes and with pagination.
+[querying.md](querying.md) covers every option.
+
+## Where to go next
+
+- [contexts.md](contexts.md) — multiple contexts, ordered tags, contexts created at runtime
+- [querying.md](querying.md) — every `tagged_with` option, and the counting API
+- [ownership.md](ownership.md) — tags belonging to a user, and why `tag_list` can look empty
+- [configuration.md](configuration.md) — every setting
+- [database.md](database.md) — schema, indexes, and per-adapter notes

data/docs/migrating-from-aato.md

@@ -0,0 +1,67 @@
+# Migrating from acts-as-taggable-on
+
+MakeTaggable began as a fork of
+[acts-as-taggable-on](https://github.com/mbleigh/acts-as-taggable-on). The behaviour is largely the
+same; the names are not.
+
+## Method names
+
+| acts-as-taggable-on | MakeTaggable |
+|---|---|
+| `acts_as_taggable` | `make_taggable` |
+| `acts_as_taggable_on :skills` | `make_taggable :skills` |
+| `acts_as_ordered_taggable` | `make_ordered_taggable` |
+| `acts_as_ordered_taggable_on :skills` | `make_ordered_taggable :skills` |
+| `acts_as_tagger` | `make_tagger` |
+
+> Versions of MakeTaggable before 1.0 kept the `acts_as_*` names as aliases. They were removed in
+> 1.0 — see [UPGRADING.md](../UPGRADING.md).
+
+Everything generated per context is unchanged: `skill_list`, `skills`, `skill_counts`,
+`top_skills`, `skills_from`, `find_related_skills` and the rest all keep their names.
+
+## Constants
+
+| acts-as-taggable-on | MakeTaggable |
+|---|---|
+| `ActsAsTaggableOn::Tag` | `MakeTaggable::Tag` |
+| `ActsAsTaggableOn::Tagging` | `MakeTaggable::Tagging` |
+| `ActsAsTaggableOn::TagList` | `MakeTaggable::TagList` |
+| `ActsAsTaggableOn::GenericParser` | `MakeTaggable::GenericParser` |
+| `ActsAsTaggableOn::DefaultParser` | `MakeTaggable::DefaultParser` |
+| `ActsAsTaggableOn.setup` | `MakeTaggable.setup` |
+
+Configuration keys are the same. `ActsAsTaggableOn.force_lowercase` becomes
+`MakeTaggable.force_lowercase`, and so on — see [configuration.md](configuration.md).
+
+## The database
+
+The schema is compatible: the same `tags` and `taggings` tables, with the same columns. If you are
+switching an application over, you do not need to move any data.
+
+Two differences to check before you do:
+
+- **`taggable_type` and `tagger_type` hold class names.** They do not mention either library, so
+  they carry across untouched.
+- **acts-as-taggable-on's migrations differ in their indexes** depending on which version installed
+  them. MakeTaggable's migrations are separate files with their own version numbers, so running
+  `rails make_taggable_engine:install:migrations` on a database that already has the tables will try
+  to create them again. Skip those migrations, or mark them as run, rather than letting them
+  execute.
+
+## Behaviour differences
+
+- **Delimiters are literal strings.** acts-as-taggable-on interpolated the configured delimiter into
+  a pattern unescaped, so splitting on `|` meant passing `'\|'`. MakeTaggable escapes for you: pass
+  `"|"`. See [parsers.md](parsers.md).
+- **`make_taggable` with no arguments tags on `:tags`.** In acts-as-taggable-on, `acts_as_taggable`
+  was the no-argument form and `acts_as_taggable_on` took contexts; MakeTaggable uses one method for
+  both.
+- **Requirements are higher.** Ruby 3.2 and Active Record 7.2, against acts-as-taggable-on's wider
+  range.
+
+## What has not changed
+
+The parts people rely on most behave identically: `tagged_with` and all its options, tag ownership
+and the rule that `tag_list` excludes owned tags, dirty tracking on `*_list` attributes, cached tag
+list columns, the tag cloud helper, and custom parsers.