Skip to content

armgit / spree

Public Imported from GitHub
0

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.

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.rb
index 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::RansackableAttributes
self.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)
end
def self.ransackable_attributes(*_args)
- default_ransackable_attributes | (whitelisted_ransackable_attributes || [])
+ base = default_ransackable_attributes | (whitelisted_ransackable_attributes || [])
+ base | Spree.ransack.custom_attributes_for(self)
end
def self.ransackable_scopes(*_args)
- whitelisted_ransackable_scopes || []
+ base = whitelisted_ransackable_scopes || []
+ base | Spree.ransack.custom_scopes_for(self)
end
end
end
diff --git a/core/lib/spree/core.rb b/core/lib/spree/core.rb
index 2ffd73db31..2d23ae9004 100644
--- a/core/lib/spree/core.rb
+++ b/core/lib/spree/core.rb
@@ -358,6 +358,19 @@ module Spree
@permissions ||= PermissionConfiguration.new
end
+ # 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.rb
new file mode 100644
index 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
+end
diff --git a/core/spec/lib/spree/core/ransack_configuration_spec.rb b/core/spec/lib/spree/core/ransack_configuration_spec.rb
new file mode 100644
index 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
+end
diff --git a/core/spec/models/spree/concerns/ransackable_attributes_spec.rb b/core/spec/models/spree/concerns/ransackable_attributes_spec.rb
new file mode 100644
index 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
+end
diff --git a/docs/developer/core-concepts/search-filtering.mdx b/docs/developer/core-concepts/search-filtering.mdx
index 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_at
Platform 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