This 0.70.0 release is the first Spree release to support Rails 3.1 and contains several exciting new features including a complete overhaul of the theming system and major improvements to the Promotions system.
We’re always looking for more help with the Spree documentation. If you’d like to offer assistance please contact us on the spree-user mailing list and we can give you commit access to the documentation project.
Theming support in this release has change significantly and all the new features are covered in detail in the following guides:
- Customization Overview - provides a high level introduction to all the customization and theming options now provided by Spree.
- View Customization - introduces and explains how to use Deface to customize Spree’s views.
While the upgrade instructions that follow briefly cover the new asset pipeline features we suggest you review the guides above as part of your upgrade preparation.
Themes as engines
In previous versions (0.11.x and earlier) Spree encouraged the approach of bundling themes in their own extensions, with the advent of the asset pipeline in Rails 3.1 and the upcoming Theme Editor we’re bringing back this approach as a suitable model for distributing and sharing themes.
While the distinction between themes and extensions is covered in the Extensions & Themes guide they are both just Rails engines and can be treated as such.
We’ve created two front-end themes to help show this new approach in action:
Spree Blue - Recreates the original “blue” theme of 0.60.x as a stand alone theme.
Rails Dog Radio - This recreates some of the aspects of the Rails Dog Radio demo application for a default Spree application.
Both themes can be installed by just adding a reference to the git repository to your Gemfile, ie:
gem 'spree_blue_theme', :git => 'git://github.com/spree/spree_blue_theme.git'
Experimental SCSS/SASS Theme
LESS proves to be unpopular amongst Spree developers so it is decided to
retire LESS stylesheets of
spree_blue_theme in favor for all-in-one
Yet with the recently adopted SCSS/SASS in Rails 3.1, we believe this technology could become de-facto standard for CSS someday. Thus, we create the experimental SCSS/SASS version of spree_blue_sass_theme to collect feedbacks before we could come up with a decision to opt for SCSS/SASS in future version of Spree.
The Asset Pipeline
This can be especially noticeable in development mode when using a single process application server like Webrick. This release of Spree includes a small tweak to the standard pre-compiling rake task that allows pre-compiling of assets for development mode.
Pre-compiling in production
Rails supports pre-compiling of assets which is intended to offload the overhead of generating and serving assets from the application server in production environments.
Pre-compiling is not required for the asset pipeline to function correctly in production, if you choose to not pre-compile Rails will generate each asset only once and serve each subsequent request using Rack::Cache.
To pre-compile assets for production you would normally execute the following rake task (on the production server).
$ bundle exec rake assets:precompile
This would write all the assets to the
public/assets directory while
including an MD5 fingerprint in the filename for added caching benefits.
Pre-compiling for development
Spree alters the behaviour of the precompile rake task as follows:
$ bundle exec rake assets:precompile:nondigest
It will still output the assets to
public/assets but it will not
include the MD5 fingerprint in the filename, hence the files will be
served in development directly by the web server (and not processed by
Using the precompile rake task in development will prevent any changes to asset files from being automatically included in when you reload the page. You must re-run the precompile task for changes to become available.
Rail’s also provides the following rake task that will delete the entire
public/assets directory, this can be helpful to clear out development
assets before committing.
$ bundle exec rake assets:clean
It might also be worthwhile to include the
public/assets directory in
Promotions have been extended well beyond their coupon roots to include
activator support, which can now fire or activate a promotion for
a variety of different user triggered events, including:
- Adding items to a cart
- Visiting specific pages
- Adjusting cart contents
- Using a coupon code
Promotions also includes a new
Actions feature which can perform an
action as a result of a promotion being actived, these actions currently
include creating an adjustment or adding additional items to a cart.
For more details on these new promotions feature please refer to the Promotions guide.
New Extension Generator
There is a new extension generator available as part of this release. The generator is utilized by a new executable contained within the gem.
You can generate new extensions inside an existing rails application or as a standalone git repository using the following command
$ spree extension foofah
One of the most important advances in this new generator is that you can now easily run specs for extensions in their own standalone repository. You just need to create a test application (one time only) as a context before running your specs.
$ bundle exec rake test_app $ bundle exec rspec spec
You can get more information on the extension generator in the Creating Extensions guide.
You must install the spree gem in order to use the new extension generator.
These instructions are mainly concerned with upgrading Spree applications, extension developers should jump straight to the “Asset Customization”asset_customization.html and View Customization guides for details on the changes that are required for extensions to fulling support 0.70.0.
Before you begin
To prevent problems later please ensure that you’ve copied all the migrations from your current version of Spree and all the extensions that you are running. While this is normal practice when setting up Spree and extensions any missing migrations will cause issues later in the upgrade process.
You can check that all Spree migrations are copied by running:
$ bundle exec rake spree:install:migrations
Each extension will provide it’s own rake task (or generator) for copying migrations so please refer to the extensions README for instructions.
It’s vital that you confirm this first before starting the upgrade process as Rails 3.1 has altered how engine migrations are handled and incorrectly copying migrations later could result in data loss.
Changes required for Rails 3.1
Most of the changes required to upgrade a Spree application to 0.70.0 is same for any Rails 3.0.x application upgrading to 3.1.
You’ll need to make several additions and changes to your Gemfile:
- Update spree to 0.70.0
- Update rails to 3.1.1
- Update mysql2 to 0.3.6 - if your using it.
- Ensure the assets group is present:
group :assets do gem 'sass-rails', "~> 3.1.1" gem 'coffee-rails', "~> 3.1.1" gem 'uglifier' end
Rails 3.1 simplifies the
config/boot.rb file significantly, so update
yours to match:
require 'rubygems' # Set up gems listed in the Gemfile. ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', *FILE*) require 'bundler/setup' if File.exists?(ENV['BUNDLE_GEMFILE'])
Enable the asset pipeline
Add the following line to
config/application.rb, this will enable the
Asset Pipeline feature (required by 0.70.0):
config.assets.enabled = true
Remove deprecated configuration
Remove the following line from
config.action_view.debug_rjs = true
The spree_site.rb file is no longer required so it’s important to migrate any existing code out of this file and into the correct location.
- Model, controller or helper evals should be relocated to a suitable _decorator.rb file.
- Configuration settings should be moved to initializers.
- If you are activating custom Abilities or Calculators, you should
remove then for now. You can re-add them to config/application.rb
after you’ve ran the spree:site generator below. They will need to
be inside the
The decorator initialization block will be automatically included in config/application.rb for you, when you run the spree:site generator below.
Remove spree_site from config/application.rb
Also ensure the following line is not present in config/application.rb:
Update gems & generate Spree files
Once you’ve completed all the Rails 3.1 steps above, you can now update your dependencies and start generating the new asset pipeline placeholders.
Install all the required gems, and lock your dependencies by running:
$ bundle update
Generate & copy required files
spree:site generator will create the skeleton structure
for the asset pipeline, and also copy missing migrations.
$ rails g spree:site
After running the generator above, it’s best to check to make sure you
do not have multiple copies of the following line, in
config.middleware.use "RedirectLegacyProductUrl" config.middleware.use "SeoAssist"
Update your database
If you encounter any issues with this step please ensure you’ve completed the Before you begin section above.
Make sure you’ve taken a backup of the database before attempting this step.
$ bundle exec rake db:migrate
Migrating your assets
Cleaning up your
/public directory is one major advantage of using
Rails 3.1. The main task required here is to separate your application
(and all those belonging to all the extensions installed) which have
been mingled together in your public directory.
Assets should be placed inside your application in one of three
app/assets is for assets that are owned by the application, such as
lib/assets is for your own libraries’ code that doesn’t really fit
into the scope of the application or those libraries which are shared
vendor/assets is for assets that are owned by outside entities, such
For a full explanation of how Spree uses Rails’ asset pipeline and how to update your site to use these new features please refer to the Asset Customization guide.
Cleaning up /public
Once you’ve relocated all your applications assets, the only
remaining directories and files in
/public should be images that
you’ve uploaded for your Products (or taxonomies). If you are using the
default Spree configuration these will be in
directory will override those provided by Spree or it’s extensions. So
it’s vital that you delete all remaining files from the
directory, EXCEPT YOUR PRODUCT IMAGES!.
If you are using S3 (or another cloud storage system) for your
Product images then your
/public directory should be completly empty.
Including old style theming hooks
With the introduction of Deface the old style theming hooks have been deprecated, the old hooks will continue to function after the upgrade as they are automatically upgraded to Deface overrides, we strongly suggest you upgrade them as soon as possible.
To include your previously defined old style theming hooks from
lib/site_hooks.rb add the following to the bottom of
The development log will include suggested replacement Deface overrides anytime Rails encounters a old style hook call. These suggestions are a best effort replacement, but might need some tweaks as some elements have been moved while removing the old hook calls from Spree’s view files.
For more information about using Deface overrides, please refer to the View Customization guide.
New way to register Calculators
Calculators no longer can be registered with register method. The register method is refactored to take advantage of default Rails application configuration Rails.application.config.spree.calculators.
For more information about this new change, please refer to the Ajustments guide.