Summary

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.

Theming Improvments

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.
• Asset Customization - explains how Spree uses Rails’ new asset pipeline, and how you can use it to customize the stylesheets, javascripts and images provided by Spree.

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 screen.css.

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

One of the more interesting new features included in Rails 3.1 is the asset pipeline, and a lot of the customization improvements in Spree are enabled by this feature. While the asset pipeline provides excellent flexibility and improved organization for all of Spree’s assets (images, javascripts and stylesheets) it does add a significant overhead as all asset requests are now being handled by Rails itself (and not being handed off to the web server).

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.

Rack::Cache is generally sufficient for lower traffic sites, but pre-compiling will provide some additional speed increases by allowing the web server to serve all assets, including gzipped versions of javascript and css files.

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 Rails).

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 your .gitignore file.

Promotions

Promotions have been extended well beyond their coupon roots to include new 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.

Upgrade Instructions

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.

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.

Gemfile changes

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

Update config/boot.rb

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/environments/development.rb.

config.action_view.debug_rjs = true

Retire lib/spree_site.rb

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 config.to_prepare block.

Remove spree_site from config/application.rb

Also ensure the following line is not present in config/application.rb:

require 'spree_site'

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 dependencies

Install all the required gems, and lock your dependencies by running:

    $ bundle update

Generate & copy required files

Running the 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/application.rb:

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.

$ 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 specific assets (javascript, stylesheets and images) from all of Spree’s (and all those belonging to all the extensions installed) which have been mingled together in your public directory.

Asset Organization

Assets should be placed inside your application in one of three locations: app/assets, lib/assets or vendor/assets.

app/assets is for assets that are owned by the application, such as custom images, JavaScript files or stylesheets.

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 across applications.

vendor/assets is for assets that are owned by outside entities, such as code for JavaScript plugins.

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 /public/assets.

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 config/application.rb

require ‘lib/site_hooks’

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.