Gutentag

https://www.rubydoc.info/gems/gutentag
Admin
Gutentag is a simple and solid tagging extension for ActiveRecord that provides easy tag management,...
Tokens:11,712
Snippets:111
Trust Score:10
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Gutentag Migrations and Run

Source: https://www.rubydoc.info/gems/gutentag/file/README.md

Execute these commands to install Gutentag's database migrations, generate version-specific migration files, and apply them to your database.

```bash
bundle exec rake gutentag:install:migrations
bundle exec rails generate gutentag:migration_versions
bundle exec rake db:migrate
```

--------------------------------

### Get Taggable

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ChangeState

Returns the taggable object associated with this instance.

```ruby
def taggable
  @taggable
end
```

--------------------------------

### Get All Tag Names for a Scope

Source: https://www.rubydoc.info/gems/gutentag/file/README.md

Retrieve an array of all unique tag names used within a given ActiveRecord scope.

```ruby
# Returns array of tag names
Gutentag::Tag.names_for_scope(Article)
# => ['tag1', 'tag2', 'tag3']

Gutentag::Tag.names_for_scope(Article.where(:created_at => 1.week.ago..1.second.ago))
# => ['tag3']

# Return array of the tag names used from the two most recent articles
Gutentag::Tag.names_for_scope(Article.order(created_at: :desc).limit(2))
# => []
```

--------------------------------

### Get Tag Validations Configuration - Gutentag

Source: https://www.rubydoc.info/gems/gutentag/Gutentag.tag_validations%3D

Returns the current tag validation configuration object. This is typically used to access or modify validation rules.

```ruby
def self.tag_validations
  @tag_validations ||= Gutentag::TagValidations
end
```

--------------------------------

### GET Gutentag.tag_validations

Source: https://www.rubydoc.info/gems/gutentag/Gutentag.tag_validations%3D

Retrieves the current tag validation class configured for the Gutentag gem.

```APIDOC
## GET Gutentag.tag_validations

### Description
Returns the class responsible for tag validations within the Gutentag system. Defaults to Gutentag::TagValidations.

### Method
GET

### Endpoint
Gutentag.tag_validations

### Response
#### Success Response (200)
- **return** (Object) - The class object used for tag validations.
```

--------------------------------

### Add Tag Association to ActiveRecord Model

Source: https://www.rubydoc.info/gems/gutentag/file/README.md

Include this line in your ActiveRecord model to enable Gutentag functionality. No further setup is required for basic tagging.

```ruby
class Article < ActiveRecord::Base
  # ...
  Gutentag::ActiveRecord.call self
  # ...
end
```

--------------------------------

### Get Tag Names for Scope - Gutentag::Tag

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/Tag.find_or_create

Use this method to retrieve all distinct tag names associated with a given ActiveRecord scope. It handles both regular ActiveRecord objects and relations, ensuring correct join conditions.

```ruby
def self.names_for_scope(scope)
  join_conditions = {:taggable_type => scope.name}
  if scope.is_a?(ActiveRecord::Relation)
    return Gutentag::Tag.none unless scope.current_scope.present?

    join_conditions[:taggable_id] = scope.select(:id)
  end

  joins(:taggings).where(
    Gutentag::Tagging.table_name => join_conditions
  ).distinct.pluck(:name)
end
```

--------------------------------

### Gutentag::Persistence Constructor: initialize

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/Persistence

Details for the constructor of Gutentag::Persistence.

```APIDOC
### Constructor Details

### permalink #**initialize**(change_state) ⇒ `Persistence`

Returns a new instance of Persistence.
[View source]
```ruby
# File 'lib/gutentag/persistence.rb', line 10

def initialize(change_state)
  @change_state = change_state
end
```
```

--------------------------------

### Gutentag::Persistence Instance Methods

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/Persistence

Summary of instance methods for Gutentag::Persistence.

```APIDOC
## Instance Method Summary

* #**initialize**(change_state) ⇒ Persistence  constructor
A new instance of Persistence.
* #**persist** ⇒ Object
```

--------------------------------

### Gutentag::TaggedWith::Query#initialize

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TaggedWith/Query%3Ainitialize

Initializes a new instance of the Query class.

```APIDOC
## Gutentag::TaggedWith::Query#initialize

### Description
Returns a new instance of Query.

### Method
initialize

### Endpoint
N/A (Instance Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **Query** (Object) - A new instance of the Query class.

#### Response Example
None
```

--------------------------------

### Initialize Gutentag::TaggedWith::Query

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TaggedWith/Query%3Ainitialize

Initializes a new instance of Gutentag::TaggedWith::Query. Requires the model, values, and match criteria.

```ruby
def initialize(model, values, match)
  @model  = model
  @values = Array values
  @match  = match
end
```

--------------------------------

### Gutentag::TagValidations#initialize

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TagValidations%3Ainitialize

Initializes a new instance of Gutentag::TagValidations.

```APIDOC
## Gutentag::TagValidations#initialize

### Description
Initializes a new instance of TagValidations.

### Method
initialize

### Parameters
#### Path Parameters
- **klass** (Object) - Required - The class to associate validations with.

### Request Example
```json
{
  "klass": "YourModel"
}
```

### Response
#### Success Response (200)
- **TagValidations** (Object) - A new instance of TagValidations.

#### Response Example
```json
{
  "instance": "<Gutentag::TagValidations>"
}
```
```

--------------------------------

### Gutentag::ActiveRecord#initialize

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ActiveRecord%3Ainitialize

