Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Added new clean Ransack customization DSL (#13442)
Damian Legawiec6cc3a4999cdc
diff --git a/core/app/models/concerns/spree/ransackable_attributes.rb b/core/app/models/concerns/spree/ransackable_attributes.rbindex c06cb6ed49..6cd245a917 100644--- a/core/app/models/concerns/spree/ransackable_attributes.rb+++ b/core/app/models/concerns/spree/ransackable_attributes.rb@@ -9,15 +9,18 @@ module Spree::RansackableAttributesself.default_ransackable_attributes = %w[id name updated_at created_at]def self.ransackable_associations(*_args)- whitelisted_ransackable_associations || []+ base = whitelisted_ransackable_associations || []+ base | Spree.ransack.custom_associations_for(self)enddef self.ransackable_attributes(*_args)- default_ransackable_attributes | (whitelisted_ransackable_attributes || [])+ base = default_ransackable_attributes | (whitelisted_ransackable_attributes || [])+ base | Spree.ransack.custom_attributes_for(self)enddef self.ransackable_scopes(*_args)- whitelisted_ransackable_scopes || []+ base = whitelisted_ransackable_scopes || []+ base | Spree.ransack.custom_scopes_for(self)endendenddiff --git a/core/lib/spree/core.rb b/core/lib/spree/core.rbindex 2ffd73db31..2d23ae9004 100644--- a/core/lib/spree/core.rb+++ b/core/lib/spree/core.rb@@ -358,6 +358,19 @@ module Spree@permissions ||= PermissionConfiguration.newend+ # Ransack configuration accessor for managing custom ransackable attributes,+ # associations, and scopes across Spree models.+ #+ # @example Adding custom searchable fields+ # Spree.ransack.add_attribute(Spree::Product, :vendor_id)+ # Spree.ransack.add_scope(Spree::Product, :by_vendor)+ # Spree.ransack.add_association(Spree::Product, :vendor)+ #+ # @return [Spree::RansackConfiguration] the ransack configuration instance+ def self.ransack+ @ransack ||= RansackConfiguration.new+ end+class << self# Dynamic methods for core dependencies#@@ -436,5 +449,6 @@ require 'spree/core/preferences/scoped_store'require 'spree/core/preferences/runtime_configuration'require 'spree/core/permission_configuration'+require 'spree/core/ransack_configuration'require 'spree/core/pricing/context'require 'spree/core/pricing/resolver'diff --git a/core/lib/spree/core/ransack_configuration.rb b/core/lib/spree/core/ransack_configuration.rbnew file mode 100644index 0000000000..86c368e26c--- /dev/null+++ b/core/lib/spree/core/ransack_configuration.rb@@ -0,0 +1,79 @@+module Spree+ # Centralized configuration for Ransack searchable attributes, associations, and scopes.+ #+ # This class allows developers to extend Spree models with custom ransackable+ # configurations without using decorators.+ #+ # @example Adding custom searchable fields+ # Spree.ransack.add_attribute(Spree::Product, :vendor_id)+ # Spree.ransack.add_scope(Spree::Product, :by_vendor)+ # Spree.ransack.add_association(Spree::Product, :vendor)+ #+ class RansackConfiguration+ def initialize+ @custom_attributes = Hash.new { |h, k| h[k] = [] }+ @custom_associations = Hash.new { |h, k| h[k] = [] }+ @custom_scopes = Hash.new { |h, k| h[k] = [] }+ end++ # Add a custom ransackable attribute to a model.+ #+ # @param model [Class] the model class to configure (e.g., Spree::Product)+ # @param attribute [String, Symbol] the attribute to add+ # @return [Array<String>] the updated list of custom attributes+ def add_attribute(model, attribute)+ @custom_attributes[model.name.to_sym] |= [attribute.to_s]+ end++ # Add a custom ransackable association to a model.+ #+ # @param model [Class] the model class to configure (e.g., Spree::Product)+ # @param association [String, Symbol] the association to add+ # @return [Array<String>] the updated list of custom associations+ def add_association(model, association)+ @custom_associations[model.name.to_sym] |= [association.to_s]+ end++ # Add a custom ransackable scope to a model.+ #+ # @param model [Class] the model class to configure (e.g., Spree::Product)+ # @param scope [String, Symbol] the scope to add+ # @return [Array<String>] the updated list of custom scopes+ def add_scope(model, scope)+ @custom_scopes[model.name.to_sym] |= [scope.to_s]+ end++ # Get custom ransackable attributes for a model.+ #+ # @param model [Class] the model class to query+ # @return [Array<String>] the custom attributes+ def custom_attributes_for(model)+ @custom_attributes[model.name.to_sym]+ end++ # Get custom ransackable associations for a model.+ #+ # @param model [Class] the model class to query+ # @return [Array<String>] the custom associations+ def custom_associations_for(model)+ @custom_associations[model.name.to_sym]+ end++ # Get custom ransackable scopes for a model.+ #+ # @param model [Class] the model class to query+ # @return [Array<String>] the custom scopes+ def custom_scopes_for(model)+ @custom_scopes[model.name.to_sym]+ end++ # Reset all custom configurations. Useful for testing.+ #+ # @return [void]+ def reset!+ @custom_attributes.clear+ @custom_associations.clear+ @custom_scopes.clear+ end+ end+enddiff --git a/core/spec/lib/spree/core/ransack_configuration_spec.rb b/core/spec/lib/spree/core/ransack_configuration_spec.rbnew file mode 100644index 0000000000..43874f1ba4--- /dev/null+++ b/core/spec/lib/spree/core/ransack_configuration_spec.rb@@ -0,0 +1,119 @@+require 'spec_helper'++RSpec.describe Spree::RansackConfiguration do+ subject(:config) { described_class.new }++ describe '#add_attribute' do+ it 'adds an attribute to a model' do+ config.add_attribute(Spree::Product, :vendor_id)++ expect(config.custom_attributes_for(Spree::Product)).to contain_exactly('vendor_id')+ end++ it 'adds to existing attributes when called multiple times' do+ config.add_attribute(Spree::Product, :vendor_id)+ config.add_attribute(Spree::Product, :brand_name)++ expect(config.custom_attributes_for(Spree::Product)).to contain_exactly('vendor_id', 'brand_name')+ end++ it 'does not duplicate attributes' do+ config.add_attribute(Spree::Product, :vendor_id)+ config.add_attribute(Spree::Product, :vendor_id)++ expect(config.custom_attributes_for(Spree::Product)).to contain_exactly('vendor_id')+ end++ it 'converts symbol to string' do+ config.add_attribute(Spree::Product, :vendor_id)++ expect(config.custom_attributes_for(Spree::Product)).to eq(['vendor_id'])+ end+ end++ describe '#add_association' do+ it 'adds an association to a model' do+ config.add_association(Spree::Product, :vendor)++ expect(config.custom_associations_for(Spree::Product)).to contain_exactly('vendor')+ end++ it 'adds to existing associations when called multiple times' do+ config.add_association(Spree::Product, :vendor)+ config.add_association(Spree::Product, :brand)++ expect(config.custom_associations_for(Spree::Product)).to contain_exactly('vendor', 'brand')+ end++ it 'does not duplicate associations' do+ config.add_association(Spree::Product, :vendor)+ config.add_association(Spree::Product, :vendor)++ expect(config.custom_associations_for(Spree::Product)).to contain_exactly('vendor')+ end+ end++ describe '#add_scope' do+ it 'adds a scope to a model' do+ config.add_scope(Spree::Product, :by_vendor)++ expect(config.custom_scopes_for(Spree::Product)).to contain_exactly('by_vendor')+ end++ it 'adds to existing scopes when called multiple times' do+ config.add_scope(Spree::Product, :by_vendor)+ config.add_scope(Spree::Product, :featured)++ expect(config.custom_scopes_for(Spree::Product)).to contain_exactly('by_vendor', 'featured')+ end++ it 'does not duplicate scopes' do+ config.add_scope(Spree::Product, :by_vendor)+ config.add_scope(Spree::Product, :by_vendor)++ expect(config.custom_scopes_for(Spree::Product)).to contain_exactly('by_vendor')+ end+ end++ describe '#custom_attributes_for' do+ it 'returns an empty array for models with no custom attributes' do+ expect(config.custom_attributes_for(Spree::Product)).to eq([])+ end+ end++ describe '#custom_associations_for' do+ it 'returns an empty array for models with no custom associations' do+ expect(config.custom_associations_for(Spree::Product)).to eq([])+ end+ end++ describe '#custom_scopes_for' do+ it 'returns an empty array for models with no custom scopes' do+ expect(config.custom_scopes_for(Spree::Product)).to eq([])+ end+ end++ describe '#reset!' do+ it 'clears all custom configurations' do+ config.add_attribute(Spree::Product, :vendor_id)+ config.add_scope(Spree::Order, :by_region)+ config.add_association(Spree::Variant, :vendor)++ config.reset!++ expect(config.custom_attributes_for(Spree::Product)).to eq([])+ expect(config.custom_scopes_for(Spree::Order)).to eq([])+ expect(config.custom_associations_for(Spree::Variant)).to eq([])+ end+ end++ describe 'isolation between models' do+ it 'keeps configurations separate per model' do+ config.add_attribute(Spree::Product, :product_attr)+ config.add_attribute(Spree::Order, :order_attr)++ expect(config.custom_attributes_for(Spree::Product)).to contain_exactly('product_attr')+ expect(config.custom_attributes_for(Spree::Order)).to contain_exactly('order_attr')+ end+ end+enddiff --git a/core/spec/models/spree/concerns/ransackable_attributes_spec.rb b/core/spec/models/spree/concerns/ransackable_attributes_spec.rbnew file mode 100644index 0000000000..eb1204b2d0--- /dev/null+++ b/core/spec/models/spree/concerns/ransackable_attributes_spec.rb@@ -0,0 +1,65 @@+require 'spec_helper'++RSpec.describe Spree::RansackableAttributes do+ before do+ Spree.ransack.reset!+ end++ after do+ Spree.ransack.reset!+ end++ describe '.ransackable_attributes' do+ it 'returns default and whitelisted attributes' do+ expect(Spree::Product.ransackable_attributes).to include('id', 'name', 'description', 'slug')+ end++ it 'merges custom attributes from Spree.ransack' do+ Spree.ransack.add_attribute(Spree::Product, :vendor_id)++ expect(Spree::Product.ransackable_attributes).to include('vendor_id')+ end++ it 'does not duplicate attributes' do+ Spree.ransack.add_attribute(Spree::Product, :name)++ expect(Spree::Product.ransackable_attributes.count('name')).to eq(1)+ end+ end++ describe '.ransackable_associations' do+ it 'returns whitelisted associations' do+ expect(Spree::Product.ransackable_associations).to include('taxons', 'variants')+ end++ it 'merges custom associations from Spree.ransack' do+ Spree.ransack.add_association(Spree::Product, :vendor)++ expect(Spree::Product.ransackable_associations).to include('vendor')+ end++ it 'does not duplicate associations' do+ Spree.ransack.add_association(Spree::Product, :taxons)++ expect(Spree::Product.ransackable_associations.count('taxons')).to eq(1)+ end+ end++ describe '.ransackable_scopes' do+ it 'returns whitelisted scopes' do+ expect(Spree::Product.ransackable_scopes).to include('not_discontinued', 'search_by_name')+ end++ it 'merges custom scopes from Spree.ransack' do+ Spree.ransack.add_scope(Spree::Product, :by_vendor)++ expect(Spree::Product.ransackable_scopes).to include('by_vendor')+ end++ it 'does not duplicate scopes' do+ Spree.ransack.add_scope(Spree::Product, :not_discontinued)++ expect(Spree::Product.ransackable_scopes.count('not_discontinued')).to eq(1)+ end+ end+enddiff --git a/docs/developer/core-concepts/search-filtering.mdx b/docs/developer/core-concepts/search-filtering.mdxindex 2c90b6c04b..d8c4fe7b3d 100644--- a/docs/developer/core-concepts/search-filtering.mdx+++ b/docs/developer/core-concepts/search-filtering.mdx@@ -315,6 +315,78 @@ GET /api/v2/platform/products?sort=status,-created_atPlatform API sorting is handled separately from Ransack's filter parameter and follows JSON:API conventions.</Info>+## Extending Ransackable Configuration++If you need to add custom ransackable attributes, associations, or scopes to Spree's built-in models without using decorators, use the `Spree.ransack` configuration API.++### Adding Custom Configuration++Add the following to your initializer (e.g., `config/initializers/spree.rb`):++```ruby+Rails.application.config.after_initialize do+ # Add a custom searchable attribute to Products+ Spree.ransack.add_attribute(Spree::Product, :vendor_id)++ # Add a custom searchable scope to Products+ Spree.ransack.add_scope(Spree::Product, :by_vendor)++ # Add a custom searchable association to Products+ Spree.ransack.add_association(Spree::Product, :vendor)++ # Add multiple configurations for Orders+ Spree.ransack.add_attribute(Spree::Order, :custom_reference)+ Spree.ransack.add_scope(Spree::Order, :high_value)+ Spree.ransack.add_association(Spree::Order, :sales_rep)+end+```++<Info>+The `Spree.ransack` API only allows adding new searchable fields. It does not support removing default configurations to prevent accidentally breaking core functionality.+</Info>++### Available Methods++| Method | Description | Example |+|--------|-------------|---------|+| `add_attribute` | Add a searchable attribute | `Spree.ransack.add_attribute(Spree::Product, :vendor_id)` |+| `add_scope` | Add a searchable scope | `Spree.ransack.add_scope(Spree::Product, :featured)` |+| `add_association` | Add a searchable association | `Spree.ransack.add_association(Spree::Product, :vendor)` |++### Complete Example++Here's an example of extending Products with a vendor relationship:++```ruby+# app/models/vendor.rb+class Vendor < ApplicationRecord+ has_many :products, class_name: 'Spree::Product'+end++# db/migrate/xxx_add_vendor_to_spree_products.rb+class AddVendorToSpreeProducts < ActiveRecord::Migration[7.0]+ def change+ add_reference :spree_products, :vendor+ end+end++# config/initializers/spree.rb+Rails.application.config.after_initialize do+ Spree.ransack.add_attribute(Spree::Product, :vendor_id)+ Spree.ransack.add_association(Spree::Product, :vendor)+end+```++Now you can search products by vendor:++```bash+# Filter by vendor_id+GET /api/v2/platform/products?filter[vendor_id_eq]=123++# Filter by vendor name (through association)+GET /api/v2/platform/products?filter[vendor_name_cont]=acme+```+## Custom Implementation Examples### Example 1: Brand Resource