Class: Spree::Variant

Inherits:
Object
  • Object
show all
Includes:
DefaultPrice, MemoizedData, Metadata, Metafields, Searchable, Webhooks
Defined in:
app/models/spree/variant.rb,
app/models/spree/variant/webhooks.rb

Defined Under Namespace

Modules: Webhooks

Constant Summary collapse

MEMOIZED_METHODS = 
%w(purchasable in_stock on_sale backorderable tax_category options_text compare_at_price)
DIMENSION_UNITS = 
%w[mm cm in ft]
WEIGHT_UNITS = 
%w[g kg lb oz]
LOCALIZED_NUMBERS =

FIXME: cost price should be represented with DisplayMoney class

%w(cost_price weight depth width height)

Constants included from DefaultPrice

DefaultPrice::DEPRECATION_MSG

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Metadata

#metadata, #metadata=, #public_metadata=

Class Method Details

.product_name_or_sku_cont(query) ⇒ Object 



203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'app/models/spree/variant.rb', line 203

def self.product_name_or_sku_cont(query)
  sanitized_query = ActiveRecord::Base.sanitize_sql_like(query.to_s.downcase.strip)
  query_pattern = "%#{sanitized_query}%"
  sku_condition = arel_table[:sku].lower.matches(query_pattern)

  if Spree.use_translations?
    translation_arel_table = Product::Translation.arel_table.alias(Product.translation_table_alias)[:name]
    product_name_condition = translation_arel_table.lower.matches(query_pattern)

    joins(:product).
      join_translation_table(Product).
      where(product_name_condition.or(sku_condition))
  else
    product_name_condition = Product.arel_table[:name].lower.matches(query_pattern)
    joins(:product).where(product_name_condition.or(sku_condition))
  end
end

.search(query) ⇒ Object

Free-text variant search: SKU, parent product name, and any option-value presentation (e.g. “Red”, “XL”). The 3-char floor keeps single-letter queries from triggering a full scan.



147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
 
# File 'app/models/spree/variant.rb', line 147

def self.search(query)
  return none if query.blank? || query.length < 3

  conditions = [
    search_condition(self, :sku, query),
    search_condition(Spree::OptionValue, :presentation, query),
  ]

  if Spree.use_translations?
    translation_table = Product::Translation.arel_table.alias(Product.translation_table_alias)
    sanitized = sanitize_query_for_search(query)
    conditions << translation_table[:name].lower.matches("%#{sanitized}%", '\\')
  else
    conditions << search_condition(Spree::Product, :name, query)
  end

  relation = joins(:product).left_joins(:option_values)
  relation = relation.join_translation_table(Product) if Spree.use_translations?
  relation.where(conditions.reduce(:or)).distinct
end

.search_by_product_name_or_sku(query) ⇒ Object 



221
222
223
 
# File 'app/models/spree/variant.rb', line 221

def self.search_by_product_name_or_sku(query)
  product_name_or_sku_cont(query)
end

Instance Method Details

#additional_images ⇒ Array<Spree::Image>

Returns all images except the default image, combining variant and product images.

Returns:



354
355
356
 
# File 'app/models/spree/variant.rb', line 354

def additional_images
  @additional_images ||= (images + product.images).uniq.reject { |image| image.id == default_image&.id }
end

#amount_in(currency) ⇒ BigDecimal

Returns the amount for the given currency.

Parameters:

  • currency (String) —

    the currency to get the amount for

Returns:

  • (BigDecimal) —

    the amount for the given currency



480
481
482
 
# File 'app/models/spree/variant.rb', line 480

def amount_in(currency)
  price_in(currency).try(:amount)
end

#available? ⇒ Boolean

Returns true if the variant is available.

Returns:

  • (Boolean) —

    true if the variant is available



237
238
239
 
# File 'app/models/spree/variant.rb', line 237

def available?
  !discontinued? && product.available?
end

#backorderable? ⇒ Boolean Also known as: is_backorderable?

Returns true if the variant is backorderable.

Returns:

  • (Boolean) —

    true if the variant is backorderable



624
625
626
 
# File 'app/models/spree/variant.rb', line 624

def backorderable?
  @backorderable ||= quantifier.backorderable?
end

#backordered? ⇒ Boolean

Returns:



668
669
670
 
# File 'app/models/spree/variant.rb', line 668

def backordered?
  @backordered ||= !in_stock? && stock_items.exists?(backorderable: true)
end

#compare_at_amount_in(currency) ⇒ BigDecimal

Returns the compare at amount for the given currency.

Parameters:

  • currency (String) —

    the currency to get the compare at amount for

Returns:

  • (BigDecimal) —

    the compare at amount for the given currency