Initializes a new instance of the ActiveRecord class within Gutentag.

```APIDOC
## Gutentag::ActiveRecord#initialize

### Description
Initializes a new instance of ActiveRecord.

### Method
`initialize(model)`

### Endpoint
N/A (Instance method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
Returns a new instance of ActiveRecord.

#### Response Example
```ruby
#<Gutentag::ActiveRecord:0x00007f8d3b9a7b00>
```
```

--------------------------------

### Gutentag::TaggedWith::NameQuery#initialize

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TaggedWith/NameQuery%3Ainitialize

Initializes a new instance of NameQuery. It normalizes the provided tag values.

```APIDOC
## Gutentag::TaggedWith::NameQuery#initialize

### Description
Returns a new instance of NameQuery.

### Method
initialize

### Endpoint
N/A (Instance Method)

### Parameters
- **model** (Object) - Description not provided
- **values** (Array) - Description not provided
- **match** (Object) - Description not provided

### Request Example
N/A

### Response
#### Success Response (200)
- **NameQuery** (Object) - A new instance of NameQuery.

#### Response Example
N/A
```

--------------------------------

### Gutentag::TaggedWith::NameQuery Initialization

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TaggedWith/NameQuery

Details the constructor for the NameQuery class, including its parameters and return type.

```APIDOC
## initialize /api/websites/rubydoc_info_gems_gutentag

### Description
Initializes a new instance of the NameQuery class.

### Method
POST

### Endpoint
/api/websites/rubydoc_info_gems_gutentag

### Parameters
#### Path Parameters
- **model** (Object) - Required - The model to associate with the query.
- **values** (Array) - Required - An array of tag values to match.
- **match** (String) - Required - The matching strategy (e.g., 'any', 'all').

### Request Body
```json
{
  "model": "YourModel",
  "values": ["tag1", "tag2"],
  "match": "all"
}
```

### Response
#### Success Response (200)
- **NameQuery** (Object) - An instance of the NameQuery class.

#### Response Example
```json
{
  "query_instance": "Gutentag::TaggedWith::NameQuery"
}
```
```

--------------------------------

### Gutentag::Persistence#initialize

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/Persistence%3Ainitialize

Initializes a new instance of the Gutentag::Persistence class. This method is used internally to set up the persistence layer with a change state object.

```APIDOC
## Gutentag::Persistence#initialize

### Description
Initializes a new instance of Persistence.

### Method
initialize

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
Returns a new instance of Persistence.

#### Response Example
None
```

--------------------------------

### Gutentag::TaggedWith::Query Constructor

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TaggedWith/Query

Initializes a new instance of the Gutentag::TaggedWith::Query class. It takes the model, values, and match criteria as arguments.

```APIDOC
## initialize(model, values, match)

### Description
Returns a new instance of Query.

### Method
constructor

### Parameters
- **model** (Object) - Required - The model to query.
- **values** (Array) - Required - The values to match.
- **match** (Object) - Required - The matching strategy.

### Request Example
```json
{
  "model": "Post",
  "values": ["ruby", "rails"],
  "match": "any"
}
```

### Response
#### Success Response (200)
- **Query** (Object) - A new instance of the Query class.

### Response Example
```json
{
  "message": "Query object created successfully"
}
```
```

--------------------------------

### Initialize Gutentag Persistence

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/Persistence%3Ainitialize

Creates a new instance of the Persistence class by assigning the provided change_state object.

```ruby
# File 'lib/gutentag/persistence.rb', line 10

def initialize(change_state)
  @change_state = change_state
end
```

--------------------------------

### Gutentag::TaggedWith#initialize

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TaggedWith%3Ainitialize

Initializes a new instance of the TaggedWith class.

```APIDOC
## Gutentag::TaggedWith#initialize

### Description
Returns a new instance of TaggedWith.

### Method
initialize

### Endpoint
N/A (Instance method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
Returns a new instance of TaggedWith.

#### Response Example
None
```

--------------------------------

### Initialize Gutentag::Persistence

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/Persistence

Constructor for the Persistence class, accepting a change_state object.

```ruby
def initialize(change_state)
  @change_state = change_state
end
```

--------------------------------

### Initialize NameQuery

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TaggedWith/NameQuery%3Ainitialize

Initializes a new instance of NameQuery. It normalizes the provided tag values before storing them.

```ruby
def initialize(model, values, match)
  super

  @values = @values.collect { |tag| Gutentag.normaliser.call(tag) }
end
```

--------------------------------

### Call Gutentag::TaggedWith

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TaggedWith.call

Use this method to initialize and call Gutentag::TaggedWith. It takes a model and options as arguments.

```ruby
def self.call(model, options)
  new(model, options).call
end
```

--------------------------------

### Gutentag::Persistence Instance Attributes

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/Persistence

Summary of instance attributes for Gutentag::Persistence.

```APIDOC
## Instance Attribute Summary

* #**tagger** ⇒ Object  writeonly
Sets the attribute tagger.
```

--------------------------------

### Gutentag::ChangeState Methods

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ChangeState

Methods for initializing the change state and retrieving added or removed tags.

```APIDOC
## initialize(taggable)

### Description
Initializes a new instance of ChangeState for a given taggable object, calculating existing and new tag states.

### Parameters
- **taggable** (Object) - Required - The object that is being tagged.

## added

### Description
Returns an array of tags that have been added to the taggable object.

## removed

### Description
Returns an array of tags that have been removed from the taggable object.
```

--------------------------------

### Gutentag::TaggedWith#call Method Implementation

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TaggedWith%3Acall

