Summary

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.

Namespacing

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:

spree.product_url

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:

main_app.root_url

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.

Spree Analytics

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.

Preferences

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.

Deprecated functions

Middleware

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 Spree::Core::Engine.

Product

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.

Spree::Config[:stylesheets]

Spree::Config and 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.

General deprecations

• Gateway.current is now deprecated. Use order.payment_method.gateway now. #747

Calculator

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.

Taxation

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.

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.

New Order#tax_zone method

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

Previously the 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.)

New Order#price_adjustments method

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.

New Order#price_adjustment_totals method

Convenient method for show the price adjustment totals grouped by similar tax categories and rates.

Removed helpers and javascript related to VAT

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.

Removed sales tax and VAT calculators

Both of these calculators have been replaced by the single calculator Calculator::DefaultTax.

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.

New TaxRate#adjust method

This method is responsible for calculating the price. This is basically an internal change but some developers may be interested to know this.

Zones

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.

Testing

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.

Upgrading

This section aims to walk you through upgrading to the newest version of Spree.

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

Extensions

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.

Routes

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.

#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’.

Update config/application.rb

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"

Migrations

$ 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

Remove the line requiring spree_dash from app/assets/stylesheets/store/all.css, app/assets/stylesheets/admin/all.css, app/assets/javascripts/store/all.js, and app/assets/javascripts/store/all.js

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.

Bug fixes

• 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