487
488
489
 
# File 'app/models/spree/variant.rb', line 487

def compare_at_amount_in(currency)
  price_in(currency).try(:compare_at_amount)
end

#compare_at_price ⇒ BigDecimal

Returns the compare at price of the variant.

Returns:

  • (BigDecimal) —

    the compare at price of the variant



612
613
614
 
# File 'app/models/spree/variant.rb', line 612

def compare_at_price
  @compare_at_price ||= price_in(cost_currency).try(:compare_at_amount)
end

#default_image ⇒ Object

Deprecated.

Use #primary_media instead.



324
325
326
327
 
# File 'app/models/spree/variant.rb', line 324

def default_image
  Spree::Deprecation.warn('Spree::Variant#default_image is deprecated and will be removed in Spree 6.0. Please use Spree::Variant#primary_media instead.')
  primary_media
end

#default_stock_location ⇒ Object 



577
578
579
 
# File 'app/models/spree/variant.rb', line 577

def default_stock_location
  Spree::Store.current.default_stock_location
end

#descriptive_name ⇒ String

Returns the descriptive name of the variant.

Returns:

  • (String) —

    the descriptive name of the variant



289
290
291
 
# File 'app/models/spree/variant.rb', line 289

def descriptive_name
  is_master? ? name + ' - Master' : name + ' - ' + options_text
end

#digital? ⇒ Boolean

Is this variant purely digital? (no physical product)

Returns:



675
676
677
 
# File 'app/models/spree/variant.rb', line 675

def digital?
  product.digital?
end

#dimension ⇒ Object 



650
651
652
 
# File 'app/models/spree/variant.rb', line 650

def dimension
  (width || 0) + (height || 0) + (depth || 0)
end

#discontinue! ⇒ Object 



660
661
662
 
# File 'app/models/spree/variant.rb', line 660

def discontinue!
  update_attribute(:discontinue_on, Time.current)
end

#discontinued? ⇒ Boolean

Returns:



664
665
666
 
# File 'app/models/spree/variant.rb', line 664

def discontinued?
  !!discontinue_on && discontinue_on <= Time.current
end

#exchange_name ⇒ String

Returns the exchange name of the variant.

Returns:

  • (String) —

    the exchange name of the variant



283
284
285
 
# File 'app/models/spree/variant.rb', line 283

def exchange_name
  is_master? ? name : options_text
end

#find_option_value(opt_name) ⇒ Spree::OptionValue

Returns the option value for the given option name.

Parameters:

  • opt_name (String) —

    the option name to get the option value for

Returns:



434
435
436
 
# File 'app/models/spree/variant.rb', line 434

def find_option_value(opt_name)
  option_values.includes(:option_type).detect { |o| o.option_type.name.parameterize == opt_name.parameterize }
end

#gallery_media ⇒ ActiveRecord::Relation

Returns the variant’s media gallery. Prefers product-level media linked via variant_media (5.5+) — these reuse a single blob across variants. Falls back to direct variant images for legacy uploads.

Returns:

  • (ActiveRecord::Relation) 


298
299
300
301
302
 
# File 'app/models/spree/variant.rb', line 298

def gallery_media
  return associated_media if has_associated_media?

  images
end

#has_associated_media? ⇒ Boolean

Returns true if any product-level media is linked to this variant.

Returns:

  • (Boolean) —

    true if any product-level media is linked to this variant



317
318
319
320
321
 
# File 'app/models/spree/variant.rb', line 317

def has_associated_media?
  return variant_media.any? if variant_media.loaded?

  variant_media.exists?
end

#has_media? ⇒ Boolean Also known as: has_images?

Returns true if the variant has media (linked product-level or direct images). Uses loaded associations when available, otherwise falls back to counter cache.

Returns:



307
308
309
310
311
312
 
# File 'app/models/spree/variant.rb', line 307

def has_media?
  return true if has_associated_media?
  return images.any? if images.loaded?

  media_count.positive?
end

#human_name ⇒ String

Returns the human name of the variant.

Returns:

  • (String) —

    the human name of the variant



227
228
229
230
231
232
233
 
# File 'app/models/spree/variant.rb', line 227

def human_name
  @human_name ||= option_values.
                  joins(option_type: :product_option_types).
                  merge(product.product_option_types).
                  reorder('spree_product_option_types.position').
                  pluck(:presentation).join('/')
end

#in_stock? ⇒ Boolean

Returns true if the variant is in stock.

Returns:

  • (Boolean) —

    true if the variant is in stock



618
619
620
 
# File 'app/models/spree/variant.rb', line 618

def in_stock?
  @in_stock ||= total_on_hand.positive?