This method is part of the Gutentag::TaggedWith module and is responsible for initiating a query based on provided values. It requires a query class, a model, and matching values.

```ruby
def call
  query_class.new(model, values, match).call
end
```

--------------------------------

### Initialize ChangeState

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ChangeState

Constructor for the ChangeState class, initializing the taggable object and normalizing existing tags.

```ruby
def initialize(taggable)
  @taggable = taggable
  @existing = normalised taggable.tags.collect(&:name)
  @changes  = normalised taggable.tag_names
end
```

--------------------------------

### Query Articles by Tag Names (Match Any)

Source: https://www.rubydoc.info/gems/gutentag/file/README.md

Find articles that have any of the specified tag names. This uses OR logic by default.

```ruby
Article.tagged_with(:names => ['tag1', 'tag2'], :match => :any)
```

--------------------------------

### Gutentag::Persistence Class

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/Persistence

Details about the Gutentag::Persistence class, including inheritance and defined file.

```APIDOC
## Class: Gutentag::Persistence

Inherits:
     Object
  * Object
  * Gutentag::Persistence

Extended by:
    Forwardable 

Defined in:
    lib/gutentag/persistence.rb
```

--------------------------------

### Initialize TaggedWith

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TaggedWith%3Ainitialize

Initializes a new instance of the TaggedWith class. Requires the model and options as arguments.

```ruby
def initialize(model, options)
  @model   = model
  @options = options
end
```

--------------------------------

### Extend Gutentag models

Source: https://www.rubydoc.info/gems/gutentag/file/README.md

Use a Rails to_prepare hook to ensure model extensions are loaded consistently across environments.

```ruby
# config/initializers/gutentag.rb or equivalent
Rails.application.config.to_prepare do
  Gutentag::Tag.include TagExtensions
end
```

--------------------------------

### Define Gutentag::ActiveRecord#call

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ActiveRecord%3Acall

Initializes the ActiveRecord integration by adding necessary associations, callbacks, methods, and attributes.

```ruby
# File 'lib/gutentag/active_record.rb', line 12

def call
  add_associations
  add_callbacks
  add_methods
  add_attribute
end
```

--------------------------------

### Query Articles by Tag IDs (Match All)

Source: https://www.rubydoc.info/gems/gutentag/file/README.md

Find articles that have all of the specified tag IDs. This uses AND logic.

```ruby
# Returns all articles that have *both* tag_a and tag_b.
Article.tagged_with(:ids => [tag_a.id, tag_b.id], :match => :all)
```

--------------------------------

### Initialize Gutentag::ActiveRecord

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ActiveRecord%3Ainitialize

Initializes the ActiveRecord integration for Gutentag. This method is called when creating a new instance of the ActiveRecord wrapper.

```ruby
def initialize(model)
  @model = model
end
```

--------------------------------

### Gutentag::ActiveRecord#call

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ActiveRecord%3Acall

The call method initializes the Gutentag integration by setting up necessary associations, callbacks, methods, and attributes on the target ActiveRecord model.

```APIDOC
## Gutentag::ActiveRecord#call

### Description
Initializes the Gutentag functionality on an ActiveRecord model by invoking the internal setup methods.

### Method
Internal Ruby Method

### Endpoint
Gutentag::ActiveRecord#call

### Response
- **Returns** (Object) - Returns the result of the initialization process.
```

--------------------------------

### Gutentag::ActiveRecord::InstanceMethods#reload

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ActiveRecord/InstanceMethods%3Areload

Reloads the tag names, resetting the prepared state.

```APIDOC
## Gutentag::ActiveRecord::InstanceMethods#reload

### Description
Resets the internal state for tag names and then calls the superclass's reload method.

### Method
`reload`

### Endpoint
N/A (Instance Method)

### Parameters
None explicitly defined for this method signature, but accepts `*args` which are passed to `super`.

### Request Example
```ruby
# Assuming an instance of a class that includes Gutentag::ActiveRecord::InstanceMethods
instance.reload
```

### Response
#### Success Response (200)
Returns the result of the `super` call, typically the reloaded object.

#### Response Example
```ruby
# Example return value depends on the superclass implementation
# For ActiveRecord, it might return the reloaded AR object.
```
```

--------------------------------

### Query Articles by Tag IDs (Match Any)

Source: https://www.rubydoc.info/gems/gutentag/file/README.md

Find articles that have any of the specified tag IDs. This uses OR logic by default.

```ruby
Article.tagged_with(:ids => [tag_id], :match => :any)
```

--------------------------------

### Assign tag names

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ActiveRecord/InstanceMethods

Sets the tag names for the instance after preparing the state.

```ruby
# File 'lib/gutentag/active_record/instance_methods.rb', line 37

def tag_names=(names)
  # This value is about to be overwritten, but we want to make sure the change
  # tracking doesn't think the original value was nil.
  prepare_tag_names

  super Gutentag::TagNames.call(names)
end
```

--------------------------------

### Gutentag::Tagging Class Documentation

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/Tagging

Details about the Gutentag::Tagging class, its inheritance, and where it is defined.

```APIDOC
## Class: Gutentag::Tagging

### Description
Represents the tagging model within the Gutentag gem, likely used to associate tags with other Active Record models.

### Inheritance
- Object
- ActiveRecord::Base
- Gutentag::Tagging

### Defined in
- app/models/gutentag/tagging.rb
```

--------------------------------

### Gutentag::TaggedWith#call Method

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TaggedWith%3Acall

