Spree 1.0 Release Notes
This is the official 1.0 Release of Spree. This is a major release for Spree, and so backwards compatibility with extensions and applications is not guaranteed. Please consult the extension registry to see which extensions are compatiable with this release. If your extension is not yet compatible you should check back periodically since the community will be upgrading various extensions over time.
WARNING: If you are upgrading from older versions of Spree you should perform a complete backup of your database before attempting. It is also recommended that you perform a test upgrade on a local development or staging server before attempting in your production environment.
A difficulty in previous versions of Spree was using it with existing applications, as there may have been conflicting class names between the Spree engines and the host application. For example, if the host application had a class, then this would cause Spree’s class to not load and issues would be encountered.
A major change within the 1.0 Release is the namespacing of all classes within Spree. This change remedies the above problem in the cleanest fashion possible.
Classes such as , and are now , and . Other classes, such as , have undergone one more level of namespacing to more clearly represent what areas of Spree they are from. This class is now called .
Constants such as and are now and respectively.
Referencing Spree routes
In previous versions of Spree, due to the lack of namespacing, it was possible to reference routing helpers such as as-is in the controllers and views of your application and send them to the for Spree.
Due to the namespacing changes, these references must now be called on the routing proxy, so that Rails will route to Spree’s , rather than a potential within an application. Routing helpers referencing Spree parts must now be written like this:
Conversely, to reference routes from the main application within a controller, view or template from Spree, you must use the routing proxy like this:
If you encounter errors where routing methods you think should be there are not available, ensure that you aren’t trying to call a Spree route from the main application within the proxy prefix, or a main application route from Spree without the proxy as well.
Mounting the Spree engine
When is run inside an application, it will install Spree, mounting the component by inserting this line automatically into :
mount Spree::Core::Engine, :at => “/”
You can customize this simply by changing the specification in to be something else. For example, if your domain is http://bobsite.com and you would like Spree to be mounted at /shop, you can write this:
mount Spree::Core::Engine, :at => “/shop”
The different parts of Spree (Auth, API, Dash & Promo) all extend the Core’s routes, and so they will be mounted as well if they are available as gems.
The admin dashboard has been replaced with Spree Analytics. This new service will provide deep insight
into your store’s ecommerce performance and sales conversion funnel.
You will have to register your store with Spree Commerce. Then configure the Analytics Add On to generate your token. The token should be entered on the Admin Overview page.
The original dashboard has been extracted into the spree_dash gem .
Command line tool
We have moved the ‘spree’ command line tool to its own gem. This is the new recommended way for adding Spree to an existing Rails application. The tool will add the Spree gem, copy migrations, initializers and generate sample data.
To add Spree to a Rails application you do the following:
$ gem install spree
$ rails new my_store
$ cd mystore
$ spree install
The extension generator has also been moved to this new tool.
$ gem install spree
$ spree extension my_ext
Default Payment Gateways
The new Spree Command Line Tool prompts you to install the default gateways. This adds the spree_skrill and spree_usa_epay gems. These are the Spree Commerce supported gateways for stores in the United States (USA ePay) and Internationally (Skrill formally Moneybookers).$ rails new my_store $ spree install my_store Would you like to install the default gateways? (yes/no) [yes]
We have moved all the gateways out of core (except bogus) to the Spree Gateway Gem. You can add this gem to your Gemfile if you need one
of those gateways.
- add to your Gemfile after the Spree gem
The gateways available in the Spree Gateway Gem are community supported. These include Authorize.net, Stripe and Braintree and many other contributed gateways.
We have refactored Spree Preferences to improve performance and simplify
code for applications and extensions. The previous interfaces have been
maintained so no code changes should be required. The underlying classes
have been completely rewritten.
Please see the Spree blog for
notes on this release.
The lines for middleware in within a host application are now deprecated. When upgrading to Spree 1.0 you must remove these two lines from :
These two pieces of middleware are now automatically included by the `Spree::Core::Engine`.
, , , are now officially retired. Please use , , and respectively instead.
and are removed in favor for the Rails 3.1 Asset Pipeline. See the Asset Customization for more information.
Extensions looking to add stylesheets to the application should do so through the Asset Pipeline by making the extension an engine.
- is now deprecated. Use now. #747
Calculator::PriceBucket is now renamed to Calculator::PriceSack
The contains Bucket keyword that conflicts with library which has caused few issues with Heroku deployment. If you used this calculator in your application, then you will need to rename it to .
There have been several major changes to how Spree handles tax calculations. If you are migrating from an older version of Spree your previous tax configurations will not function properly and will need to be reconfigured before you can resume processing orders.
WARNING: Be sure to backup your database before migrating. Your tax configuration will likely break after upgrading. You have been warned.
Zone#match now only returns the best possible match.
Previously the method would return an array of zones as long as the zone included the address. Now only the narrowest match is returned.
Will return the zone to be used for computing tax on the order. Returns the best possible zone match given the order address. In the absence of an order address it will return the default tax zone (if one is specified.)
Adjustments are now polymorphic
Adjustment class belonged to just
Order. Now the
LineItem class can have adjustments as well. This allows Spree to store the amount of tax included in the price when prices include tax (such as VAT case.)
Convenience method for listing all of the price adjustments in the order. Price adjustments are tax calculations equivalent to the amount of tax included in a price. These adjustments are not counted against the order total but are sometimes useful for reporting purposes.
NOTE: You don’t need to worry about price adjustments unless your prices include tax (such as the case with Value Added Tax.)
Convenient method for show the price adjustment totals grouped by similar tax categories and rates.
Prior to this version of Spree there were several helpers designed to show prices including tax before Spree was changed so that prices were expected to already include tax (when applicable.) We’ve removed a lot of stuff related to the old (more complicated) way of doing things.
WARNING: One unfortunate byproduct of prices now including tax is that you will need to change the prices on your products if you are in a region that requires prices to include tax and you were not already including the tax in your prices.
Removed sales tax and VAT calculators
Both of these calculators have been replaced by the single calculator
Tax rates can now be included in a product price
There is now a boolean checkbox for indiciating if a tax rate is included in the product price. The tax rate will only be considered as part of the product price if the product has a matching tax category. You can also have multiple tax rates with this designation.
This method is responsible for calculating the price. This is basically an internal change but some developers may be interested to know this.
INFO: Marking a tax rate as including price is the new way to handle Value Added Tax (VAT) and other similar tax schemes.
There is one major change related to zones in this release. Zones can no longer have zone members that are themselves a zone. All zone members must now be a either a country or state.
The demise of Cucumber testing
Cucumber is a great testing tool however it doesn’t bring more values for testing but overhead. It is decided to opt for a light-weight practice of RSpec + Capybara.
This section aims to walk you through upgrading to the newest version of Spree.
INFO: This steps in this guide were written while upgrading from 0.70.x to 1.0.0. Upgrading older versions of Spree may require some additional steps.
Upgrading the Spree Gem
You will want to begin the update process by updating the Spree gem in your Gemfile to reference version 1.0.0.
gem ‘spree’, ‘1.0.0’
Next, you will need to update this gem using this command:
$ bundle update spree
NOTE: If you run `bundle update` instead of `bundle update spree`, you run the risk of having all your application dependencies updated to their latest version. It is recommended to only update spree during the upgrade process.
Any Spree extensions being used will also need to be updated to a 1.0.0 compatible version. If there is not a 1.0.0 compatible extensions release yet, you will need to disable that extension in order to continue the upgrade process.
You will need to update your routes file in order for Spree’s routes to be correctly loaded. You will need to add `mount Spree::Core::Engine, :at => ‘/’` as shown below.
mount Spree::Core::Engine, :at => ‘/’
- your application’s custom routes
If you’re mounting Spree at the default root path, it is recommended to place your application’s custom routes beneath Spree’s mounted routes as shown in the above example. This will ensure you don’t override any of Spree’s defined routes.
You may choose to mount Spree at a custom location by changing the option to something different, such as .
Remove the following two lines from config/application.rb in your application:
These two pieces of middleware are now automatically included by Spree. If you have no desire to use these pieces of middleware, you can now remove them by placing these two lines into your config/application.rb:
$ bundle exec rake railties:install:migrations
Run the above command to copy over all the migrations from all the engines included in your application. This may also include any migrations from extensions or other engines.
Then it is time to run any new migrations copied to your application.
$ bundle exec rake db:migrate
Asset Manifest Files
Other Tips for Upgrading
- If your application defines any class decorators, you will need to update these files to decorate Spree’s new namespace classes. This means becomes , becomes , and so on.
- Correct the paths to any templates you are overriding to include the Spree namespace. Things such as app/views/products/show.html.erb have now become app/views/spree/products/show.html.erb.
- Fixed issue caused by using syntax inside the helper provided by . #693 and #704.
- Fixed issue where non-ASCII characters were not being correctly titleized in the helper provided by . #722"
- When Thinking Sphinx was being used, a conflict would occur with its module and the one inside Spree. #740
- Added to core to allow things such as and to be used. commit b0903ea
- Performance improvements for the and methods in . #718
- If an admin user already exists, will now ask if you want to override. #752
- Making a request to a URL such as no longer shows a status 500 page. #538
- output is now not so excessive. commit ca4db30
- The is automatically mounted inside your application when you run . commit ba67b51
- Product now takes all variants into account. #772
- The translation for “Listing Products” in admin/products now is more easily translatable into different languages. commit c0d5cb5
- Removed POSIX-only system calls, replaced with Ruby calls instead to enable Windows compatibility. #711 and commit ce00172"
- Improved performance. commit 6a2d367
- Improved permalink code, removed reliance on the gem. #444 and #847
- Master variant is now deleted when a product is deleted. Performance with this action has also been improved. #801
- An invalid coupon code on the payment screen will now show an error. #717
- Products are now restocked when an order is canceled, and unstocked when the order is resumed. #729
- The gem is now used in favor of the gem. #826
- should no longer be used, please use with a block: commit 5590fb3 #801
- Fix calculator dropdown bug for creating a shipping method in the admin interface. #825
- Fix escaping of in view. #852