diff --git a/docs/how-tos/how-to-use-a-custom-brand-selector.mdx b/docs/how-tos/how-to-use-a-custom-brand-selector.mdx new file mode 100644 index 0000000..a8cc952 --- /dev/null +++ b/docs/how-tos/how-to-use-a-custom-brand-selector.mdx @@ -0,0 +1,85 @@ +--- +sidebar_position: 10 +--- +# Introduction +Brands are a frequently required information in ecommerce. +They allow +* more comprehensive analytics; +* They allow your customers to filter products from a certain manufacturer; +* They are frequently used in product feeds for marketing platforms such as Google Shopping. + +With the integration of Brands inside Solidus all above detailed scenarios are possible. + +# How to Use a Custom Brand Selector + +In Solidus, a product's brand is determined using a configurable `brand_selector_class`. By default, this is set to `Spree::TaxonBrandSelector`, which identifies the brand by associating the product with a taxon under the taxonomy named `"Brands"`. + +This guide explains how to implement and configure a custom brand selector to suit your application's unique requirements. + +## Default Behavior + +By default, the `Spree::TaxonBrandSelector` works as follows: + +- It fetches all taxons associated with a product. +- It filters the taxons by checking if they belong to the `"Brands"` taxonomy. +- It returns the first matching taxon as the brand. + +Here is the default configuration: + +```ruby +Spree.config do |config| + # ... + config.brand_selector_class = 'Spree::TaxonBrandSelector' +end +``` + +# Implementing a Custom Brand Selector + +To override the default behavior, you can create a new class that implements the same interface as `Spree::TaxonBrandSelector`. + +For example, let's say you want to define brands based on specific product properties rather than taxons. Here's how you can do it: + +## Step 1: Create Your Custom Class + +```ruby title="app/models/my_store/custom_brand_selector.rb" +module MyStore + class CustomBrandSelector + def initialize(product) + @product = product + end + + def call + # Replace this with your custom logic. + # For instance, returning a specific brand based on a product's property: + @product.custom_brand_property + end + + private + + attr_reader :product + end +end +``` + +## Step 2: Update the Configuration + +To use your custom brand selector, update the initializer to configure the `brand_selector_class`: + +```ruby title="config/initializers/spree.rb" +Spree.config do |config| + # ... + config.brand_selector_class = 'MyStore::CustomBrandSelector' +end +``` + + +## Verifying the Custom Behavior + +Once you've implemented and configured your custom class, you can verify its behavior by calling the `brand` method on any product. This method will now use your custom selector logic: + +```ruby title="Example: Verifying Custom Brand Selector" +product = Spree::Product.find(1) +puts product.brand # Outputs the result of your custom logic +``` + +[order_adjustments_recalculator]: https://github.com/solidusio/solidus/blob/v3.3/core/app/models/spree/promotion/order_adjustments_recalculator.rb