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.
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'
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 spreebluesass_theme to collect feedbacks before we could come up with a decision to opt for SCSS/SASS in future version of Spree.
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.
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.
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). !!! 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. ```bash 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 ```bash $ 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.
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. !!!
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'])
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 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.
Also ensure the following line is not present in config/application.rb:
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 Running the `spree:site` generator will create the skeleton structure for the asset pipeline, and also copy missing migrations. ```bash 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`: ```ruby config.middleware.use "RedirectLegacyProductUrl" config.middleware.use "SeoAssist"
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. !!!
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.
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 Adjustments guide.