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.
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 Product class, then this would cause Spree’s Product 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 Product, Variant and ProductsController are now Spree::Product, Spree::Variant and Spree::ProductsController. Other classes, such as RedirectLegacyProductUrl, have undergone one more level of namespacing to more clearly represent what areas of Spree they are from. This class is now called Spree::Core::RedirectLegacyProductUrl.
Constants such as SpreeCore and SpreeAuth are now Spree::Core and Spree::Auth respectively.
Referencing Spree routes
In previous versions of Spree, due to the lack of namespacing, it was possible to reference routing helpers such as product_url as-is in the controllers and views of your application and send them to the ProductsController for Spree.
Due to the namespacing changes, these references must now be called on the spree routing proxy, so that Rails will route to Spree’s product_url, rather than a potential product_url 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 main_app 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 rails g spree:install is run inside an application, it will install Spree, mounting the Spree::Core::Engine component by inserting this line automatically into config/routes.rb:
mount Spree::Core::Engine, at: "/"
By default, all Spree routes will be available at the root of your domain. For example, if your domain is http://shop.com, Spree’s /products URL will be available at http://shop.com/products.
You can customize this simply by changing the :at specification in config/routes.rb 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 my_store $ 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.
gem 'spree' # add to your Gemfile after the Spree gem gem 'spree_gateway'
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 config/application.rb within a host application are now deprecated. When upgrading to Spree 1.0 you must remove these two lines from config/application.rb:
config.middleware.use "SeoAssist" config.middleware.use "RedirectLegacyProductUrl"
These two pieces of middleware are now automatically included by the
master_price, master_price=, variants?, variant are now officially retired. Please use Spree::Product#price, Spree::Product#price=, Spree::Product#has_variants? and Spree::Product#master respectively instead.
stylesheet_tags 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.
- Gateway.current is now deprecated. Use order.payment_method.gateway now. #747
Calculator::PriceBucket is now renamed to Calculator::PriceSack
The PriceBucket contains Bucket keyword that conflicts with AWS::S3 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 PriceSack.
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.
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.
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.
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.
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.
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
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
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
at: '/' as shown below.
#config/routes.rb YourStore::Application.routes.draw do mount Spree::Core::Engine, at: '/' # your application's custom routes … end
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 :at option to something different, such as at: ‘/shop’.
Remove the following two lines from config/application.rb in your application:
config.middleware.use "SeoAssist" config.middleware.use "RedirectLegacyProductUrl"
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:
config.middleware.delete "Spree::Core::Middleware::SeoAssist" config.middleware.delete "Spree::Core::Middleware::RedirectLegacyProductUrl"
$ 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 Product becomes Spree::Product, Country becomes Spree::Country, 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 &:upcase syntax inside the tab helper provided by Admin::NavigationHelper. #693 and #704.
- Fixed issue where non-ASCII characters were not being correctly titleized in the tab helper provided by Admin::NavigationHelper. #722
- When Thinking Sphinx was being used, a conflict would occur with its Scopes module and the one inside Spree. #740
- Added script/rails to core to allow things such as rails generate and rails console to be used. commit b0903ea
- Performance improvements for the best_selling_variants and top_grossing_variants methods in Admin::OverviewController. #718
- If an admin user already exists, rake db:admin:create will now ask if you want to override. #752
- Making a request to a URL such as /admin/products/non-existant/edit no longer shows a status 500 page. #538
- rails g spree:install output is now not so excessive. commit ca4db30
- The Spree::Core::Engine is automatically mounted inside your application when you run rails g spree:install. commit ba67b51
- Product on_hand 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 bundle exec rake test_app performance. commit 6a2d367
- Improved permalink code, removed reliance on the rd-find_by_param 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 ffaker gem is now used in favor of the faker gem. #826
- Spree::Config.set should no longer be used, please use Spree.config with a block: commit 5590fb3 #801
- Fix calculator dropdown bug for creating a shipping method in the admin interface. #825
- Fix escaping of order_subtotal in view. #852