end

#in_stock_or_backorderable? ⇒ Boolean

Returns true if the variant is in stock or backorderable.

Returns:

  • (Boolean) —

    true if the variant is in stock or backorderable



243
244
245
 
# File 'app/models/spree/variant.rb', line 243

def in_stock_or_backorderable?
  self.class.in_stock_or_backorderable.exists?(id: id)
end

#on_sale?(currency) ⇒ Boolean

Returns:



628
629
630
 
# File 'app/models/spree/variant.rb', line 628

def on_sale?(currency)
  @on_sale ||= price_in(currency)&.discounted?
end

#option_value(option_type) ⇒ String

Returns the presentation of the option value for the given option type.

Parameters:

Returns:

  • (String) —

    the presentation of the option value for the given option type



441
442
443
444
445
446
447
 
# File 'app/models/spree/variant.rb', line 441

def option_value(option_type)
  if option_type.is_a?(Spree::OptionType)
    option_values.detect { |o| o.option_type_id == option_type.id }.try(:presentation)
  else
    find_option_value(option_type).try(:presentation)
  end
end

#options ⇒ Array<Hash>

Returns an array of hashes with the option type name, value and presentation

Returns:

  • (Array<Hash>) 


360
361
362
363
364
365
366
367
368
369
370
371
372
 
# File 'app/models/spree/variant.rb', line 360

def options
  @options ||= option_values.
               includes(option_type: :product_option_types).
               merge(product.product_option_types).
               reorder('spree_product_option_types.position').
               map do |option_value|
                 {
                   name: option_value.option_type.name,
                   value: option_value.name,
                   presentation: option_value.presentation
                 }
               end
end

#options=(options = {}) ⇒ void

This method returns an undefined value.

Sets the option values for the variant

Parameters:

  • options (Array<Hash>) (defaults to: {}) —

    the options to set



377
378
379
380
381
382
383
384
385
386
387
388
 
# File 'app/models/spree/variant.rb', line 377

def options=(options = {})
  if product.nil?
    @pending_options = options
    return
  end

  options.each do |option|
    next if option[:name].blank? || option[:value].blank?

    set_option_value(option[:name], option[:value], option[:position])
  end
end

#options_text ⇒ String

Returns the options text of the variant.

Returns:

  • (String) —

    the options text of the variant



269
270
271
272
273
274
275
276
277
278
279
 
# File 'app/models/spree/variant.rb', line 269

def options_text
  @options_text ||= if option_values.loaded?
                      option_values.sort_by do |ov|
                        ov.option_type.position
                      end.map { |ov| "#{ov.option_type.presentation}: #{ov.presentation}" }.to_sentence(words_connector: ', ', two_words_connector: ', ')
                    else
                      option_values.includes(:option_type).joins(:option_type).order("#{Spree::OptionType.table_name}.position").map do |ov|
                        "#{ov.option_type.presentation}: #{ov.presentation}"
                      end.to_sentence(words_connector: ', ', two_words_connector: ', ')
                    end
end

#price_for(context_or_options) ⇒ Spree::Price

Returns the price for the given context or options.

Parameters:

Returns:

  • (Spree::Price) —

    the price for the given context or options



551
552
553
554
555
556
557
558
559
560
561
 
# File 'app/models/spree/variant.rb', line 551

def price_for(context_or_options)
  context = if context_or_options.is_a?(Spree::Pricing::Context)
              context_or_options
            elsif context_or_options.is_a?(Hash)
              Spree::Pricing::Context.new(**context_or_options.merge(variant: self))
            else
              raise ArgumentError, 'Must provide a Pricing::Context or options hash'
            end

  Spree::Pricing::Resolver.new(context).resolve
end

#price_in(currency) ⇒ Spree::Price

Returns the base price (global price, not from a price list) for the given currency. Use price_for(context) when you need to resolve prices including price lists.

Parameters:

  • currency (String) —

    the currency to get the price for

Returns:



453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
 
# File 'app/models/spree/variant.rb', line 453

def price_in(currency)
  currency = currency&.upcase

  price = if prices.loaded? && prices.any?
            prices.detect { |p| p.currency == currency && p.price_list_id.nil? }
          else
            prices.base_prices.find_by(currency: currency)
          end

  if price.nil?
    return Spree::Price.new(
      currency: currency,
      variant_id: id
    )
  end

  price
rescue TypeError
  Spree::Price.new(
    currency: currency,
    variant_id: id
  )
end

#price_modifier_amount(options = {}) ⇒ BigDecimal

Returns the price modifier amount of the variant.

Parameters:

  • options (Hash) (defaults to: {}) —

    the options to get the price modifier amount for