Documentation for the `call` method within the `Gutentag::TaggedWith` class.

```APIDOC
## Gutentag::TaggedWith#call

### Description
Executes the query to find tagged items.

### Method
`call`

### Endpoint
N/A (Instance Method)

### Parameters
None

### Request Example
N/A

### Response
#### Success Response (200)
- **Object** - The result of the query.

#### Response Example
N/A
```

--------------------------------

### Query Articles by Tag Objects (Match Any)

Source: https://www.rubydoc.info/gems/gutentag/file/README.md

Find articles that have any of the specified Gutentag::Tag objects. This uses OR logic by default.

```ruby
Article.tagged_with(
  :tags  => Gutentag::Tag.where(name: ['tag1', 'tag2']),
  :match => :any
)
```

--------------------------------

### Gutentag Class List

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TaggedWith/IDQuery

An overview of the classes and modules available in the Gutentag gem.

```APIDOC
# Class List

## Top Level Namespace
- Gutentag

## Gutentag Top Level Namespace
- ActiveRecord (inherits from Object)
  - ClassMethods
  - InstanceMethods
- ChangeState (inherits from Object)
- Engine (inherits from Engine)
- Generators
  - MigrationVersionsGenerator (inherits from Base)
- Persistence (inherits from Object)
- RemoveUnused (inherits from Object)
- Tag (inherits from Base)
- TagNames (inherits from Object)
- TagValidations (inherits from Object)
- TaggedWith
  - IDQuery (inherits from Query)
  - NameQuery (inherits from Query)
  - Query (inherits from Object)
- Tagging (inherits from Base)
```

--------------------------------

### Gutentag::ActiveRecord::InstanceMethods

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ActiveRecord/InstanceMethods

Provides methods for managing tags directly on ActiveRecord models.

```APIDOC
## Module: Gutentag::ActiveRecord::InstanceMethods

### Description
This module provides instance methods for ActiveRecord models to manage tag names.

### Methods

#### `reload(*)`

##### Description
Reloads the instance and resets any prepared tag names.

##### Method
`reload`

##### Parameters
None

##### Request Example
```ruby
# Assuming 'article' is an instance of an ActiveRecord model with Gutentag
article.reload
```

##### Response
Returns the reloaded object.

#### `reset_tag_names`

##### Description
Resets the `tag_names` attribute if it hasn't been modified or saved.
This is useful to ensure the stored value is accurate, especially after direct tag additions.

##### Method
`reset_tag_names`

##### Parameters
None

##### Request Example
```ruby
# Assuming 'article' is an instance of an ActiveRecord model with Gutentag
article.reset_tag_names
```

##### Response
Returns `nil` or the result of the underlying attribute write.

#### `tag_names`

##### Description
Retrieves the tag names associated with the model instance. If not already prepared or fetched, it queries the database for tags and prepares them.

##### Method
`tag_names`

##### Parameters
None

##### Request Example
```ruby
# Assuming 'article' is an instance of an ActiveRecord model with Gutentag
tags = article.tag_names
```

##### Response
Returns an array of tag names (strings).

#### `tag_names=(names)`

##### Description
Sets the tag names for the model instance. It prepares the names and then uses the setter to update the underlying attribute, ensuring change tracking is handled correctly.

##### Method
`tag_names=(names)`

##### Parameters
- **names** (Array<String> or String) - The tag names to set.

##### Request Example
```ruby
# Assuming 'article' is an instance of an ActiveRecord model with Gutentag
article.tag_names = ['ruby', 'rails', 'gem']
```

##### Response
Returns the result of the `super` call, typically the assigned value.
```

--------------------------------

### Gutentag::TaggedWith::IDQuery Class

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TaggedWith/IDQuery

Details about the Gutentag::TaggedWith::IDQuery class, its inheritance, and methods.

```APIDOC
## Class: Gutentag::TaggedWith::IDQuery

### Description
Represents a query for tagged items based on their IDs.

### Inheritance
- Query
- Object
- Gutentag::TaggedWith::IDQuery

### Defined in
- lib/gutentag/tagged_with/id_query.rb

### Methods inherited from Query
- #call
- #initialize

### Constructor Details
This class inherits its constructor from `Gutentag::TaggedWith::Query`.
```

--------------------------------

### Gutentag::TaggedWith.call

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TaggedWith.call

This method is used to initialize and call the TaggedWith functionality.

```APIDOC
## Gutentag::TaggedWith.call

### Description
This class method initializes a new instance of `Gutentag::TaggedWith` with the provided model and options, and then calls the instance's `call` method.

### Method
`call(model, options)`

### Endpoint
N/A (This is a Ruby method, not an API endpoint)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```ruby
Gutentag::TaggedWith.call(user, { scope: :posts })
```

### Response
#### Success Response (200)
Returns the result of the `call` method on the `Gutentag::TaggedWith` instance, which is typically an object or collection related to tagged items.

#### Response Example
```ruby
# Example response structure depends on the implementation of Gutentag::TaggedWith#call
# For instance, it might return a collection of tagged records.
[
  # ... tagged records ...
]
```
```

--------------------------------

### Gutentag::ActiveRecord.call Method Implementation

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ActiveRecord.call

This method is used to initialize and call the Gutentag::ActiveRecord class with a given model. Ensure the model is compatible with ActiveRecord.

```ruby
def self.call(model)
  new(model).call
end
```

--------------------------------

### Gutentag::Persistence Instance Attribute: tagger=

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/Persistence

Details for the tagger= attribute setter in Gutentag::Persistence.

