Model Preferences

Model preferences allow you to easily extend Spree models with configuration options. Thanks to this you can store useful information on Spree models, eg.

user.preferred_language = "English"
user.save

Defining Model Preferences

To define a model preference, you need to add them to your model class. Make sure to generate a migration to add the preferences column to the table. This column will store the preferences in a serialized format.

spree generate migration AddPreferencesToSpreeUsers preferences:text

bin/rails g migration AddPreferencesToSpreeUsers preferences:text

Run the migration.

spree migrate

bin/rails db:migrate

class Spree::User < ApplicationRecord
  # ... you existing code ...

  # include the preferable module
  include Spree::Preferences::Preferable
  # define the preferences
  preference :language, :string, default: "English"
  preference :sms_marketing, :boolean, default: false
end

This will add a language preference to the User model. The preference will be stored in the newly created preferences column of the spree_users table. You can add more preferences to the model in the same way.

Accessing Model Preferences

Once preferences have been defined for a model, they can be accessed either using the shortcut methods that are generated for each preference or the generic methods that are not specific to a particular preference.

Shortcut Methods

There are several shortcut methods that are generated. They are shown below. Query methods:

user.prefers_sms_marketing? # => false

Reader methods:

user.preferred_sms_marketing      # => false
user.preferred_language   # => "English"

Writer methods:

user.prefers_sms_marketing = false         # => false
user.preferred_language = "English"    # => "English"

Remember to run user.save after setting the preference value to save the changes to the database.

Check if a preference is available:

user.has_preference? :sms_marketing

Generic Methods

Each shortcut method is essentially a wrapper for the various generic methods shown below: Query method:

user.prefers?(:sms_marketing)       # => false
user.prefers?(:language)  # => false

Reader methods:

user.preferred(:sms_marketing)      # => false
user.preferred(:language)   # => "English"

user.get_preference :sms_marketing
user.get_preference :language

Writer method:

user.set_preference(:sms_marketing, false)     # => false
user.set_preference(:language, "English")  # => "English"

Accessing All Preferences

You can get a hash of all stored preferences by accessing the preferences helper:

user.preferences # => {"language"=>"English", "sms_marketing"=>false}

This hash will contain the value for every preference that has been defined for the model instance, whether the value is the default or one that has been previously stored.

Models with preferences

The following Spree models already have preferences defined:

Spree::Calculator
Spree::Gateway
Spree::PageBlock
Spree::PageSection
Spree::Page
Spree::PaymentMethod
Spree::PromotionRule
Spree::Store
Spree::Theme

Tutorial

Admin Panel

Customization Reference

Defining Model Preferences

Accessing Model Preferences

Shortcut Methods

Generic Methods

Accessing All Preferences

Models with preferences

​Defining Model Preferences

​Accessing Model Preferences

​Shortcut Methods

​Generic Methods

​Accessing All Preferences

​Models with preferences

Defining Model Preferences

Accessing Model Preferences

Shortcut Methods

Generic Methods

Accessing All Preferences

Models with preferences