### 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::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::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 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. [#, #] ``` ``` -------------------------------- ### 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) [#
, #
] ``` ``` -------------------------------- ### 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** - 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 ```