```APIDOC
## Instance Attribute Details

### permalink #**tagger=**(value) ⇒ `Object`

Sets the attribute tagger
Parameters:
  * value — 
the value to set the attribute tagger to.

```ruby
# File 'lib/gutentag/persistence.rb', line 8

def tagger=(value)
  @tagger = value
end
```
```

--------------------------------

### Retrieve tag names

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ActiveRecord/InstanceMethods

Fetches tag names from the database if they have not been prepared yet.

```ruby
# File 'lib/gutentag/active_record/instance_methods.rb', line 22

def tag_names
  if super.nil? || !prepared_tag_names?
    # If the underlying value is nil, we've not requested this from the
    # database yet. But we also don't want to make the query twice. So, grab
    # the names, prepare as needed, and make sure we also invoke the setter.
    names = tags.pluck(:name)

    prepare_tag_names(names)
    self.tag_names = names
  end

  # Use ActiveRecord's underlying implementation with change tracking.
  super
end
```

--------------------------------

### Query Articles by Tag IDs (Match None)

Source: https://www.rubydoc.info/gems/gutentag/file/README.md

Find articles that have none of the specified tag IDs. This uses NOT logic.

```ruby
# Returns all articles that have *neither* tag_a nor tag_b.
Article.tagged_with(:ids => [tag_a.id, tag_b.id], :match => :none)
```

--------------------------------

### Initialize TagValidations in Ruby

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TagValidations%3Ainitialize

Initializes a new instance of TagValidations. This method is part of the Gutentag::TagValidations class.

```ruby
def initialize(klass)
  @klass = klass
end
```

--------------------------------

### Gutentag::Persistence#persist Method

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/Persistence%3Apersist

Documentation for the `persist` method in the `Gutentag::Persistence` module. This method is responsible for removing old tags and adding new ones.

```APIDOC
## Gutentag::Persistence#persist

### Description
Persists tags by removing old ones and adding new ones.

### Method
Instance Method

### Endpoint
N/A (This is a Ruby method, not an API endpoint)

### Parameters
None

### Request Body
None

### Request Example
```ruby
persistence_instance.persist
```

### Response
#### Success Response
Returns `Object` (typically `nil` or the result of `add_new`).

#### Response Example
```ruby
# No specific return value documented, implies side effects.
```
```

--------------------------------

### Calculate Added Tags

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ChangeState

Returns the list of tags that have been added.

```ruby
def added
  @added ||= changes - existing
end
```

--------------------------------

### Execute Gutentag::TaggedWith::Query

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TaggedWith/Query

Executes the query to find records matching the specified tags. It constructs a SQL WHERE clause based on the model and query parameters.

```ruby
def call
  model.where "#{model_id} #{operator} (#{query.to_sql})"
end
```

--------------------------------

### Gutentag::ActiveRecord::InstanceMethods#tag_names=

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ActiveRecord/InstanceMethods%3Atag_names%3D

This method is used to set the tag names for an ActiveRecord model. It prepares the tag names and then assigns them using the superclass method.

```APIDOC
## Gutentag::ActiveRecord::InstanceMethods#tag_names=

### Description
Sets the tag names for an ActiveRecord model. It first prepares the tag names by ensuring proper formatting and then assigns them using the superclass's assignment method.

### Method
`tag_names=(names)`

### Endpoint
N/A (Instance Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```ruby
# Assuming an instance of a model that includes Gutentag::ActiveRecord::InstanceMethods
model_instance.tag_names = ['ruby', 'rails', 'gem']
```

### Response
#### Success Response (200)
Returns the assigned object (typically an array of tag names or a similar representation).

#### Response Example
```ruby
# The return value is usually the object assigned, which might be an array or a custom tag object.
['ruby', 'rails', 'gem']
```
```

--------------------------------

### Implement Gutentag Persistence

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/Persistence%3Apersist

This method is responsible for removing old tags and adding new ones. It is part of the Gutentag::Persistence class.

```ruby
def persist
  remove_old
  add_new
end
```

--------------------------------

### Gutentag Class Hierarchy

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/Tagging

An overview of the class hierarchy within the Gutentag gem.

```APIDOC
# Gutentag Gem Class List

## Top Level Namespace

### Gutentag

#### ActiveRecord < Gutentag
  * ClassMethodsGutentag::ActiveRecord
  * InstanceMethodsGutentag::ActiveRecord

#### ChangeState < Gutentag

#### Engine < EngineGutentag

#### GeneratorsGutentag
  * MigrationVersionsGenerator < BaseGutentag::Generators

#### Persistence < Gutentag

#### RemoveUnused < Gutentag

#### Tag < BaseGutentag

#### TagNames < Gutentag

#### TagValidations < Gutentag

#### TaggedWith < Gutentag
  * IDQuery < QueryGutentag::TaggedWith
  * NameQuery < QueryGutentag::TaggedWith
  * Query < ObjectGutentag::TaggedWith

#### Tagging < BaseGutentag
```

--------------------------------

### Gutentag::TagValidations#call Method

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TagValidations%3Acall

Documentation for the `call` method within the `Gutentag::TagValidations` class.

```APIDOC
## Gutentag::TagValidations#call

### Description
This method applies validations to the tag name using the provided validation options.

### Method
`call`

### Endpoint
N/A (Instance Method)

### Parameters
None

### Request Example
N/A

### Response
#### Success Response (Object)
- Returns the result of the `klass.validates` call.

#### Response Example
N/A
```

--------------------------------

### Gutentag::TaggedWith::Query#call

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TaggedWith/Query