Returns:

  • (BigDecimal) —

    the price modifier amount of the variant



597
598
599
600
601
602
603
604
605
606
607
608
 
# File 'app/models/spree/variant.rb', line 597

def price_modifier_amount(options = {})
  return 0 unless options.present?

  options.keys.map do |key|
    m = "#{key}_price_modifier_amount".to_sym
    if respond_to? m
      send(m, options[key])
    else
      0
    end
  end.sum
end

#price_modifier_amount_in(currency, options = {}) ⇒ Object 



581
582
583
584
585
586
587
588
589
590
591
592
 
# File 'app/models/spree/variant.rb', line 581

def price_modifier_amount_in(currency, options = {})
  return 0 unless options.present?

  options.keys.map do |key|
    m = "#{key}_price_modifier_amount_in".to_sym
    if respond_to? m
      send(m, currency, options[key])
    else
      0
    end
  end.sum
end

#prices=(prices_params) ⇒ void

This method returns an undefined value.

Syncs base prices from an array of hashes. Upserts prices for listed currencies, removes base prices for unlisted currencies. On new records, builds prices in memory (saved when variant is saved). On persisted records, saves prices immediately and removes unlisted currencies. An empty array clears every base price — distinguished from ‘nil` (no change requested), which falls through to the default ActiveRecord setter.

Parameters:

  • prices_params (Array<Hash>, nil) —

    array of { currency:, amount:, compare_at_amount: }



499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
 
# File 'app/models/spree/variant.rb', line 499

def prices=(prices_params)
  return super if prices_params.nil? || prices_params.first.is_a?(Spree::Price)

  currencies_in_payload = []

  prices_params.each do |price_data|
    price_data = price_data.to_h.with_indifferent_access
    currencies_in_payload << price_data[:currency]
    set_price(price_data[:currency], price_data[:amount], price_data[:compare_at_amount])
  end

  # Remove base prices for currencies not in the payload (including the
  # `prices_params == []` case, which clears every base price).
  prices.base_prices.where.not(currency: currencies_in_payload).destroy_all if persisted?
end

#primary_image ⇒ Spree::Image?

Deprecated.

Use #primary_media instead.

Returns first Image for Variant.

Returns:



341
342
343
344
 
# File 'app/models/spree/variant.rb', line 341

def primary_image
  Spree::Deprecation.warn('Spree::Variant#primary_image is deprecated and will be removed in Spree 6.0. Please use Spree::Variant#primary_media instead.')
  primary_media
end

#purchasable? ⇒ Boolean

Returns:



636
637
638
 
# File 'app/models/spree/variant.rb', line 636

def purchasable?
  @purchasable ||= in_stock? || backorderable?
end

#secondary_image ⇒ Spree::Image?

Returns second Image for Variant (for hover effects).

Returns:



348
349
350
 
# File 'app/models/spree/variant.rb', line 348

def secondary_image
  images.second
end

#set_option_value(opt_name, opt_value, opt_type_position = nil) ⇒ void

This method returns an undefined value.

Sets the option value for the given option name.

Parameters:

  • opt_name (String) —

    the option name to set the option value for

  • opt_value (String) —

    the option value to set

  • opt_type_position (Integer) (defaults to: nil) —

    the position of the option type



395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
 
# File 'app/models/spree/variant.rb', line 395

def set_option_value(opt_name, opt_value, opt_type_position = nil)
  # no option values on master
  return if is_master

  option_type = Spree::OptionType.where(name: opt_name.parameterize).first_or_initialize do |o|
    o.name = o.presentation = opt_name
    o.save!
  end

  current_value = find_option_value(opt_name)

  if current_value.nil?
    # then we have to check to make sure that the product has the option type
    product_option_type = if (existing_prod_ot = product.product_option_types.find { |ot| ot.option_type_id == option_type.id })
                            existing_prod_ot
                          else
                            product_option_type = product.product_option_types.new
                            product_option_type.option_type = option_type
                          end
    product_option_type.position = opt_type_position if opt_type_position
    product_option_type.save! if product_option_type.new_record? || product_option_type.changed?
  else
    return if current_value.name.parameterize == opt_value.parameterize

    option_values.delete(current_value)
  end

  option_value = option_type.option_values.where(name: opt_value.parameterize).first_or_initialize do |o|
    o.name = o.presentation = opt_value
    o.save!
  end

  option_values << option_value
  save
end

#set_price(currency, amount, compare_at_amount = nil) ⇒ void

This method returns an undefined value.

Sets the base price (global price, not for a price list) for the given currency.

Parameters:

  • currency (String) —

    the currency to set the price for

  • amount (BigDecimal) —

    the amount to set

  • compare_at_amount (BigDecimal) (defaults to: nil) —

    the compare at amount to set



541
542
543
544
545
546
 
# File 'app/models/spree/variant.rb', line 541

def set_price(currency, amount, compare_at_amount = nil)
  price = prices.base_prices.find_or_initialize_by(currency: currency)
  price.amount = amount
  price.compare_at_amount = compare_at_amount
  price.save! if persisted?
end

#set_stock(count_on_hand, backorderable = nil, stock_location = nil) ⇒ void

This method returns an undefined value.

Sets the stock for the variant at a given location. Mirrors set_price: find-or-initialize, set attrs, save only if persisted.

Parameters:

  • count_on_hand (Integer) —

    the count on hand

  • backorderable (Boolean) (defaults to: nil) —

    the backorderable flag

  • stock_location (Spree::StockLocation) (defaults to: nil) —

    the stock location (defaults to store default)



569
570
571
572
573
574
575
 
# File 'app/models/spree/variant.rb', line 569

def set_stock(count_on_hand, backorderable = nil, stock_location = nil)
  stock_location ||= default_stock_location
  stock_item = stock_items.find_or_initialize_by(stock_location: stock_location)
  stock_item.count_on_hand = count_on_hand
  stock_item.backorderable = backorderable if backorderable.present?
  stock_item.save! if persisted?
end

#should_track_inventory? ⇒ Boolean

Shortcut method to determine if inventory tracking is enabled for this variant This considers both variant tracking flag and site-wide inventory tracking settings

Returns:



642
643
644
 
# File 'app/models/spree/variant.rb', line 642

def should_track_inventory?
  track_inventory? && Spree::Config.track_inventory_levels
end

#stock_items=(stock_items_params) ⇒ void

This method returns an undefined value.

Syncs stock items from an array of hashes. Upserts stock for listed locations, soft-deletes stock items for unlisted locations. On new records, defers to after_create callback.

Parameters:

  • stock_items_params (Array<Hash>) —

    array of { stock_location_id:, count_on_hand:, backorderable: }



520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
 
# File 'app/models/spree/variant.rb', line 520

def stock_items=(stock_items_params)
  return super if stock_items_params.blank? || stock_items_params.first.is_a?(Spree::StockItem)

  location_ids_in_payload = []

  stock_items_params.each do |stock_data|
    stock_data = stock_data.to_h.with_indifferent_access
    location = Spree::StockLocation.find_by_param(stock_data[:stock_location_id])
    location_ids_in_payload << location.id
    set_stock(stock_data[:count_on_hand], stock_data[:backorderable], location)
  end

  # Soft-delete stock items for locations not in the payload
  stock_items.where.not(stock_location_id: location_ids_in_payload).destroy_all if persisted?
end

#tax_category ⇒ Spree::TaxCategory

Returns tax category for Variant

Returns:



249
250
251
252
253
254
255
 
# File 'app/models/spree/variant.rb', line 249

def tax_category
  @tax_category ||= if self[:tax_category_id].nil?
                      product.tax_category
                    else
                      Spree::TaxCategory.find_by(id: self[:tax_category_id]) || product.tax_category
                    end
end

#tax_category_id ⇒ Integer

Returns tax category ID for Variant

Returns:

  • (Integer) 


259
260
261
262
263
264
265
 
# File 'app/models/spree/variant.rb', line 259

def tax_category_id
  @tax_category_id ||= if self[:tax_category_id].nil?
                         product.tax_category_id
                       else
                         self[:tax_category_id]
                       end
end

#update_thumbnail! ⇒ Object

Updates primary_media_id to the first media item by position. Called when media is added, removed, or reordered. Uses gallery_media so product-level assets linked via VariantMedia are considered alongside legacy variant-pinned images.



333
334
335
336
 
# File 'app/models/spree/variant.rb', line 333

def update_thumbnail!
  first_media = gallery_media.first
  update_column(:primary_media_id, first_media&.id)
end

#volume ⇒ Object 



646
647
648
 
# File 'app/models/spree/variant.rb', line 646

def volume
  (width || 0) * (height || 0) * (depth || 0)
end

#weight_unit ⇒ String

Returns the weight unit for the variant

Returns:

  • (String) 


656
657
658
 
# File 'app/models/spree/variant.rb', line 656

def weight_unit
  attributes['weight_unit'] || Spree::Store.default.preferred_weight_unit
end

#with_digital_assets? ⇒ Boolean

Returns:



679
680
681
 
# File 'app/models/spree/variant.rb', line 679

def with_digital_assets?
  digitals.any?
end