Executes the query to find records matching the specified tags. It constructs a SQL query based on the model and tag values.

```APIDOC
## call()

### Description
Executes the query to find records matching the specified tags.

### Method
GET

### Endpoint
/api/tagged_items

### Parameters
#### Query Parameters
- **model_id** (String) - Required - The ID of the model to query.
- **operator** (String) - Required - The SQL operator to use for the query (e.g., 'IN', 'NOT IN').
- **query_sql** (String) - Required - The SQL string representing the tag query.

### Request Example
```json
{
  "model_id": "posts.id",
  "operator": "IN",
  "query_sql": "(SELECT taggings.taggable_id FROM taggings WHERE taggings.taggable_type = 'Post' AND taggings.tag_id IN (SELECT id FROM tags WHERE name IN ('ruby', 'rails')))"
}
```

### Response
#### Success Response (200)
- **Object** (Object) - The records matching the query.

### Response Example
```json
{
  "data": [
    {
      "id": 1,
      "title": "My First Post"
    },
    {
      "id": 2,
      "title": "Another Post"
    }
  ]
}
```
```

--------------------------------

### Implement tag_names Method in Gutentag::ActiveRecord

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ActiveRecord/InstanceMethods%3Atag_names

This method retrieves and prepares tag names for ActiveRecord models. It handles cases where tags haven't been loaded yet, ensuring efficient querying and proper assignment.

```ruby
def tag_names
  if super.nil? || !prepared_tag_names?
    # If the underlying value is nil, we've not requested this from the
    # database yet. But we also don't want to make the query twice. So, grab
    # the names, prepare as needed, and make sure we also invoke the setter.
    names = tags.pluck(:name)

    prepare_tag_names(names)
    self.tag_names = names
  end

  # Use ActiveRecord's underlying implementation with change tracking.
  super
end
```

--------------------------------

### Gutentag::ActiveRecord::InstanceMethods#tag_names

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ActiveRecord/InstanceMethods%3Atag_names

This method retrieves and prepares tag names for an ActiveRecord model. It handles cases where tags might not have been loaded yet, ensuring efficient data retrieval and preparation.

```APIDOC
## Gutentag::ActiveRecord::InstanceMethods#tag_names

### Description
Retrieves and prepares tag names for an ActiveRecord model. It ensures that tag names are fetched from the database only when necessary and are properly prepared before being returned.

### Method
Instance Method

### Endpoint
N/A (This is a Ruby method, not an API endpoint)

### Parameters
None

### Request Example
N/A

### Response
#### Success Response
- **Object**: Returns an object representing the tag names.

#### Response Example
```ruby
# Example usage within an ActiveRecord model:
# model_instance.tag_names
```
```

--------------------------------

### Gutentag::TaggedWith::Query#call Method

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TaggedWith/Query%3Acall

Documentation for the `call` method within the `Gutentag::TaggedWith::Query` class. This method is used to query records based on tags.

```APIDOC
## Gutentag::TaggedWith::Query#call

### Description
Executes a query to find records associated with specific tags.

### Method
GET (Implicit, as it's a query execution)

### Endpoint
N/A (This is a class method execution within the Ruby codebase)

### Parameters
This method does not take explicit parameters in its definition, but relies on instance variables set within the `Query` object:
- `model` (Object) - The ActiveRecord model to query.
- `model_id` (String) - The foreign key column name in the model.
- `operator` (String) - The SQL operator to use for the comparison (e.g., '=', 'IN').
- `query` (Object) - An object that can generate SQL for tag conditions.

### Request Example
```ruby
# Assuming a Query object is already instantiated and configured
query_result = Gutentag::TaggedWith::Query.new(model, model_id, operator, query).call
```

### Response
#### Success Response (200)
- `ActiveRecord::Relation` - A collection of model instances matching the tag query.

#### Response Example
```ruby
# Example of a potential return value (ActiveRecord::Relation)
# This would be a collection of objects, e.g., posts, articles, etc.
[#<Post id: 1, title: "First Post", ...>,
 #<Post id: 5, title: "Another Post", ...>]
```
```

--------------------------------

### Call Gutentag::TagValidations

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TagValidations.call

Use this method to initiate the tag validation process for a given class. It instantiates and calls the validator.

```ruby
def self.call(klass)
  new(klass).call
end
```

--------------------------------

### Gutentag::ActiveRecord.call

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ActiveRecord.call

The `call` method in Gutentag::ActiveRecord is a class method used to initialize and call the instance method, likely for processing or applying tags to a model.

```APIDOC
## Gutentag::ActiveRecord.call

### Description
Initializes a new instance of Gutentag::ActiveRecord with the provided model and then calls the instance's `call` method.

### Method
`call(model)`

### Endpoint
N/A (Class Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```ruby
Gutentag::ActiveRecord.call(my_model)
```

### Response
#### Success Response (200)
Returns the result of the instance `call` method, which is typically an `Object`.

#### Response Example
```json
{
  "example": "result_object"
}
```
```

--------------------------------

### Reload ActiveRecord Instance Methods

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ActiveRecord/InstanceMethods%3Areload

Overrides the reload method to reset prepared tag names before calling super.

```ruby
# File 'lib/gutentag/active_record/instance_methods.rb', line 45

def reload(*)
  @prepared_tag_names = false
  super
end
```

--------------------------------

### Gutentag::TagValidations.call

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TagValidations.call

This method is defined in `lib/gutentag/tag_validations.rb`. It is a class method that takes a class `klass` as an argument and returns an instance of `Gutentag::TagValidations` initialized with `klass`, then calls the instance's `call` method.

```APIDOC
## Gutentag::TagValidations.call

### Description
This class method initializes a new `Gutentag::TagValidations` object with the provided class `klass` and then calls its `call` method.

### Method
`call(klass)`

### Endpoint
N/A (Class Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```ruby
Gutentag::TagValidations.call(MyModel)
```

### Response
#### Success Response (200)
Returns an instance of `Gutentag::TagValidations` after its `call` method has been executed.

#### Response Example
```json
// No specific JSON response example provided, as this is a Ruby method.
```
```

--------------------------------

### Set Tag Names in ActiveRecord

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ActiveRecord/InstanceMethods%3Atag_names%3D

Assigns tag names to an ActiveRecord model. This method prepares the tag names before passing them to the superclass. Ensure that the `prepare_tag_names` method is defined in the class.

```ruby
def tag_names=(names)
  # This value is about to be overwritten, but we want to make sure the change
  # tracking doesn't think the original value was nil.
  prepare_tag_names

  super Gutentag::TagNames.call(names)
end
```

--------------------------------

### Add Gutentag Gem to Gemfile

Source: https://www.rubydoc.info/gems/gutentag/file/README.md

Specify the Gutentag gem and its version constraint in your application's Gemfile to include it in your project.

```ruby
gem 'gutentag', '~> 3.0'
```

--------------------------------

### Configure custom tag normaliser

Source: https://www.rubydoc.info/gems/gutentag/file/README.md

Provide a callable object to Gutentag.normaliser to define how tag values are converted to strings.

```ruby
Gutentag.normaliser = lambda { |value| value.to_s.upcase }
```

--------------------------------

### Implement tagged_with method in Gutentag::ActiveRecord::ClassMethods

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ActiveRecord/ClassMethods

This method is used to query records tagged with specific tags. It requires the Gutentag::TaggedWith class to be available.

```ruby
def tagged_with(options)
  Gutentag::TaggedWith.call self, options
end
```

--------------------------------

### Gutentag::TagNames Class Method

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TagNames

Details on the .call class method of the Gutentag::TagNames class, used for processing tag names.

```APIDOC
## Gutentag::TagNames.call

### Description
Processes an array of tag names, returning a unique, normalized, and non-blank list.

### Method
Class Method

### Endpoint
N/A (Class Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```ruby
Gutentag::TagNames.call(["tag1", " tag2 ", "tag1", nil, ""])
```

### Response
#### Success Response (200)
- **Array** - A unique, normalized, and non-blank array of tag names.

#### Response Example
```json
["tag1", "tag2"]
```
```

--------------------------------

### Define Gutentag database schema

Source: https://www.rubydoc.info/gems/gutentag/file/README.md

Use this schema when integrating Gutentag into projects without Rails migrations.

```ruby
create_table :gutentag_tags do |t|
  t.string :name,           null: false, index: {unique: true}
  t.bigint :taggings_count, null: false, index: true, default: 0
  t.timestamps              null: false
end

create_table :gutentag_taggings do |t|
  t.references :tag,      null: false, index: true, foreign_key: {to_table: :gutentag_tags}
  t.references :taggable, null: false, index: true, polymorphic: true
  t.timestamps            null: false
end
add_index :gutentag_taggings, [:taggable_type, :taggable_id, :tag_id], unique: true, name: "gutentag_taggings_uniqueness"
```

--------------------------------

### Gutentag::ActiveRecord::ClassMethods#tagged_with

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ActiveRecord/ClassMethods

This method, defined within the Gutentag::ActiveRecord::ClassMethods module, allows you to query records based on their tags. It accepts options to specify the tags to filter by.

```APIDOC
## tagged_with(options)

### Description
Queries records based on associated tags using the provided options.

### Method
Instance Method

### Endpoint
N/A (Instance Method)

### Parameters
#### Instance Parameters
- **options** (Hash) - Required - A hash of options to specify the tags for filtering.

### Request Example
```ruby
# Assuming 'Article' is an ActiveRecord model with Gutentag enabled
Article.tagged_with(name: 'ruby')
Article.tagged_with(ids: [1, 2, 3])
```

### Response
#### Success Response (200)
- **Object** - Returns a collection of objects that match the tagging criteria.

#### Response Example
```ruby
# Example of a successful response (collection of ActiveRecord objects)
[#<Article id: 1, title: "First Post", ...>,
 #<Article id: 5, title: "Another Article", ...>]
```
```

--------------------------------

### Calculate Removed Tags

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ChangeState

Returns the list of tags that have been removed.

```ruby
def removed
  @removed ||= existing - changes
end
```

--------------------------------

### Manage Tags Using String Representations

Source: https://www.rubydoc.info/gems/gutentag/file/README.md

Use the `tag_names` accessor to easily add, remove, or view tags as an array of strings. Changes are not persisted until the model is saved.

```ruby
article.tag_names #=> ['pancakes', 'melbourne', 'ruby']
article.tag_names << 'portland'
article.tag_names #=> ['pancakes', 'melbourne', 'ruby', 'portland']
article.tag_names -= ['ruby']
article.tag_names #=> ['pancakes', 'melbourne', 'portland']
```

--------------------------------

### Gutentag::Tag#name=

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/Tag%3Aname%3D

Sets the name attribute for a Gutentag::Tag object, applying a normalization process.

```APIDOC
## Gutentag::Tag#name=

### Description
Sets the name attribute for a Gutentag::Tag object, applying a normalization process using Gutentag.normaliser.

### Method
`name=(value)`

### Endpoint
N/A (Instance Method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
Returns the normalized value that was set.

#### Response Example
None
```

--------------------------------

### Set Tag Name with Normalization

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/Tag%3Aname%3D

Use this method to set the name of a tag. It automatically normalizes the input value using Gutentag's configured normalizer before saving.

```ruby
def name=(value)
  write_attribute(:name, Gutentag.normaliser.call(value))
end
```

--------------------------------

### Remove unused tags via Gutentag::RemoveUnused.call

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/RemoveUnused.call

Executes a SQL DELETE statement to remove tags that are not associated with any taggings.

```ruby
def self.call
  Gutentag::Tag.connection.execute <<-SQL
DELETE FROM gutentag_tags
WHERE id NOT IN (SELECT DISTINCT tag_id FROM gutentag_taggings)
  SQL
end
```

--------------------------------

### Gutentag::Persistence#tagger=

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/Persistence%3Atagger%3D

Sets the tagger attribute for the Persistence class.

```APIDOC
## Gutentag::Persistence#tagger=

### Description
Sets the attribute tagger.

### Method
`tagger=(value)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **tagger** (Object) - The value to set the attribute tagger to.

#### Response Example
None
```

--------------------------------

### Configure custom tag validations

Source: https://www.rubydoc.info/gems/gutentag/file/README.md

Assign a custom validation object that responds to call to override default tag validation logic.

```ruby
Gutentag.tag_validations = CustomTagValidations
```

--------------------------------

### Update migration versions in Gutentag

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/Generators/MigrationVersionsGenerator%3Aupdate_migration_versions

Updates migration files to use the current Rails version by replacing the hardcoded migration version in the file content.

```ruby
# File 'lib/gutentag/generators/migration_versions_generator.rb', line 10

def update_migration_versions
  superclass = "ActiveRecord::Migration[#{rails_version}]"

  migration_files.each do |file|
    gsub_file file,
      /< ActiveRecord::Migration\[4\.2\]$/,
      "< #{superclass}"
  end
end
```

--------------------------------

### Normalize and Deduplicate Tag Names

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/TagNames

Use this class method to process an array of tag names. It filters out blank names, removes duplicates, and normalizes each name using the configured normalizer. Returns nil if the input is nil.

```ruby
def self.call(names)
  return nil if names.nil?

  names.reject(&:blank?).uniq.collect do |name|
    Gutentag.normaliser.call(name)
  end
end
```

--------------------------------

### Define AR_VERSION constant

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ActiveRecord/InstanceMethods

Determines the ActiveRecord version as a float.

```ruby
ActiveRecord::VERSION::STRING.to_f
```

--------------------------------

### Gutentag::Generators::MigrationVersionsGenerator#update_migration_versions

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/Generators/MigrationVersionsGenerator%3Aupdate_migration_versions

Updates existing migration files to use the current Rails version instead of the hardcoded 4.2 version.

```APIDOC
## Method: update_migration_versions

### Description
Updates migration files within the project to match the current Rails version by replacing the hardcoded ActiveRecord::Migration[4.2] superclass with the current environment's Rails version.

### Method
Internal Ruby Method

### Parameters
None

### Response
- **Returns** (Object) - Performs file system modifications via gsub_file.
```

--------------------------------

### Update Migration Versions

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/Generators/MigrationVersionsGenerator

Updates migration files to use the current Rails migration version by replacing older ActiveRecord::Migration versions.

```ruby
def update_migration_versions
  superclass = "ActiveRecord::Migration[#{rails_version}]"

  migration_files.each do |file|
    gsub_file file,
      /< ActiveRecord::Migration\[4\.2\]$/,
      "< #{superclass}"
  end
end
```

--------------------------------

### Set Tagger Attribute in Gutentag::Persistence

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/Persistence%3Atagger%3D

Use this method to set the tagger attribute for Gutentag persistence. It takes a single value argument.

```Ruby
def tagger=(value)
  @tagger = value
end
```

--------------------------------

### Gutentag::Tag.names_for_scope

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/Tag.find_or_create

Retrieves a distinct list of tag names associated with a given scope (e.g., a model instance or relation).

```APIDOC
## Gutentag::Tag.names_for_scope

### Description
Retrieves a distinct list of tag names associated with a given scope. The scope can be an ActiveRecord::Relation or a model instance.

### Method
`self.names_for_scope(scope)`

### Parameters
- **scope** (Object) - The scope for which to retrieve tag names. This is typically an ActiveRecord model instance or a relation.

### Request Example
```ruby
Gutentag::Tag.names_for_scope(my_model_instance)
Gutentag::Tag.names_for_scope(MyModel.where(id: [1, 2, 3]))
```

### Response
#### Success Response (200)
- **Array<String>** - A distinct list of tag names associated with the scope.

#### Response Example
```json
["tag1", "tag2", "tag3"]
```
```

--------------------------------

### Reset tag names implementation

Source: https://www.rubydoc.info/gems/gutentag/Gutentag/ActiveRecord/InstanceMethods%3Areset_tag_names

Updates the tag_names attribute directly to avoid triggering change tracking, provided no changes have already been saved.

```ruby
def reset_tag_names
  return if saved_change_to_tag_names?

  # Update the underlying value rather than going through the setter, to
  # ensure this update doesn't get marked as a 'change'.
  @attributes.write_from_database "tag_names", []
  @prepared_tag_names = false
end
```
Tokens:
Raw