Integrating the Estes Freight Shipping SOAP API as a Spree Shipping Calculator

2021-09-28T00:00:00+00:00

One of our clients with a Spree-based e-commerce site was interested in providing automated shipping quotes to their customers using their freight carrier Estes. After doing some research I found that Estes provided a variety of SOAP APIs and determined a method for extending Spree with custom shipping rate calculators. This presented an interesting challenge to me on several levels: most of my previous API integration experience was with REST, not SOAP APIs, and I had not previously worked on custom shipping calculators for Spree. Fortunately, the Estes SOAP API documentation and some code examples of other Spree shipping calculators were all I needed to create a successful integration of the freight shipping API for this client.

Estes API Documentation

The Estes Rate Quote Web Service API is the one that I relied on for being able to generate shipping quotes based on a combination of source address, destination address, and package weight. I found the developer documentation to be thorough and helpful, and was able to create working client code to send a request and receive a response relatively quickly. Many optional fields can be provided when making requests but I found that I only needed to use a small subset of these, as shown in the example code below.

The one aspect of the API that tripped me up a bit was their use of CN as the country code for Canada; Spree and most other codebases I have encountered use the international standard ISO 3166 country codes with CA for Canada, so I had to add a small workaround for that in my client code when requesting shipping quotes to Canadian addresses. Another limitation I encountered is that the API expected to receive only 5-digit US and 6-character Canadian postal codes, so I had to do a bit of manipulation in my shipping calculator to account for that.

Ruby SOAP Client

I researched Ruby SOAP clients and soon found Savon, the “Heavy metal SOAP client”, which proved to be very easy to integrate into my existing Rails/Spree application. I added the savon gem to my project’s Gemfile and I was quickly able to instantiate a Savon client and configure it using the WSDL provided by Estes. After that, most of the integration work involved crafting a valid XML payload for my request and then parsing the response.

Spree Shipping Calculators

The final piece of the puzzle was implementing the Savon client into a Spree shipping calculator class. This process allowed me to retrieve details about the current user’s order and then return the calculated shipping estimates within the context of the Spree checkout pages. Looking at existing shipping calculator code helped set me on the right path here; in the end, it was just a matter of defining a new class that inherited from the base Spree::ShippingCalculator class and then defining the #compute_package method expected by Spree for returning the shipping cost of a given package.

Code Example

# app/models/spree/calculator/shipping/estes_calculator.rb
module Spree::Calculator::Shipping
  # Custom freight shipping rate API integration
  class EstesCalculator < Spree::ShippingCalculator
    ESTES_API_URL = 'https://www.estes-express.com/tools/rating/ratequote/v4.0/services/RateQuoteService?wsdl'.freeze

    def self.description
      'Estes Freight'
    end

    def compute_package(package)
      country_code = package.order.ship_address.country.iso
      return 0 unless country_code.in?(['US', 'CA', 'MX'])

      client = Savon.client(
        filters: %i[user password account],
        log: true,
        log_level: :debug,
        logger: Logger.new(Rails.root.join('log', 'savon.log')),
        pretty_print_xml: true,
        wsdl: ESTES_API_URL
      )

      country_code = 'CN' if country_code == 'CA' # Estes uses CN for Canada
      postal_code = package.order.ship_address.zipcode

      postal_code =
        if country_code == 'CN'
          postal_code.delete(' ').first(6)
        else
          postal_code.first(5)
        end

      xml = <<~XML
        <soapenv:Envelope
            xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
            xmlns:rat="http://ws.estesexpress.com/ratequote"
            xmlns:rat1="http://ws.estesexpress.com/schema/2019/01/ratequote">
          <soapenv:Header>
            <rat:auth>
              <rat:user>#{ENV['ESTES_USER']}</rat:user>
              <rat:password>#{ENV['ESTES_PASSWORD']}</rat:password>
            </rat:auth>
          </soapenv:Header>
          <soapenv:Body>
            <rat1:rateRequest>
              <rat1:requestID>#{package.order.number}</rat1:requestID>
              <rat1:account>#{ENV['ESTES_ACCOUNT']}</rat1:account>
              <rat1:originPoint>
                <rat1:countryCode>US</rat1:countryCode>
                <rat1:postalCode>10001</rat1:postalCode>
              </rat1:originPoint>
              <rat1:destinationPoint>
                <rat1:countryCode>#{country_code}</rat1:countryCode>
                <rat1:postalCode>#{postal_code}</rat1:postalCode>
              </rat1:destinationPoint>
              <rat1:payor>S</rat1:payor>
              <rat1:terms>C</rat1:terms>
              <rat1:baseCommodities>
                <rat1:commodity>
                  <rat1:class>50</rat1:class>
                  <rat1:weight>#{package_weight(package)}</rat1:weight>
                </rat1:commodity>
              </rat1:baseCommodities>
            </rat1:rateRequest>
          </soapenv:Body>
        </soapenv:Envelope>
      XML

      response = client.call(:get_quote, xml: xml)
      quotes = response.body.dig(:rate_quote, :quote_info, :quote)

      if quotes.is_a?(Array)
        quotes.first.dig(:pricing, :total_price).to_f
      elsif quotes.is_a?(Hash)
        quotes.dig(:pricing, :total_price).to_f
      else
        0
      end
    rescue Savon::Error
      # Record shipping rate as 0 if an API error is caught, 0 amount will indicate need to show user an error message on the shipping rate page
      0
    end

    private

    def package_weight(package)
      weight = package.contents.sum { |content| content.line_item.weight }

      if weight < 5 # enforce minimum package weight
        5
      else
        weight.round
      end
    end
  end
end

Conclusion

I was pleased that I was able to quickly build a custom shipping calculator in Spree that used the Estes Rate Quote API to provide accurate shipping estimates for large freight packages. The high quality documentation of the Estes API and the Savon SOAP Client gem made for a pleasant development experience, and the client was happy to gain the new functionality for their Spree store.

wroc_love.rb 2017 part 1

2017-03-18T00:00:00+00:00

wroc_love.rb is a single-track 3-day conference that takes place in Wrocław, Poland, every year in March.

Here’s a subjective list of most interesting talks from the first day:

Kafka / Karafka by Maciej Mensfeld

Karafka is another library that simplifies Apache Kafka usage in Ruby. It lets Ruby on Rails apps benefit from horizontally scalable message busses in a pub-sub (or publisher/consumer) type of network.

Why Kafka is (probably) better message/task broker for your app:

broadcasting is a real power feature of Kafka (HTTP lacks that)
author claims that it’s easier to support than ZeroMQ/RabbitMQ
it’s namespaced with topics (similar to ROS, the Robot Operating System)
great replacement for ruby-kafka and Poseidon

Karafka https://t.co/g9LQZiAV4i microframework to have #rails-like development performance with #kafka in #ruby @maciejmensfeld #wrocloverb

— Maciek Rząsa (@mjrzasa) 17 marzo 2017

Machine Learning to the Rescue by Mariusz Gil

This talk was devoted to Machine Learning success (and failure) story of the author.

Author underlined that Machine Learning is a process and proposed following workflow:

define a problem
gather your data
understand your data
prepare and condition the data
select & run your algorithms
tune algorithms parameters
select final model
validate final model (test using production data)

Mariusz described few ML problems that he has dealt with in the past. One of them was a project designed to estimate cost of a code review. He outlined the process of tuning the input data. Here’s a list of what comprised the input for a code review estimation cost:

number of lines changed
number of files changed
efferent coupling
afferent coupling
number of classes
number of interfaces
inheritance level
number of method calls
LLOC metric (Logical Lines of Code, excluding empty or comment lines)
LCOM metric (Lack of Cohesion between Methods—whether single responsibility pattern is followed or not)

Spree lightning talk by sparksolutions.co

One of the lightning talks was devoted to Spree. Here’s some interesting latest data from the Spree world:

number of contributors to Spree: 700
it’s very modular
it’s API driven
it’s one of the biggest repos on GitHub
very large number of extensions
it drives thousands of stores worldwide
Spark Solutions is a maintainer
Popular companies that use Spree: GoDaddy, Goop, Casper, Bonobos, Littlebits, Greetabl
it support Rails 5, Rails 4.2 and Rails 3.x

Author also released newest 3.2.0 stable version during the talk:

releasing spree 3.2.0 live during lightning talk #wrocloverb pic.twitter.com/9oPcB5CTfB

— Wojciech Ziniewicz (@fribulusxax) 17 marzo 2017

The merchant login ID or password is invalid or the account is inactive, and to how to fix it in Spree

2016-06-02T00:00:00+00:00

Authorize.net has disabled the RC4 cipher suite on their test server. Their production server update will follow soon. So, in order to ensure your, or your client’s, site(s) do not experience any interruption in payment processing it is wise to place a test order in the Authorize.net test environment.

The projects I was testing were all Spree Gem (2.1.x). The Spree Gem uses the ActiveMerchantGem (in Spree 2.1.x it’s ActiveMerchant version 1.34.x). Spree allows you to sign into the admin and select which server your Authorize.net payment method will hit- production or test. There is another option for selecting a “Test Mode” transaction. The difference between a test server transaction and a test mode transaction is explained quite succinctly on the Authorize.net documentation. To summarize it, test server transactions are never sent to financial institutions for processing but are stored in Authorize.net (so you can see their details). Transactions in test mode however are not stored and return a transaction ID of zero.

I wanted to use my Authorize.net test account to ensure my clients were ready for the RC4 cipher suite disablement. I ran across a few strange things. First, for three sites, no matter what I did, I kept getting errors saying my Authorize.net account was either inactive or I was providing the wrong credentials. I signed in to Authorize.net and verified my account was active. I triple checked the credentials, they were right. So, I re-read the Spree docs thinking that perhaps I needed to use a special word or format to actually use the test server (“test” versus “Test” or something like that).

Below is a screenshot of the test payment method I had created and was trying to use.

Since I kept getting errors I looked through the Spree code, then the ActiveMerchant Gem that Spree is using.

Below, you can see that the ActiveMerchant is deciding which URL to use (test or live) based on the value of test? (line 15).

active_merchant/lib/active_merchant/billing/gateways/authorize_net.rb

require 'nokogiri'

module ActiveMerchant #:nodoc:
  module Billing #:nodoc:
    class AuthorizeNetGateway < Gateway
      include Empty

      self.test_url = 'https://apitest.authorize.net/xml/v1/request.api'
      self.live_url = 'https://api2.authorize.net/xml/v1/request.api'

      # etc.

      def url
        test? ? test_url : live_url
      end

How and where is this set? Spree passes the ActiveMerchant Gem some data which the ActiveMerchant Gem uses to create Response objects. Below is the code where ActiveMerchant handles this data.

active_merchant/lib/active_merchant/billing/response.rb

module ActiveMerchant #:nodoc:
  module Billing #:nodoc:
    class Error < ActiveMerchantError #:nodoc:
    end

    class Response
      attr_reader :params, :message, :test, :authorization, :avs_result, :cvv_result, :error_code, :emv_authorization

      # etc.

      def test?
        @test
      end

      def initialize(success, message, params = {}, options = {})
        @success, @message, @params = success, message, params.stringify_keys
        @test = options[:test] || false
        @authorization = options[:authorization]
        @fraud_review = options[:fraud_review]
        @error_code = options[:error_code]
        @emv_authorization = options[:emv_authorization]

        @avs_result = if options[:avs_result].kind_of?(AVSResult)
          options[:avs_result].to_hash
        else
          AVSResult.new(options[:avs_result]).to_hash
        end

        @cvv_result = if options[:cvv_result].kind_of?(CVVResult)
          options[:cvv_result].to_hash
        else
          CVVResult.new(options[:cvv_result]).to_hash
        end
      end
    end

active_merchant/lib/active_merchant/billing/gateway.rb

# Are we running in test mode?
def test?
  (@options.has_key?(:test) ? @options[:test] : Base.test?)
end

Now that I was more familiar with ActiveMerchant, I wanted to verify that Spree was passing the data as intended

I could see in spree/core/app/models/spree/gateway.rb that Spree was setting ActiveMerchant::Billing::Base.gateway_mode equal to the server param as a symbol. I verified it with some logging.

def provider
	gateway_options = options
	gateway_options.delete :login if gateway_options.has_key?(:login) and gateway_options[:login].nil?
	if gateway_options[:server]
		ActiveMerchant::Billing::Base.gateway_mode = gateway_options[:server].to_sym
	end
	@provider ||= provider_class.new(gateway_options)
end

At this point I was satisfied that Spree was sending a server param. I also knew Spree was setting Active Merchant’s Base.gateway_mode as intended. I then reviewed active_merchant/lib/active_merchant/billing/gateway.rb once more

# Are we running in test mode?
def test?
	(@options.has_key?(:test) ? @options[:test] : Base.test?)
end

and active_merchant/lib/active_merchant/billing/base.rb

def self.test?
	self.gateway_mode == :test
end

So, that’s it! We know from the exceptions I raised that Spree is sending a test key and a test_mode key. They seem to be the same value but with different keys (I’m guessing that’s a mistake), and they both just seem to indicate if the test mode checkbox was checked or not in the Spree admin. However, Base.test? is the server selection and comes from whatever anyone enters in the server input box in the Spree admin. So, we just need to update the ternary operator to check if @options[:test] (test mode) or Base.test? (test server) is true.

Since this is Spree, I created a decorator to override the test? method.

app/models/gateway_decorator.rb

ActiveMerchant::Billing::Gateway.class_eval do
  def test?
    @options.has_key?(:test) && @options[:test] || ActiveMerchant::Billing::Base.test?
  end
end

Lastly, I placed some test orders and it all worked as intended.

Summary

Authorize.net is disabling the RC4 cipher suite. If your site(s) uses that, your payment processing may be interrupted. Since the test environment has been updated by Authorize.net, you can see if your site(s) is compliant by posting test transactions to the test environment. If it works, then your site(s) should be compliant and ready when Authorize.net applies the changes to the production server.

Spree 2.1.x (and perhaps all other Spree versions) always send the test key, so the ActiveMerchant Gem will always just use the boolean value of that key instead of ever checking to see what the server was set to. Further, this fix makes things a little bit more robust in my opinion by checking if test mode OR the test server was specified, rather than only checking which server (gateway_mode) was specified if the test key was absent.

Alternatively, you could probably make Spree only pass the test key if the value was true. Either way, if you are trying to send test orders to the test environment for a Spree site of at least some versions and have not implemented one of these changes, you will be unable to do so until you add a similar fix as I have described here. If you need any further assistance, please reach out to us.

Spree Admin pages unreachable (500 errors)

2016-03-17T00:00:00+00:00

I was notified a few minutes ago by one of our Spree clients that their admin interface was unreachable due to errors.

Digging into the logs, I discovered SocketErrors (DNS lookup failures) were behind the 500 errors. Digging deeper, I discovered the SocketErrors were coming from a Spree file attempting to access “alerts.spreecommerce.com”. I confirmed in my browser that alerts.spreecommerce.com fails to resolve.

This Git commit discusses the removal of the class, but if you haven’t stayed current and you’ve left the “Check for alerts” box checked, you may need to do some manual editing of your stored preferences to get the UI to load again.

Spree::Preference.where(key: "spree/app_configuration/check_for_spree_alerts").first.update_attributes(value: false)

It does appear that your app will need to restart to pull in this change.

I’m not sure what the chances are your particular config key might vary, so please use the above with caution.

Spree Commerce “invalid value for Integer(): "09"” in Spree::Checkout/update

2015-01-14T00:00:00+00:00

Hello again all. I like to monitor the orders and exceptions of the Spree sites I work on to ensure everything is working as intended. One morning I noticed an unusual error: “invalid value for Integer(): "09"” in Spree::Checkout/update on a Spree 2.1.x site.

The Issue

Given that this is a Spree-powered e-commerce site, a customer’s inability to checkout is quite alarming. In the backtrace I could see that a string of “09” was causing an invalid value for an integer. Why hadn’t I seen this on every order in that case?

I went into the browser and completed some test orders. The bug seemed to affect only credit cards with a leading “0” in the expiration month, and then only certain expiration months. I returned to the backtrace and saw this error was occurring with Active Merchant. So, Spree was passing Active Merchant a string while Active Merchant was expecting an integer.

Armed with a clearer understanding of the problem, I did some Googling. I came across this post. This post describes the source of this issue as being the behavior of sprintf which I will describe below. This topic was discussed in the Ruby Forum.

Octal Numbers

As per Daniel Martin on the aforementioned post:

sprintf("%d",‘08’) ==> ArgumentError
sprintf("%d",‘8’) ==> “8”
sprintf("%d",‘08’.to_i) ==> “8”
sprintf("%f",‘08’) ==> “8.000000”

As you can see, sprintf cannot convert ‘08’ or ‘09’ to a decimal. Matthias Reitlinger notes,

“%d tells sprintf to expect an Integer as the corresponding argument. Being given a String instead it tries to convert it by calling Kernel#Integer”

In the same post, we can review some documentation of Kernel#Integer

We can see here that if the argument being provided is a string (and it is since that is what Spree is sending), the “0” will be honored. Again, we know

<tr>
  <td>sprintf("%d",'02') => "2"</td>
  <td> | </td>
  <td>sprintf("%d", 02) => "2"</td>
</tr>

<tr>
  <td>sprintf("%d",'03') => "3"</td>
  <td> | </td>
  <td>sprintf("%d", 03) => "3"</td>
</tr>

<tr>
  <td>sprintf("%d",'04') => "4"</td>
  <td> | </td>
  <td>sprintf("%d", 04) => "4"</td>
</tr>

<tr>
  <td>sprintf("%d",'05') => "5"</td>
  <td> | </td>
  <td>sprintf("%d", 05) => "5"</td>
</tr>

<tr>
  <td>sprintf("%d",'06') => "6"</td>
  <td> | </td>
  <td>sprintf("%d", 06) => "6"</td>
</tr>

<tr>
  <td>sprintf("%d",'07') => "7"</td>
  <td> | </td>
  <td>sprintf("%d", 07) => "7"</td>
</tr>

<tr>
  <td>sprintf("%d",'08') => error</td>
  <td> | </td>
  <td>sprintf("%d", 08) => error</td>
</tr>

<tr>
  <td>sprintf("%d",'09') => error</td>
  <td> | </td>
  <td>sprintf("%d", 09) => error</td>
</tr>

sprintf("%d",'01') => "1"

sprintf("%d", 01) => "1"

By pre-prepending the “0” to the numbers, they are being marked as ‘octal’. Wikipedia defines octal numbers as

“The octal numeral system, or oct for short, is the base-8 number system, and uses the digits 0 to 7. Octal numerals can be made from binary numerals by grouping consecutive binary digits into groups of three (starting from the right).”

So, 08 and 09 are not octal numbers.

Solution

This is why this checkout error did not occur on every order whose payment expiration month had a leading “0”, only August (08) and September (09) were susceptible as the leading ‘0’ indicates we are passing in an octal of which 08 and 09 are not valid examples of. So, I made Spree send integers (sprintf("%d",8) #=> “8” and sprintf("%d",9) #=> “9”) so that the leading “0” would not get sent (thereby not trying to pass them as octals). I created a app/models/spree/credit_card_decorator.rb file with the contents

Spree::CreditCard.class_eval do
  def expiry=(expiry)
    if expiry.present?
      self[:month], self[:year] = expiry.delete(' ').split('/')
      self[:year] = "20" + self[:year] if self[:year].length == 2
      self[:year] = self[:year].to_i
      self[:month] = self[:month].to_i
    end
  end
end

After adding this, I tested it in the browser and there were no more checkout errors! I hope you’ve found this interesting and helpful, thanks for reading!

Create a sales functionality within Spree 2.3 using Spree fancy

2014-11-14T00:00:00+00:00

Introduction

I recently started working with Spree and wanted to learn how to implement some basic features. I focused on one of the most common needs of any e-commerce business—adding a sale functionality to products. To get a basic understanding of what was involved, I headed straight to the Spree Developer Guides. As I was going through the directions, I realized it was intended for the older Spree version 2.1. This led to me running into a few issues as I went through it using Spree’s latest version 2.3.4. I wanted to share with you what I learned, and some tips to avoid the same mistakes I made.

Set-up

I’ll assume you have the prerequisites it lists including Rails, Bundler, ImageMagick and the Spree gem. These are the versions I’m running on my Mac OS X:

Ruby: 2.1.2p95
- Rails: 4.1.4
- Bundler: 1.5.3
- ImageMagick: 6.8.9-1
- Spree: 2.3.4

What is Bundler? Bundler provides a consistent environment for Ruby projects by tracking and installing the exact gems and versions that are needed. You can read more about the benefits of using Bundler on their website. If you’re new to Ruby on Rails and/or Spree, you’ll quickly realize how useful Bundler is when updating your gems.

After you’ve successfully installed the necessary tools for your project, it’s time to create our first Rails app, which will then be used as a foundation for our simple Spree project called mystore

Let’s create our app

Run the following commands:

$ rails new mystore
$ cd mystore
$ gem install spree_cmd

*Note: you may get a warning that you need to run bundle install before trying to start your application since spree_gateway.git isn’t checked out yet. Go ahead and follow those directions, I’ll wait.

Spree-ify our app

We can add the e-commerce platform to our Rails app by running the following command:

spree install --auto-accept

If all goes well, you should get a message that says, “Spree has been installed successfully. You’re all ready to go! Enjoy!”. Now the fun part—let’s go ahead and start our server to see what our demo app actually looks like. Run rails s to start the server and open up a new browser page pointing to the URL localhost:3000.

*Note—when you navigate to localhost:3000, watch your terminal—you’ll see a lot of processes running in the background as the page loads simultaneously in your browser window. It can be pretty overwhelming, but as long as you get a “Completed 200 OK” message in your terminal, you should be good to go! See it below:

Our demo app actually comes with an admin interface ready to use. Head to your browser window and navigate to http://localhost:3000/admin. The login Spree instructs you to use is spree@example.com and password spree123.

Once you login to the admin screen, this is what you should see:

Once you begin to use Spree, you’ll soon find that the most heavily used areas of the admin panel include Orders, Products, Configuration and Promotions. We’ll be going into some of these soon.

Extensions in 3.5 steps

The next part of the Spree documentation suggests adding the spree_fancy extension to our store to update the look and feel of the website, so let’s go ahead and follow the next few steps:

Step 1: Update the Gemfile

We can find our Gemfile by going back to the terminal, and within the mystore directory, type ls to see a list of all the files and subdirectories within the Spree app. You will see the Gemfile there—open it using your favorite text editor. Add the following line to the last line of your Gemfile, and save it:

gem 'spree_fancy', :git => 'git://github.com/spree/spree_fancy.git', :branch => '2-1-stable'

Notice the branch it mentions is 2-1-stable. Since you just installed Spree, you are most likely using the latest version, 2-3-stable. I changed my branch in the above gem to ‘2-3-stable’ to reflect the Spree version I’m currently using. After completing this step, run bundle install to install the gem using Bundler.

Now we need to copy over the migrations and assets from the spree_fancy extension by running this command in your terminal within your mystore application:

$ bundle exec rails g spree_fancy:install

Step 1.5: We’ve hit an error!

At this point, you’ve probably hit a LoadError, and we can no longer see our beautiful Spree demo app, instead getting an error page which says “Sprockets::Rails::Helper::AssetFilteredError in Spree::Home#index” at the top. How do we fix this?

Within your mystore application directory, navigate to config/intializers/assets.rb file and edit the last line of code by uncommenting it and typing:

Rails.application.config.assets.precompile += %w ( bx_loader.gif )

Now restart your server and you will see your new theme!

Step 2: Create a sales extension

Now let’s see how to create an extension instead of using an existing one. According to the Spree tutorial, we first need to generate an extension—remember to run this command from a directory outside of your Spree application:

$ spree extension simple_sales

Once you do that, cd into your spree_simple_sales directory. Next, run bundle install to update your Spree extension.

Now you can create a migration that adds a sale_price column to variants using the following command:

bundle exec rails g migration add_sale_price_to_spree_variants sale_price:decimal

Once your migration is complete, navigate in your terminal to db/migrate/XXXXXXXXXXXX_add_sale_price_to_spree_variants.rb and add in the changes as shown in the Spree tutorial:

class AddSalePriceToSpreeVariants < ActiveRecord::Migration
  def change
    add_column :spree_variants, :sale_price, :decimal, :precision => 8, :scale => 2
  end
end

Now let’s switch back to our mystore application so that we can add our extension before continuing any development. Within mystore, add the following to your Gemfile:

gem 'spree_simple_sales', :path => '../spree_simple_sales'

You will have to adjust the path (’../spree_simple_sales’) depending on where you created your sales extension.

Now it’s time to bundle install again, so go ahead and run that. Now we need to copy our migration by running this command in our terminal:

$ rails g spree_simple_sales:install

Step 3: Adding a controller Action to HomeController

Once the migration has been copied, we need to extend the functionality of Spree::HomeController and add an action that selects “on sale” products. Before doing that, we need to make sure to change our .gemspec file within the spree_simple_sales directory (remember: this is outside of our application directory).

Open up the spree_simple_sales.gemspec file in your text editor

Add the following line to the list of dependencies:

s.add_dependency ‘spree_frontend’

Run bundle.

Run $ mkdir -p app/controllers/spree to create the directory structure for our controller decorator. This is where we will create a new file called home_controller_decorator.rb and add the following content to it:

module Spree
  HomeController.class_eval do
    def sale
      @products = Product.joins(:variants_including_master).where('spree_variants.sale_price is not null').uniq
    end
  end
end

As Spree explains it, this script will select just the products that have a variant with a sale_price set.

Next step—add a route to this sales action in our config/routes.rb file. Make sure your routes.rb file looks like this:

Spree::Core::Engine.routes.draw do
  get "/sale" => "home#sale"
end

Let’s set a sale price for the variant

Normally, to change a variant attribute, we could do it through the admin interface, but we haven’t created this functionality yet. This means we need to open up our rails console:

*Note—you should be in the mystore directory

Run $ rails console

The next steps are taken directly from the Spree documentation:

“Now, follow the steps I take in selecting a product and updating its master variant to have a sale price. Note, you may not be editing the exact same product as I am, but this is not important. We just need one “on sale” product to display on the sales page.”

> product = Spree::Product.first
=> #<Spree::Product id: 107377505, name: "Spree Bag", description: "Lorem ipsum dolor sit amet, consectetuer adipiscing...", available_on: "2013-02-13 18:30:16", deleted_at: nil, permalink: "spree-bag", meta_description: nil, meta_keywords: nil, tax_category_id: 25484906, shipping_category_id: nil, count_on_hand: 10, created_at: "2013-02-13 18:30:16", updated_at: "2013-02-13 18:30:16", on_demand: false>

> variant = product.master
=> #<Spree::Variant id: 833839126, sku: "SPR-00012", weight: nil, height: nil, width: nil, depth: nil, deleted_at: nil, is_master: true, product_id: 107377505, count_on_hand: 10, cost_price: #<BigDecimal:7f8dda5eebf0,'0.21E2',9(36)>, position: nil, lock_version: 0, on_demand: false, cost_currency: nil, sale_price: nil>

> variant.sale_price = 8.00
=> 8.0

> variant.save
=> true

Hit Ctrl-D to exit the console.

Now we need to create the page that renders the product that is on sale. Let’s create a view to display these “on sale” products.

Create the required views directory by running:

$ mkdir -p app/views/spree/home

Create the a file in your new directory called sale.html.erb and add the following to it:

<div data-hook="homepage_products">
  <%= render 'spree/shared/products', :products => @products %>
</div>

Now start your rails server again and navigate to localhost:3000/sale to see the product you listed on sale earlier! Exciting stuff, isn’t it? The next step is to actually reflect the sale price instead of the original price by fixing our sales price extension using Spree Decorator.

Decorate your variant

Create the required directory for your new decorator within your mystore application:

$ mkdir -p app/models/spree

Within your new directory, create a file called variant_decorator.rb and add:

module Spree
  Variant.class_eval do
    alias_method :orig_price_in, :price_in
    def price_in(currency)
      return orig_price_in(currency) unless sale_price.present?
      Spree::Price.new(:variant_id => self.id, :amount => self.sale_price, :currency => currency)
    end
  end
end

The original method of price_in now has an alias of price_in unless there is a sale_price present, in which case the sale price is returned on the product’s master variant.

In order to ensure that our modification to the core Spree functionality works, we need to write a couple of unit tests for variant_decorator.rb. We need a full Rails application present to test it against, so we can create a barebones test_app to run our tests against.

Run the following command from the root directory of your EXTENSION:

$ bundle exec rake test_app

It will begin the process by saying “Generating dummy Rails application…”—great! you’re on the right path.

Once you finish creating your dummy Rails app, run the rspec command and you should see the following output:

No examples found.

Finished in 0.00005 seconds

0 examples, 0 failures

Now it’s time to start adding some tests by replicating your extension’s directory structure in the spec directory:

$ mkdir -p spec/models/spree

In your new directory, create a file called variant_decorator_spec.rb and add this test:

require 'spec_helper'

describe Spree::Variant do
  describe "#price_in" do
    it "returns the sale price if it is present" do
      variant = create(:variant, :sale_price => 8.00)
      expected = Spree::Price.new(:variant_id => variant.id, :currency => "USD", :amount => variant.sale_price)

      result = variant.price_in("USD")

      result.variant_id.should == expected.variant_id
      result.amount.to_f.should == expected.amount.to_f
      result.currency.should == expected.currency
    end

    it "returns the normal price if it is not on sale" do
      variant = create(:variant, :price => 15.00)
      expected = Spree::Price.new(:variant_id => variant.id, :currency => "USD", :amount => variant.price)

      result = variant.price_in("USD")

      result.variant_id.should == expected.variant_id
      result.amount.to_f.should == expected.amount.to_f
      result.currency.should == expected.currency
    end
  end
end

Deface overrides

Next we need to add a field to our product admin page, so we don’t have to always go through the rails console to update a product’s sale_price. If we directly override the view that Spree provides, whenever Spree updates the view in a new release, the updated view will be lost, so we’d have to add our customizations back in to stay up to date.

A better way to override views is to use Deface, which is a Rails library to directly edit the underlying view file. All view customizations will be in ONE location: app/overrides which will make sure your app is always using the latest implementation of the view provided by Spree.

Go to mystore/app/views/spree and create an admin/products directory and create the file _form.html.erb.
Copy the full file NOT from Spree’s GitHub but from your Spree backend. You can think of your Spree backend as the area to edit your admin (among other things)—the spree_backend gem contains the most updated _form.html.erb—if you use the one listed in the documentation, you will get some Method Errors on your product page.

In order to find the _form.html.erb file in your spree_backend gem, navigate to your app, and within that, run the command:

bundle show spree_backend

The result is the location of your spree_backend. Now cd into that location, and navigate to app/views/spree/admin/products—this is where you will find the correct _form.html.erb. Copy the contents of this file into the newly created _form.html.erb file within your application’s directory structure you just created: mystore/app/views/spree/admin/products.

Now we want to actually add a field container after the price field container for sale price so we need to create another override by creating a new file in your application’s app/overrides directory called add_sale_price_to_product_edit.rb and add the following content:

Deface::Override.new(:virtual_path => 'spree/admin/products/_form',
  :name => 'add_sale_price_to_product_edit',
  :insert_after => "erb[loud]:contains('text_field :price')",
  :text => "
    <%= f.field_container :sale_price do %>
      <%= f.label :sale_price, raw(Spree.t(:sale_price) + content_tag(:span, ' *')) %>
      <%= f.text_field :sale_price, :value =>
        number_to_currency(@product.sale_price, :unit => '') %>
      <%= f.error_message_on :sale_price %>
    <% end %>
  ")

The last step is to update our model in order to get an updated product edit form. Create a new file in your application’s app/models/spree directory called product_decorator.rb. Add the following content:

module Spree
  Product.class_eval do
    delegate_belongs_to :master, :sale_price
  end
end

Now you can check to see if it worked by heading to http://localhost:3000/admin/products and you should edit one of the products. Once you’re on the product edit page, you should see a new field container called SALE PRICE. Add a sale price in the empty field and click on update. Once completed, navigate to http://localhost:3000/sale to find an updated list of products on sale.

Conclusion

Congratulations, you’ve created the sales functionality! If you’re using Spree 2.3 to create a sales functionality for your application, I would love to know what your experience was like. Good luck!

Spree Authorization Failure for Customized Role

2014-09-22T00:00:00+00:00

Hello again all. Recently I was working on another Spree site running Spree 2.1.1. The client wanted to create some custom roles. For example, the client wanted there to be a Sales Manager role. A Sales Manager could log in and have read and write access to all the orders. However, a sales manager should not have read/write access to products, configuration, promotions, users, etc. This was easily accomplished by following the steps in the Spree documentation. As I will describe, this documentation assumes that the custom role will have access to Orders#index.

The client wanted to create a second custom role that had create, read, update and delete access to the Training model and nothing more. The training model belongs to a taxon and has a unique event date and taxon id. An example would be a training instance with an event date of September 9th, 2014 that belongs to a taxon with the name “Fire Safety 101” and a description “Teaching fire safety in accordance with OSHA standards. 10 hours and lunch is provided”. So, I planned to create a training personnel role that should be able to log in and only have read/write access to Trainings. However, the Spree documentation did not provide an explanation on how to create a custom role that does not have read or write access to orders.

Following the pattern described in the Spree documentation for creating custom roles and their respective authorization, I created an ability_decorator.rb with the contents:

class AbilityDecorator
     include CanCan::Ability
     def initialize(user)
       if user.respond_to?(:has_spree_role?) && user.has_spree_role?('sales_manager')
         can [:admin, :index, :show], Spree::Order
       end
       if user.respond_to?(:has_spree_role?) && user.has_spree_role?('training')
         can [:admin, :manage], Spree::Training
       end
     end
   end
 
   Spree::Ability.register_ability(AbilityDecorator)

However, after creating a training user and attempting to log in, I got an unauthorized error. So, I checked the logs:

The log output above shows that while I was logged in as a user with the training role, the application was checking for authorization on Spree::Admin::OrdersController#index (the orders list page), because the base admin URL ("/admin") points to this controller action. I reviewed the Devise documentation to modify where a user with the training role is redirected to upon login (via Spree Auth Devise’s after_sign_in method), as shown in the code shown below.

def after_sign_in_path_for(resource)
    stored_location_for(resource) ||
      if resource.is_a?(Spree::User) && resource.has_spree_role?('training')
        admin_trainings_path
      else
        super
      end
  end

After making this change, I tried once again and was able to successfully log in as a training user and only have the desired access to Trainings.

To summarize, if you’d like to have a custom role and not give them access to Orders, you will need to make some adjustments outside the steps listed in Spree’s documentation for custom role authorization.

Enhancing the labelsontime.com Spree application

2014-09-09T00:00:00+00:00

Labels on Time is an online retailer that delivers top-quality thermal roll and direct thermal labels—and all on time, of course. They came to us last year to upgrade their Spree site, resolve bugs, and develop cutting-edge features, utilizing our expertise with the ecommerce platform. Spree Commerce is an open-source ecommerce solution built on Ruby on Rails, and manages all aspects of the fulfillment process, from checkout to shipping to discounts, and much more.

UPGRADING THE SPREE PLATFORM

There were quite a few challenges associated with the upgrade, since Labels on Time was still running on Spree’s version 2.0, which was not yet stable. To keep some stability, we initially worked off a fork of Spree, and selectively brought in changes from 2.0 when we were sure they were stable and reliable enough.

USING SPREE GEMS

To date, some of the Spree gems we have used on the site include:

Active Shipping: This is a Spree plugin that can interface with USPS, UPS and FedEx. Label on Time’s active_shipping gem interacts with the UPS API, which is a big task to tackle since it requires a lot of configuration, especially every time Spree is updated.

Another important gem we use for Labels on Time is Volume Pricing. Volume Pricing is an extension to Spree that uses predefined ranges of quantities to determine the price for a particular product variant. When we first added this gem on the labelsontime.com checkout page, we kept finding that if a user increased the number of items in their cart sufficiently to activate the volume pricing and receive a discount per item, the standard Spree view did not show the new (discounted) price that was currently in effect (although it was correctly calculating the totals). To resolve this, our developer Matt Galvin created some custom JavaScript and Ruby code. Thanks to Matt’s ingenuity, the application can now return every price for every possible size and sort it accordingly.

WHAT WE’RE WORKING ON NEXT

Matt recently upgraded the application to 2.0.10, which was needed for security reasons. You can read more about the security fix here.

We are also working on implementing a neat SEO gem called Canonical Rails, which helps search engines understand that any duplicate content URLs it can access all refer to the canonical URL.

Next up, we’re going to implement inventory management, where, according to a customer’s location, we can suggest the available inventory in the closest warehouse to that location.

Spree Commerce, Take Care When Offering Free Shipping Promotion

2014-08-20T00:00:00+00:00

Hello again all. I was working on another Spree Commerce Site, a Ruby on Rails based e-commerce platform. As many of you know, Spree Commerce comes with Promotions. According to Spree Commerce documentation, Spree Commerce Promotions are:

“… used to provide discounts to orders, as well as to add potential additional items at no extra cost. Promotions are one of the most complex areas within Spree, as there are a large number of moving parts to consider.”

The promotions feature can be used to offer discounts like free shipping, buy one get one free etc.. The client on this particular project had asked for the ability to provide a coupon for free shipping. Presumably this would be a quick and easy addition since these types of promotions are included in Spree.

The site in question makes use of Spree’s Active Shipping Gem, and plugs in the UPS Shipping API to return accurate and timely shipping prices with the UPS carrier.

The client offers a variety of shipping methods including Flat Rate Ground, Second Day Air, 3 Day Select, and Next Day Air. Often, Next Day Air shipping costs several times more than Ground. E.g.: If something costs $20 to ship Ground, it could easily cost around $130 to ship Next Day Air.

When creating a free shipping Promotion in Spree it’s important to understand that by default it will be applied to all shipping methods. In this case, the customer could place a small order, apply the coupon and receive free Next Day Air shipping! To take care of this you need to use Promotion Rules. Spree comes with several built-in rules:

First Order: The user’s order is their first.
ItemTotal: The order’s total is greater than (or equal to) a given value.
Product: An order contains a specific product.
User: The order is by a specific user.
UserLoggedIn: The user is logged in.

As you can see there is no built in Promotion Rule to limit the free shipping to certain shipping methods. But fear not, it’s possible to create a custom rule.

module Spree
     class Promotion
       module Rules
         class RestrictFreeShipping < PromotionRule
           MATCH_POLICIES = %w(all)
 
           def eligible?(order, options={})
             e = false
             if order.shipment.shipping_method.admin_name == "UPS Flat Rate Ground"
               e = true
             else
               e = false
             end
            return e
           end
        end
      end
    end
  end

Note that you have to create a partial for the rule, as per the documentation.

Then, in config/locales/en.yml I added a name and description for the rule.

en:
     spree:
       promotion_rule_types:
         restrict_free_shipping:
           name: Restrict Free Shipping To Ground
           description: If somebody uses a free shipping coupon it should only apply to ground shipping

The last step was to restart the app and configure the promotion in the Spree Admin interface.

Unable to Bcc in mail, Spree 2.0 Stable Rails 3.2.14

2014-06-09T00:00:00+00:00

Hello again all. As usual, I was working on a Spree Commerce website. I recently encountered an issue when trying to bcc order confirmation emails. Others have been asking about this on Github and also on the Spree mailing list, so it was time to write about the problem and the solution that worked for me.

First, I’d like to briefly describe the use case here. As with any typical e-commerce site, a user visits the site, adds some items to their cart, and checks out. After which, an order confirmation (order summary) email is sent to the user with their order details and any extra information provided by the seller.

Spree pretty much handles all this for you automatically. What about if you as the business owner would like a copy of this e-mail? Easy enough. If you review the Spree documentation you will see simple instructions for the “Mail Method Settings” to set up in the Spree Admin Interface.

Ok, so let’s say you follow all the instructions and start placing test orders (or receiving real ones), and you’re not getting bcc’d? This is where it gets tricky, so let’s check out a few things:

Check the logs

Check to see if Spree/Rails is attempting to send the confirmation email to your Bcc recipient
Try development, test, & production modes

If the Bcc email is not getting sent, keep following along for the solution

Ensure the interceptor works by adding a value into “INTERCEPT EMAIL ADDRESS” via the admin. If emails are being intercepted you know the the interceptor is working. Why is that important? Because, that is also where the bcc code is.

core/lib/spree/mail_interceptor.rb

module Spree
  module Core
    class MailInterceptor
      def self.delivering_email(message)
        return unless MailSettings.override?

        if Config[:intercept_email].present?
          message.subject = "#{message.to} #{message.subject}"
          message.to = Config[:intercept_email]
        end

        if Config[:mail_bcc].present?
          message.bcc ||= Config[:mail_bcc]
        end
      end
    end
  end
end

You can ensure that more than one email can be sent by updating mail(to: @order.email, from: from_address, subject: subject) to be an array of emails, like mail(to: [@order.email, "some_other_email@somewhere.com"], from: from_address, subject: subject)

core/app/mailers/spree/order_mailer.rb

module Spree
  class OrderMailer < BaseMailer
    def confirm_email(order, resend = false)
      @order = order.respond_to?(:id) ? order : Spree::Order.find(order)
      subject = (resend ? "[#{Spree.t(:resend).upcase}] " : '')
      subject += "#{Spree::Config[:site_name]} #{Spree.t('order_mailer.confirm_email.subject')} ##{@order.number}"
      mail(to: @order.email, from: from_address, subject: subject)
    end

    def cancel_email(order, resend = false)
      @order = order.respond_to?(:id) ? order : Spree::Order.find(order)
      subject = (resend ? "[#{Spree.t(:resend).upcase}] " : '')
      subject += "#{Spree::Config[:site_name]} #{Spree.t('order_mailer.cancel_email.subject')} ##{@order.number}"
      mail(to: @order.email, from: from_address, subject: subject)
    end
  end
end

At this point, you’ve verified the interceptor works, and the mailer can definitely send more than one email. Here is the final piece that is not mentioned anywhere on the Spree site, or any resolutions for any posts I had found: you may need to contact your hosting provider and ask them to make any necessary adjustments to allow for the bcc messages. I saw that several people have gotten hung up on this and I hope this post has saved you some time. If you are still having trouble, please feel free to reach out in the comments. You can refer to the Spree issue I created on this topic some time ago.

Spree Security Update 2.x.x Error, undefined method ‘assume_from_symbol’ for Money:Class (ActionView::Template::Error)

2014-04-23T00:00:00+00:00

On March 25, 2014 Spree Commerce posted an announcement that there was a security vulnerability for all Spree 2.x.x versions. As reported on Spree’s website,

“The exploit would require the attacker to randomly guess valid order numbers, but once achieved, the technique would reveal private customer information associated with the order. Credit card details are never stored in Spree and were never at risk by this exploit.”

So, this update is pretty typical and as usual, you should make sure nothing has broken with any changes that were made. I wanted to note a couple of “gotchas” with this most recent update however.

The first of which is probably obvious and really more of a reminder as sometimes people forget. Further, the instructions for this update in the Spree docs don’t mention it, so, as a reminder - after updating be sure to run

$ bundle exec rake railties:install:migrations
$ bundle exec rake db:migrate

Now, here is the tricky one. After updating and installing/running your migrations you may find that you are getting an error:

undefined method `assume_from_symbol' for Money:Class (ActionView::Template::Error)

I have been unable to find anything on this in the Spree documentation but the problem is that in the update the money gem version 6.1.1 breaks the product display. The work around is to lock the money gem at 6.0.1. So, specify version 6.0.1 for the money gem in your Gemfile

gem 'money', '=6.0.1'

Updating Spree versions can sometimes be a little tense if things start breaking and you don’t know why. I hope that if this error brought you here this article has saved you some time.

Spree Active Shipping Gem “We are unable to calculate shipping rates for the selected items.” Error

2014-02-12T00:00:00+00:00

I was recently working on a Spree site and setting up the Spree Active Shipping Gem along with the UPS API. For those not familiar, the Spree Active Shipping Gem interacts with various shipping APIs like UPS, USPS, and FedEx. Due to the nature of Spree—where it does so much for you, and the interaction between the Active Shipping Gem and a shipping API also being “auto-magic”, it is often difficult to debug. As I was recently undertaking the task of setting this up I found a few “gotchas” that I hope, through this blog post, may be able to save others a lot of time.

I have found that there wasn’t a lot of instruction for setting up the Active Shipping Gem and a shipping carrier API like the UPS Shipping API. Ostensibly, there isn’t much to it—the Active Shipping Gem handles much of the interaction between the shipping API of choice and Spree.

First, you’re going to go the Spree Active Shipping Gem GitHub repo and follow the instructions for installing the Active Shipping Gem. It is very straightforward, but do proceed in the order mentioned in the Spree Active Shipping Gem documentation as some steps depend on the successful completion of others.

Second, you’re going to go to the shipper of your choice, in this case UPS, and follow their directions for using their API. I do recommend actually reading, or at least skimming, the pages and pages of documentation. Why? Because there are some important agreements explaining how the API is to be used (basically legal requirements for the UPS logo).

The Active Shipping Gem makes a call to the API, the API returns a hash of various shipping methods and prices based on the parameters you’ve sent it (such as shipment origin and destination), and then it automatically displays in the UI as an adjustment. How great is that?!

Well, it would be great if it all worked out exactly as planned. However, if you are running Spree 2-0-stable you may find yourself battling an unusual circumstance. Namely, Spree 2-0-stable will create your core/app/views/spree/checkout/edit.html.erb as

<% content_for  :head do %>
     <%= javascript_include_tag '/states' %>
   <% end  %>

This will provide the incorrect path. It is intended to hit the StatesController, so update it like so:

<% content_for  :head do %>
     <%= javascript_include_tag states_url %>
   <% end  %>

Now, once this correction has been made you may find that you are still having an error, “We are unable to calculate shipping rates for the selected items.”

At this point Chrome Dev Tools will not show any errors. When I had this error, a number of Google searches returned results of the kind “make sure you have set up your shipping zones correctly and added shipping methods to these zones”. I verified this again and again in the console, as did many others who were equally perplexed by this message on StackOverflow as well as in Google Groups, like here and here. Some got this error when they added an item to the cart that had a count_on_hand of 0 and backorderable equal to false, like you can see here at Spree GitHub issues. If a 0 count_on_hand is what is giving you this error, but you want a product to be backorderable, make sure to also check the “Propagate All Variants” in the Spree admin as seen below. This will loop through all of the product’s variants with a count_on_hand of 0, and allow them to be backorderable.

After a long while of searching and wondering, is it the API? Is it the Active Shipping Gem? Is it a blacklisted zip code? I went through and changed one setting at a time in the Spree admin until finally arriving at the source of this error for me. Missing product weight. Because UPS needs the product weight in order to calculate shipping charges, make sure this is set.

The “We are unable to calculate shipping rates for the selected items” error message is misleading. If you encounter this error after correcting the javascript_include_tag, the cause is most likely a setting in the admin. Check for how insufficient inventory is handled, missing product weights, or incorrectly setup up or non-existent shipping zones & associated methods. I hope if this error message is what brought you here that this post has saved you some time.

A Brief Retrospective of Spree

2014-02-10T00:00:00+00:00

SpreeConf NYC 2014 starts on the 26th and its hard to believe that Spree is almost 7 years old! Here’s a retrospective showing some notable Spree moments and major releases.

July 15, 2007 RailsCart, the precursor to Spree, is created by Sean Schofield and gets its first commit as a Google Code project.

February 1, 2008 Sean is hired by End Point Corporation to work on RailsCart along with its other Rails developers. End Point sponsors Spree for the next year and a half.

February 15, 2008 RailsCart project moves from Google Code to GitHub and is renamed Spree.

June 1, 2008 Spree 0.0.9 released: sophisticated data model for inventory.

June 3, 2008 Product Properties added.

June 5, 2008 Spree 0.2.0 released: adds Spree extensions.

July 4, 2008 Zones introduced.

Sept 8, 2008 Refactored to REST routing added state machine to order.

October 1, 2008 New Taxonomy system introduced.

October 2, 2008 Spree 0.4.0 released: Taxonomy, and VAT-inclusive pricing.

November 26, 2008 Volume pricing introduced as an extension.

November 24, 2008 Spree 0.5.0 released: new shipping framework.

December 3, 2008 SEO friendly URLs.

December 4, 2008 Switched from attachment_fu to paperclip for image attachments.

February 3, 2009 Spree 0.6.0 released: friendly urls, attachment_fu to paperclip, paranoid deletion of products, standardized security model, rake tasks for translations.

March 5, 2009 Searchlogic gem added.

March 10, 2009 Spree 0.7.0 released: switches to ajax-based Magento-style single page checkout, order number as permalinks, French, Russian and Norwegian translations added.

April 2, 2009 Authlogic gem added.

April 23, 2009 Spreecommerce.com launched.

May 4, 2009 Spree 0.8.0 released: CSS based layout using compass, sass, and blueprint, Authlogic, guest checkout, expanded functionality for prototype products, improved upgrade rake task, improved order security using tokens.

May 18, 2009 Spree core team formalized.

May 28, 2009 Sean Schofield leaves End Point and founds Rails Dog.

September 22, 2009 Spree 0.9.0 released: Coupon and discount support, improved system of calculators, Thai, Hebrew, Dutch, Finish, and Mexican Spanish translations.

September 5, 2009 Spree now 100% jQuery for all JavaScript functionality.

March 13, 2009 Spree 0.10.0 released: Named scopes and product groups, pluggable search (Xapian, Sphinx, and Solr), theming, switch to multipage checkout, improved gateway configuration, multiple payment methods, refunds and credits, restful api.

June 14, 2010 Spree 0.11.0 released: new look for Spree, Rails 2.3.8 compatibility.

November 1, 2010 New extension registry.

November 9, 2010 Spree 0.30.0 released: Rails 3 support, reorganization into multiple gems: spree_core, spree_auth, spree_api, spree_dash, spree_sample, Rails engines introduced, site extension removed, extensions become gems, improved payments with addition of state machine, simplification of adjustments, new promotion functionality, no more “vendor mode”.

December 10, 2010 Spree 0.40.0 released: switched from Authlogic to Devise for authentication.

March 23, 2011 Spree 0.50.0 released: improved test coverage, replaced Searchlogic gem with Meta search gem.

May 13, 2011 Spree 0.60.0 released: removal of Resource Controller.

October 10, 2011 Announcement that Spree Commerce Inc. is formed and raised $1.5M in seed funding.

November 7, 2011 Spree 0.70.0 Integration with rails asset pipeline, theming support, themes as engines, extension generator, promotions extended.

January 31, 2012 Spree analytics with Jiraffe introduced.

February 9, 2012 Spree 1.0 released, namespacing introduced, Spree referenced routes, mounting Spree engine in routes, Spree analytics, Spree dash gem, command line tool, default payment gateway Spree/Skrill Spree_usa_epay, moved gateways out of core to Spree gateway gem, Refactored preferences, polymorphic adjustments, removed helpers and JavaScript related to VAT, removed sales tax and VAT calculators.

February 18, 2012 First SpreeConf held in New York City.

April 30, 2012 Spree 1.1.0 released: support for Rails 3.2, Ransack replaces meta search, Spree product groups is a standalone extension, theme support deprecated in favor of deface, major rewrite of credit card model, API rewrite, stronger mass assignment protection, clearer separation between Spree components, easier Spree spec testing.

August 31, 2012 Spree 1.2.0 released: Auth component completely removed from Spree and placed in separate Spree auth devise extension. Customizing state machine no longer requires completely overriding it.

December 19, 2012 Spree 1.3.0 released: Admin section redesigned, currency support.

December 20, 2012 New Spree “Fancy” theme introduced.

April 15, 2013 New documentation site launched.

May 19, 2013 Spree 2.0.0 released: Removed support for Ruby 1.8.7, Backend and Frontend split from core, Split shipments introduced, I18n names spaced translations, New API endpoints, instance level permission in API, Custom API templates, adjustment state changes, Order Populator in its own class, coupon applicator in its own class, product duplicator moved to its own class, new helpers to modify checkout flow steps, API supports “checking out” order, Auto-rotation of images, Unique payment identifier added to payments, removal of state call back in checkout controller, tracking URL for shipments, SSLRequirement deprecated in favor of ForceSSL, MailMethod model no longer exists,

May 21, 2013 Second SpreeConf held in Washington DC.

September 16, 2013 Spree 2.1.0 released: Rails 4 compatibility, breaking API changes, better Spree PayPal Express extension.

How to Dynamically Update A Spree Product’s Price Based on Volume Pricing

2013-11-08T00:00:00+00:00

I was recently working on a Spree Commerce site that utilizes Spree’s Volume Pricing extension. For those who may not be familiar, the Spree Commerce Volume Pricing extension allows a user to offer a variety of ‘price ranges’. These price ranges represent discounted prices per unit for larger quantity orders. For example (we will use this t-shirt pricing table for the remainder of the post) from the Spree Volume Pricing Github

   Variant                Name               Range        Amount         Position
   -------------------------------------------------------------------------------
   Rails T-Shirt          1-5                (1..5)       19.99          1
   Rails T-Shirt          6-9                (6...10)     18.99          2
   Rails T-Shirt          10 or more         (10+)        17.99          3

I would like to mention that these ranges, although resembling traditional ranges, are expressed as Strings as this will become more important later. Again from the Spree Volume Pricing project page at Github,

“All ranges need to be expressed as Strings and must include parentheses. ‘(1..10)’ is considered to be a valid range. ‘1..10’ is not considered to be a valid range (missing the parentheses.)

Now that the intent of Volume Pricing has been discussed I would like to bring your attention to what is likely a very common use case. Often on an e-commerce website when placing an order for an item the price and quantity is seen as so,

Which is generated from relatively typical Spree models and functions in erb and the HTML5 number input:

#price per shirt
  <%= display_price(@product) %> per shirt

  #number field
  <%= number_field_tag (@product.variants_and_option_values.any? ? :quantity : "variants[#{@product.master.id}]"),
    1, :class => 'title', :min => 1 %>
  <%= button_tag :class => 'large primary', :id => 'add-to-cart-button', :type => :submit do %>
    <%= Spree.t(:add_to_cart) %>
  <% end  %>

However, without any additional coding when a customer increases their order quantity to the next range, the price per unit (shirt) should be decremented as noted in the table above. However, as we can see here rather than the price being lowered to 18.99 per shirt, it continues to indicate 19.99 even though volume pricing has taken effect and the shirts are actually 18.99 each.

So, how would one accomplish this? JavaScript is the first thing that comes to most people’s mind. I spent some time looking around the Spree docs thinking that certainly there must be something quick to drop in, but there was not. I did a little Googling and found the same thing to be true—not much info out there on how best to proceed with this task. I was very surprised to find no notes on anyone doing what I would think is a very common issue. So, here we are and I hope that anyone who reads this finds it helpful.

Step 1a: Create an array of the prices

This is the most challenging part of the task. After discussing the issue with some colleagues I believed the easiest method was to create an array of all the possible volume prices. Then, this price could be referenced by just taking the selected quantity of an order, subtracting 1 (to account for the zero-indexing of arrays) and getting the value of the complete volume price array via that index. In this example, using the data from the table above, the array would look like this:

[19.99, 19.99, 19.99, 19.99, 19.99,18.99,18.99,18.99,18.99]

In case that isn’t clear from above, volume price (1..5) is 19.99 so the first 5 items in the array are 19.99. Volume price 18.99 is in effect for range (6..9) so the 6th through 9th item in the array are 18.99. If a user were to indicate a quantity of 5, 5-1 = 4. Index 4 of the array is 19.99, the correct price for five shirts. Note, for now I’ve left off the (10+) range and associated pricing and the reason will be clear in a few moments.

Alright, so now on how to create this array. Those of you who are familiar with Spree know that we use the Spree Model decorator, in this case, the Product decorator which should be created in app/models/product_decorator.rb

Spree::Product.class_eval do

  def all_prices
    price_ranges = Spree::Variant.where(product_id: self.id).first.volume_prices[0...-1].map(&:range)
    volume_prices = Spree::Variant.where(product_id: self.id).first.volume_prices[0...-1].map(&:amount).map(&:to_f)
    price_ranges.map(&:to_range).map{|v| v.map{|i| volume_prices[price_ranges.map(&:to_range).index(v)]}}.flatten
  end

end

Step 1b: Create to_range function for Strings & create a function to return lowest possible price per unit

Now here you may note the to_range call in pink above. As mentioned in this post and in the Volume Pricing docs, Spree expresses these ranges as Strings and not true ranges, so I used this to_range method in lib/range.rb to easily convert the String ranges into true Ranges, which I found on the “Master Ruby/Rails Programming” post at athikunte blog. I would also like to draw your attention to the fact that I am taking all but the last item of the volume prices array ([0…-1]). Why? Because ‘10+’ will not be converted into a range and any quantity of 10 or greater can just get the lowest volume price. Perhaps most importantly, if some product’s last range is 10+ while another is say 25+, this method of obtaining the lowest discounted price will avoid any problems related to that variance. In lib/string.rb,

class String
  def to_range
    case self.count('.')
      when 2
        elements = self.split('..')
        return Range.new(elements[0].to_i, elements[1].to_i)
      when 3
        elements = self.split('...')
        return Range.new(elements[0].to_i, elements[1].to_i-1)
      else
        raise ArgumentError.new("Couldn't convert to Range: #{str}")
    end
  end
end

app/models/product_decorator.rb

def lowest_discounted_volume_price
  Spree::Variant.where(product_id: self.id).first.volume_prices[-1].to_f
end

Step 2: Load Your New Volume Pricing Array and Lowest Possible Price

I did this by creating some script tags in the product show page (or wherever you wish to have this price per unit showing) to make the data from the backend available in a JavaScript file that will update the price dynamically as a user adds or subtracts from the desired quantity. I just called the functions I created in the product decorator here and stored the result in variables for the JavaScript file, app/views/product_show_page.html.erb

var all_prices = <%= @product.all_prices %>;
var lowest_discounted_volume_price = <%= @product.lowest_discounted_volume_price %>;

Step3: Write JavaScript Code to Handle Quantity Changes

In your Spree app just follow typical rails protocol and create a new JavaScript file in app/assets/javascripts/volume_pricing.js and of course require it in your manifest file. Here, just plug your variables in and update your view with the change event (I also added keyup so the price changes if/when a user types in a new quantity)

$(function() {
  $('.title').on('keyup change', function(e){
    var qty = parseInt( $(this).val());
    var prices_array = all_prices;
    var per_shirt = ' per shirt'
    if (qty <= prices_array.length)
      {
        $('span.price.selling').text('$'+prices_array[qty -1] + per_shirt);
      }
    else
      {
        $('span.price.selling').text('$'+lowest_discounted_volume_price + per_shirt);
      }
   });

And now you have dynamically updating price based on selected quantity! I hope you have found this informative and useful, thank you for reading.

Buy One Get One Promotion with Spree

2013-08-07T00:00:00+00:00

Implementing a “Buy One, Get One Free” promotion in Spree requires implementation of a custom promotion action and appropriate use of existing promotion rules. This article implements the promotion by automatically adding and removing immutable “get one” line items whose price is zero and whose quantity always mirrors its paid “buy one” counterpart. Although written and tested with Spree’s 1-3-stable branch, the core logic of this tutorial will work with any version of Spree.

Promotion Eligibility

Begin by creating a new promotion using a meaningful name. Set the “event name” field to be “Order contents changed” so the promotion’s actions are updated as the order is updated. Save this new promotion, so we can then configure Rules and Actions. In the Rules section, select the “Product(s)” rule and click Add. Now choose the products you’d like to be eligible for your promotion. If you’d like to include broader sets such as entire taxonomies (and have implemented the custom promotion rules to do so), feel free to use them. When we implement the promotion action, you’ll be able to make things work.

You should now have a product rule that selects some subset of products eligible for your promotion.

Adding a Custom Promotion Action

We’ll now add a custom promotion action that will do the work of creating the free line items for each eligible paid line item. Again, this implementation is specifically for the 1-3-stable branch, but the public interface for promotion actions has (amazingly) remained stable, and is supported from 0-7-0-stable all the way through 2-0-stable.

First, we begin by doing the basic wiring for creating a new promotion action. As the guide instructs, create a new promotion class in a file.

# app/models/spree/promotion/buy_one_get_one.rb
class BuyOneGetOne < Spree::PromotionAction
  def perform(options={})
    # TODO
  end
end

Then register this new class with Spree using an initializer.

# config/initializers/spree.rb

Rails.application.config.spree.promotions.actions << BuyOneGetOne

Then update your locales to provide translations for the promotion action’s name and description.

# config/locales/en.yml

en:
  spree:
    promotion_action_types:
      buy_one_get_one:
        name: Buy One Get One
        description: Adds free line items of matching quantity of eligible paid line items.

And although the guide doesn’t instruct you to, it seems required that you add an empty partial to be rendered in the Spree admin when you select the rule.

# app/views/spree/admin/promotions/actions/_buy_one_get_one.html.erb

# Empty File. Spree automatically renders the name and description you provide,
# but you could expand here if you'd like.

Pre-flight check

Before moving any farther, it’s best to make sure the new promotion action has been wired up correctly. Restart your development server so the initializer registers your new promotion action and refresh your browser. You should now see a “Buy One Get One” promotion action.

Buy One Get One Logic

Now that we’ve got the promotion action wired, we’re ready to implement the logic needed to create the new line items. Begin by collecting the order from the options.

# app/models/spree/promotion/buy_one_get_one.rb
class BuyOneGetOne < Spree::PromotionAction
  def perform(options={})
    return unless order = options[:order]
  end
end

Next we need to determine which line items in the order are eligible for a corresponding free line item. Because line items are for variants of products, we must collect the variant ids from the product rule we setup. If you’ve used something other the default Spree “Product(s)” rule, just make sure you end up with equivalent output.

# app/models/spree/promotion/buy_one_get_one.rb
class BuyOneGetOne < Spree::PromotionAction
  def perform(options={})
    return unless order = options[:order]

    eligible_variant_ids = get_eligible_variant_ids_from_promo_rule
    return unless eligible_variant_ids.present?
  end

  def get_eligible_variant_ids_from_promo_rule
    product_rule = promotion.promotion_rules.detect do |rule|
      # If not using the Product rule, update this line
      rule.is_a? Spree::Promotion::Rules::Product
    end 
    return unless product_rule.present?

    eligible_products = product_rule.products
    return unless eligible_products.present?

    eligible_products.collect { |p| p.variant_ids }.flatten.uniq
  end
end

Now that we’ve got the eligible variant ids from the promotion’s rule, we’ll identify the line items which have those variants.

# app/models/spree/promotion/buy_one_get_one.rb
class BuyOneGetOne < Spree::PromotionAction
  def perform(options={})
    return unless order = options[:order]

    eligible_variant_ids = get_eligible_variant_ids_from_promo_rule
    return unless eligible_variant_ids.present?

    order.line_items.where(variant_id: eligible_variant_ids).each do |li|
      #TODO
    end
  end
  ....
end

We’re now ready to process eligible line items. There are several cases we’ll need to implement to have a working promotion:

When we find an eligible, paid line item:
- if an existing corresponding free line item exists, update quantity to match the paid line item.
- Else, create corresponding free line item with appropriate quantity.
- When we find a Buy One Get One promotion line item:
- If the corresponding paid line item still exists, do nothing.
- Else, destroy the free line item.

These cases handle the creation, updating, and removal of promotional line items. Let’s translate these cases into a skeleton of code which can then be implemented incrementally.

# app/models/spree/promotion/buy_one_get_one.rb
class BuyOneGetOne < Spree::PromotionAction
  def perform(options={})
    return unless order = options[:order]

    eligible_variant_ids = get_eligible_variant_ids_from_promo_rule
    return unless eligible_variant_ids.present?

    order.line_items.where(variant_id: eligible_variant_ids).each do |li|
      if li.price != 0
        # It's an eligible variant and it's price is not zero, so we
        # found a "buy one" line item.

        matching_get_one_line_item = find_matching_get_one_line_item(li)

        # Create or update matching promo line item.
        if matching_get_one_line_item
          matching_get_one_line_item.update_attribute(:quantity, li.quantity)
        else
          create_matching_get_one_line_item(li)
        end 

      else
        # It's an eligible variant and it's price is zero, so we
        # found a "get one" line item.

        # Verify "buy one" line item still exists, else destroy
        # the "get one" line item
        li.destroy unless find_matching_buy_one_line_item(li)
    end
  end

  def find_matching_buy_one_line_item(li)
  end
  def create_matching_get_one_line_item(li)
  end
  def find_matching_get_one_line_item(li)
  end
  ....
end

This well named and commented code reads nicely and clearly covers the create, update, and destroy cases we need to be concerned with. Now let’s implement the helper methods.

  ....
  def find_matching_buy_one_line_item(get_one_line_item)
    get_one_line_item.order.line_items.detect do |li|
      li.variant_id == get_one_line_item.variant_id and li.price != 0
    end 
  end

  def create_matching_get_one_line_item(buy_one_line_item)
    # You may need to update this with other custom attributes you've added.
    new_line_item = buy_one_line_item.order.line_items.build
    new_line_item.variant = buy_one_line_item.variant
    new_line_item.currency = buy_one_line_item.currency
    new_line_item.price = 0
    new_line_item.quantity = buy_one_line_item.quantity
    new_line_item.save
  end

  def find_matching_get_one_line_item(buy_one_line_item)
    buy_one_line_item.order.line_items.detect do |li|
      li.variant_id == buy_one_line_item.variant_id and li.price != 0
    end 
  end
  ....
end

We’ve now completed most of the implementation for the promotion action. Every time the order is updated, all line items are scanned for eligibility and the appropriate create/update/destroy actions are taken. This however, isn’t the end of our implementation. Unlike other items in our cart, we need to prevent users from changing the quantity of “get one” line items or removing them from the cart. We also need some way of indicating that these zero price line items are complements of the Buy One Get One promotion.

Locked Line Items with Additional Text

While the concept of locked or immutable line items might rightly deserve its own, separate Spree plugin, we’ll roll a quick one here to complete the implementation of our promotion. We’ll need to add a few attributes to the spree_line_items database table, and tweak our implementation of create_matching_get_one_line_item.

# db/migration/add_immutable_and_additional_text_to_spree_line_items.rb
class AddImmutableAndAdditionalTextToSpreeLineItems < ActiveRecord::Migration
  def change
    add_column :spree_line_items, :immutable, :boolean
    add_column :spree_line_items, :additional_text, :string
  end
end

# app/models/spree/promotion/buy_one_get_one.rb
  def create_matching_get_one_line_item(buy_one_line_item)
    # You may need to update this with other custom attributes you've added.
    new_line_item = buy_one_line_item.order.line_items.build
    new_line_item.variant = buy_one_line_item.variant
    new_line_item.currency = buy_one_line_item.currency
    new_line_item.price = 0
    new_line_item.quantity = buy_one_line_item.quantity

    new_line_item.immutable = true
    new_line_item.additional_text = "Buy One Get One"

    new_line_item.save
  end

Now that we know which line items aren’t meant to be edited by users, we can update our UI to not render the options to remove immutable line items or update their quantity. We can also display the additional text in the line line item when it’s available.

Missing from this implementation is a way to secure the immutable line items from manipulation of the immutable line items POSTed parameters. While this might be required in other cases using immutable line items, because our promotion action sets the “get one” line items quantity with every order update, we don’t need to worry about this issue in this case.

Test Driving

At this point, you can begin manual testing of your implementation, but of course automated testing is best. Ideally, we would have TDDed this against a failing integration test, but the testing infrastructural setup required to do this is beyond the scope of the article. What’s worth sharing though, is the syntax of the assertions I’ve developed to inspect line items, so that you can implement something similar for your specific needs. Here’s a snippet from an integration test to give you a sense of the DSL we’ve built up.

# spec/requests/buy_one_get_one_spec.rb

context "add eligible item to cart" do
  before do
    # setup cart
    visit_product_and_add_to_cart eligible_product
    visit "/cart"
  end   
      
  it "should add an identical, immutable, free item" do
    assert_line_item_count(2)
    assert_line_item_present(eligible_product.name, unit_price: undershirt_amount, unit_price: eligible_product.price, immutable: false)
    assert_line_item_present(eligible_product.name + " - (Buy One Get One)", unit_price: 0.00, immutable: true)
    assert_order_total(eligible_product.price)
  end
end

Of course you’d want to test all the cases we’ve implemented, but what’s worth focusing on is the ability to assert specific attributes across many different line items. This is an extremely reusable tool to have in your testing suite. Good luck implementing!

Little Spree Big Performance Problems

2013-08-05T00:00:00+00:00

Recently I worked on an online food store serving an area with very little infrastructure. As a result, the orders tended to be really big with lots of products.

The website worked in the following environment:

Ruby 1.9.2
Spree 0.60
Heroku, Bamboo stack
PostgreSQL 9.2.4

H12 timeout errors

The performance problems started when we migrated Bamboo to Cedar on Heroku and replaced Thin webserver with Unicorn. We started getting a lot of Heroku Request timeout errors - H12:

The problems happened mostly when logging in to admin dashboard or during the checkout for the certain orders. H12 errors occur when a HTTP request takes longer than 30 seconds to complete. For example, if a Rails app takes 35 seconds to render the page, the HTTP router returns a 503 after 30 seconds and abandons the incomplete Rails request for good. The Rails request will keep working and logging the normal errorless execution. After completion, the request will indefinitely hang in the application dyno.

We started debugging H12: we set Unicorn timeout to 20 seconds to prevent the runaway requests and installed the rack-timeout gem with the timeout of 10 seconds to raise an error on a slow request. It all came down to a trivial database timeout!

The application source has not changed during the transition from Bamboo to Cedar, but apparently Cedar/Unicorn is much more sensitive to the troubled code. Below is the list of performance bottlenecks and solutions in Spree. Some of them exist in version 0.60 only, but a lot of them are still present in Spree 1.x, which means that your application may have them too.

Issue #1: Real-time reports

Let’s take a closer look at the earlier database timeout code. It came from Admin Dashboard and admin/overview_controller.rb.

The “Best Selling variants" report was being calculated real-time right in the web process:

def best_selling_variants
  li = LineItem.includes(:order).
      where("orders.state = 'complete'").
      sum(:quantity, :group => :variant_id, :limit => 5)
  ...
end

Record counts in the database are large enough to crash the application on Heroku with the database timeout:

irb(main):001:0> LineItem.count
=> 162279
irb(main):002:0> Order.count
=> 13027
irb(main):003:0> Variant.count
=> 14418

Other reports on the Dashboard experience the same problem. They would cause the timeout in turns when logging into Admin:

top_grossing_variants
best_selling_taxons
last_five_orders
biggest_spenders

Solution

Fortunately, in Spree 1.x the internal reporting system has been replaced with Jirafe:

If switching to Spree 1.x is not an option, another way is to move the calculation into a background job, using, for example, delayed_job gem and Heroku Scheduler Addon:

task :statistics => :environment do
  Delayed::Job.enqueue StatisticsJob.new
end

Issue #2: Large numbers

It is an established fact that humans eat a lot! Think about an order of a thousand Heineken 6-pack cans…

Or even something like this:

or this:

Spree, both 0.60 and 1.x, proved to have a huge problem if an order has a lot of line items and/or a large quantity of single line items. The potentially dangerous code can be found all over the place. Consider the following example:

class InventoryUnit < ActiveRecord::Base
  def self.destroy_units(order, variant, quantity)
    variant_units = order.inventory_units.group_by(&:variant_id)[variant.id].sort_by(&:state)
    quantity.ceil.times do
      inventory_unit = variant_units.shift
      inventory_unit.destroy
    end
  end
end

Now imagine what will happen with the order from the first screenshot. We have 15100 inventory units for that one. They will be meticulously destroyed from the inventory one by one in a loop after the checkout. This method was born to crash the application!

Solution

A simple mindful refactoring was enough to solve the problem for me. There is no need to call “destroy” in the loop for every single inventory unit because we can use the efficient “destroy_all” method. I’m sure this can be optimized further, but it was enough to get rid of the timeout:

def self.destroy_units(order, variant, quantity)
  variant_units = order.inventory_units.
    group_by(&:variant_id)[variant.id].
    sort_by(&:state)
  variant_units = variant_units.shift(quantity.ceil)
InventoryUnit.
    where(:order_id => order.id,:variant_id => variant.id).
    order('state asc').limit(quantity.ceil).
    destroy_all
end

Issue #3: Real-time emails

All emails in Spree are sent in real-time.

class Order < ActiveRecord::Base
  def finalize!
    ...
    OrderMailer.confirm_email(self).deliver
    ...
  end
end

Why is it bad? Let’s look at the following example from my application:

def confirm_email(order)
  attachments["invoice.pdf"] = {
    'Content-type' => 'application/pdf',
    :content => OrderInvoice.new.to_pdf(order)}

  mail(:subject  => 'Order #' + order.number,
       :from   =>    Spree::Config[:order_from],
       :to => order.email)
end

In my application “confirm_email” was overridden and generated the PDF invoice. The invoice listed all the products in the order and had about 200 lines in it. Again, it lead to the H12 timeout error.

Solution

All emails should be sent in the background rather than in the web request. First, because network operations can take a long time, and second, because generating an email can also be slow. For example, sending in the background can be accomplished using delayed_job gem:

OrderMailer.delay.confirm_email(self)

Issue #4: Lazy-loading

Ecommerce objects are usually complicated with a lot of associations. This is totally fine as long as you eager-load the associations that will be used most with the loaded object later on. In most cases, Spree does not preload associations for its orders. For example, in spree/base_controller.rb:

@order = Order.find_by_number! params[:order_id]

As the result, here is what I see in server console while loading the order display page on the frontend:

…And five more screens like this! The associations of the order — line items, variants and products — generate an additional chain of queries to the database during lazy-loading.

Solution: Eager-loading

If I modify the line from the controller like this…

@order = Order.where(:number => params[:order_id])
         .includes(:line_items => {:product => :taxons, :variant => [:product, :option_values]})
         .includes(:adjustments).first

…SQL queries will shrink down to this:

Eager-loading did the trick. Of course, not everything needs to be loaded eagerly, and the solution varies from case to case. It worked like charm in my case.

Issue #5: Dangerous code all over the place

There a lot of places in the Spree source code that are not optimized for performance. We don’t need to look far for an example, because there is another killer method right near the “destroy_units” one we inspected earlier!

class InventoryUnit < ActiveRecord::Base
  def self.create_units(order, variant, sold, back_order)
    shipment = order.shipments.detect {|shipment| !shipment.shipped? }
    sold.ceil.times {
      order.inventory_units.create(:variant => variant, :state => "sold", :shipment => shipment)
    }
    back_order.ceil.times {
      order.inventory_units.create(:variant => variant, :state => "backordered", :shipment => shipment)
    }
  end
end

And then:

order.line_items.each do |line_item|
  back_order = determine_backorder(order, variant, quantity)
  sold = quantity - back_order
  create_units(order, line_item.variant,  sold, back_order)
end

I received a timeout either in the “sold” or the “backorder” loop, but there wasn’t a time when I didn’t receive a timeout!

Solution

def self.create_units(order, variant, sold, back_order)
  shipment = order.shipments.detect {|shipment| !shipment.shipped? }
  values = sold.ceil.times.to_a.map { "(#{order.id},#{variant.id},'sold',#{shipment.id})" } +
    back_order.ceil.times.to_a.map { "(#{order.id},#{variant.id},'backordered',#{shipment.id})" }
  values.in_groups_of(500, false) do |group|
    InventoryUnit.connection.execute("INSERT INTO inventory_units(order_id, variant_id, state, shipment_id) VALUES #{group.join(',')}")
  end
end

Another example: every line item has the after_create and after_save callbacks. The callback invokes the Order.update! method. Order.update! method calls update_totals method…twice throughout the method.

def update_totals
  self.payment_total = payments.completed.map(&:amount).sum
  self.item_total = line_items.map(&:amount).sum
  self.adjustment_total = adjustments.map(&:amount).sum
  self.total = item_total + adjustment_total
end

Now imagine the order from the second screenshot with a lot of line items. During the checkout “update_totals” will be called each time the line item is saved. Typically, this line would produce a timeout, because the “line_items” association was, of course, not preloaded:

line_items.map(&:amount).sum

I couldn’t list every circumstance like that, because it would require a lot of context to explain the catch, but I can still say many times …

No long-running tasks in the web request!

Be it Spree, Heroku, or any other context, environment or platform, please, never do the following in the web process:

(!!!) Heavy database usage (slow or numerous queries, N+1 queries)
Sending an email
Accessing a remote API (posting to Twitter, querying Flickr, etc.)
Rendering an image or PDF
Heavy computation (computing a fibonacci sequence, etc.)

Say “No” to all these things to ensure a much happier life for your application!

Spree’s New Release Policy

2013-06-17T00:00:00+00:00

Spree has recently updated its documentation regarding contributions and has included (maybe for the first time?) an official Release Policy. This is an important step forward for the Spree community so that developers can communicate to clients the potential costs and benefits when upgrading Spree, understand how well Spree supports older releases, and gauge the overall speed of the “upgrade treadmill”.

Deprecation Warnings

Deprecation warnings are to be added in patch releases (i.e. 2.0.2) and the code being deprecated will only be removed in minor versions. For example, if a deprecation warning is added in 2.0.2, 2.0.3 will still contain the same deprecation warning but in 2.1.0 the deprecation warning and the code will be gone.

Deprecation warnings are very helpful for developers, but without a robust test suite exercising your application, it’s easy for deprecation warnings to go unnoticed. A strong test suite coupled with deprecation warnings helps you manage your client’s expectations about how upgrades can affect your Spree customizations and extensions.

Master Branch Receives All Patches

Master branch receives all patches, including new features and breaking API changes (with deprecation warnings, if necessary).

No surprises here; the master branch is for developers and should not be used for production. If you think you’ve encountered a bug in Spree, make sure to create a failing test against master to make sure it hasn’t be resolved by any existing patches. Read more about filing an issue for additional details.

Current Stable Release Branch

One branch “back” from master (currently 2-0-stable) receives patches that fix all bugs, and security issues, and modifications for recently added features (for example, split shipments). Breaking API changes should be avoided, but if unavoidable then a deprecation warning MUST be provided before that change takes place.

Continuing Spree’s history of very aggressive refactoring, breaking API changes are permitted in the current stable branch. If you’re looking for a truly stable release of Spree, you’ll need to look back two stable branches behind master.

Two Releases Behind Master

Two branches “back” from master (currently 1-3-stable) receives patches for major and minor issues, and security problems. Absolutely no new features, tweaking or API changes.

In my opinion, this is the only branch that should be considered for use in production. With the API locked down and a greater chance of most bugs worked out while it was the current release branch, the “two-back” stable branch is a safe bet that’s going to have the most up-to-date feature set.

Three and Four Releases Behind Master

Three branches back from master (currently 1-2-stable) receives patches for major issues and security problems. The severity of an issue will be determined by the person investigating the issue. Absolutely no features, tweaking or API changes. Four branches and more “back” from master (currently 1-1-stable and lesser) receive patches only for security issues, as people are still using these branches and may not be able to or wish to upgrade to the latest version of Spree.

It’s nice to see a fairly strong commitment to accepting security patches, although if we look at this in absolute terms, the 1.1.x release was put into security-patches-only mode after just 13 months. Considering that the 1-1-stable branch is 2,127 commits behind the 1-3-stable branch (!!), it’s clear that Spree is now formalizing it’s very aggressive release culture.

Managing the Upgrade Treadmill

As stated previously, a strong test suite is the best tool available to be able to determine what upstream updates affect your Spree customizations. Coupled with deprecation warnings, it becomes a fairly straight-forward process for identifying breaking changes, creating estimates for fixes, and communicating these costs to clients. Following the stated guides for customizing Spree is also recommended. When visiting the Spree guides section on customization, you’ll first be taken to the sub-section for authentication. Make sure to expand the Customization menu on your left to see additional guidance for customizing internationalization, views, JavaScript, stylesheet and image assets, business logic, and checkout.

Another important suggestion helpfully submitted by my colleague Mike Farmer was to never simply add gem ‘spree’ to your Gemfile. You should be very conscious about what version of Spree you want to use, and make sure you specify it in your Gemfile.

Company Presentation: Ecommerce as an Engine

2012-09-14T00:00:00+00:00

Today, I gave the presentation to my coworkers entitled “Puppies & Ecommerce as an Engine”. The presentation is strongly coupled with my work on Piggybak, and includes a discussion of traditional ecommerce platforms versus a lightweight ecommerce approach through modularity (Rails Engine). It also provides some code examples as how this does work in Piggybak.

Below are a few more related articles to my work on Piggybak. Check them out!

Developing a Spree Application

2012-06-15T00:00:00+00:00

Mike Farmer presented one of the projects he worked on. He gave us a very detailed overview of integration of a Spree application into Facebook for a large client.

He also described the changes that were made in the Spree project to customize it to the client’s needs.

The most interesting thing in this Spree shop usage is that the company’s clients make extensive use of the admin panel and they can sell their own products for other clients.

Mike showed us a great overview of writing better Rails applications using better object oriented code along with TDD and extensive SASS usage. He also described the great tools he uses including Screen and Vagrant.

Mike also talked about the things he learned during working on this project, especially about Spree and Ruby.

Multi-store Architecture for Ecommerce

2012-02-29T00:00:00+00:00

Something that never seems to go out of style in ecommerce development is the request for multi-site or multi-store architecture running on a given platform. Usually there is interest in this type of setup to encourage build-out and branding of unique stores that have shared functionality.

A few of Backcountry.com’s stores driven by a multi-store architecture, developed with End Point support.

End Point has developed several multi-store architectures on open source ecommerce platforms, including Backcountry.com (Interchange/Perl), College District (Interchange/Perl), and Fantegrate (Spree/Rails). Here’s an outline of several approaches and the advantages and disadvantages for each method.

Option #1: Copy of Code Base and Database for Every Site

This option requires multiple copies of the ecommerce platform code base, and multiple database instances connected to each code base. The stores could even be installed on different servers. This solution isn’t a true multi-store architecture, but it’s certainly the first stop for a quick and dirty approach to deploy multiple stores.

The advantages to this method are:

Special template logic doesn’t have to be written per site — the templates would simply follow the ecommerce platform’s template pattern.
Relative to Option #3 described below, no custom database development is required.
Custom business logic may be more easily applied to a set of the stores, without affecting the other stores.

The disadvantages to this method are:

Maintenance of the applications can be time consuming, as changes must be applied to all instances.
Custom changes must be applied to all multi-store instances.
Users and administrator accounts are not shared across multiple stores.

Option #2: Single Code Base, Single Database

In this method, there is one copy of the source code that interacts with one database. The single database would be modified to contain a store specific id per product, order, and peripheral tables. The code base would also have to be modified to be able to limit the visible products described here. In this method, the individual store may be identified by the domain or subdomain. With this method, there may also be code customization that allows for custom templates per store.

The advantages to this method are:

Relative to Option #1, maintenance for one code base is relatively simple.
User and administrator accounts are shared across multiple stores.
Super administrators may view and manage data from one backend administrative interface.

The disadvantages to this method are:

Rights and role management can be complicated.
Development is required for code and database customization.
Development is required for coding to handle flexible templating across stores.

A second option in multi-store architecture may use a data model with store specific entries in various tables, described here.

Option #3: Single Code Base, Single Database with Schemas or Views Per Store

In this method, there is one copy of the source code that interacts with a database that has views specific to that store, or a schema specific to that store. In this case, the code base would not necessarily need customization since the data model it accesses should follow the conventions of the ecommerce platform. However, moderate database customization is required in this method. With this method, there may also be code customization that allows for custom templates per store.

The advantages to this method are:

Relative to Option #1, maintenance for one code base is relatively simple.
Relative to option #2, code base changes are minimal.
User accounts may or may not be shared across stores.
Relative to option #2, there may be a potential performance gain by removing time spent limiting data to the current store instance.

The disadvantage to this method is:

Customization and development is required for database configuration and management of multi-store database schemas.

A tangential variation on the methods above are two different codebases and functionality attached to one back-end web service and backing database, such as the architecture we implemented for Locate Express. And a similar tangential variation I’ve investigated before is one that might use a Sinatra driven front-end and a Rails backed admin, such as RailsAdmin used in Piggybak.

College District has a collection of stores driven by a multi-store architecture, developed with End Point support.

Conclusion

In most cases for our clients, there is cost-benefit analysis that drives the decision between the three options described above. Option #1 might be an acceptable solution for someone interested in building out two or three stores, but the latter two options would be more suitable for someone interested in spinning up many additional instances quickly with lower long term maintenance costs.

Rails Request-Based Routing Constraints in Spree

2011-12-21T00:00:00+00:00

I recently adopted an unreleased ecommerce project running Spree 0.60.0 on Rails 3.0.9. The site used a Rails routing constraint and wildcard DNS to dynamically route subdomains to the “dispatch” action of the organizations_controller. If a request’s subdomain component matched that regular expression, it was routed to the dispatch method. Here’s the original route:

match '/' => 'organizations#dispatch', :constraints => { :subdomain => /.+/ }

The business requirement driving this feature was that a User could register an Organization by submitting a form on the site. Once that Organization was marked “approved” by an admin, that Organization would become accessible at their own subdomain—no server configuration required.

For marketing reasons, we decided to switch from subdomains to top-level subdirectories. This meant RESTful routes (e.g. domain.com/organizations/143) wouldn’t cut it. In order to handle this, I created a routing constraint class called OrgConstraint. This routing constraint class works in tandem with a tweaked version of that original route.

match '*org_url' => 'organizations#show', :constraints => OrgConstraint.new

The :constraints param takes an instance of a class (not a class name) that responds to a matches? predicate method that returns true or false. If matches? returns true, the request will be routed to that controller#action. Else, that route is treated like any other non-matching route. Here’s the entire OrgConstraint class:

class OrgConstraint
  def matches?(request)
    Organization.valid_url? request.path_parameters[:org_url]
  end
end

Note how Rails automatically passes the request object to the matches? method. Also note how the relative url of the request is available via the :org_url symbol-the same identifier we used in the route definition. The Organization.valid_url? class method encapsulates the logic of examining a simple cached (via Rails.cache) hash consisting of organization urls as keys and true as their value.

The final step in this process is, of course, the organizations_controller’s show method. It now needs to look for that same :org_url param that the route definition creates, in the standard params hash we all know and love:

def show
  @organization = Organization.find(params[:id]) if params[:id]  
  # from routing constraint
  @organization ||= Organization.find_by_url(params[:org_url]) if params[:org_url]  
  ...
end

I should point out that Rails instantiates exactly one instance of your routing constraint class when it first loads your routes. This means you’ll want to ensure your class’s design will respond appropriately to changes in any underlying data. This is one of the reasons the Organization class caches the {$org_url => true} hash rather than using instance variables within the OrgConstraint class.

Paperclip in Spree: Extending Product Image Sizes

2011-06-06T00:00:00+00:00

Spree uses the popular gem Paperclip for assigning images as attachments to products. The basic installation requires you to install the gem, create a migration to store the paperclip-specific fields in your model, add the has_attached_file information to the model with the attachment, add the ability to upload the file, and display the file in a view. In Spree, the Image model has an attached file with the following properties:

class Image < Asset
  ...
  has_attached_file :attachment,
                    :styles => { :mini => '48x48>',
                      :small => '100x100>',
                      :product => '240x240>',
                      :large => '600x600>'
                    },
                    :default_style => :product,
                    :url => "/assets/products/:id/:style/:basename.:extension",
                    :path => ":rails_root/public/assets/products/:id/:style/:basename.:extension"
  ...
end

As you can see, when an admin uploads an image, four image sizes are created: large, product, small, and mini.

Four images are created per product image uploaded in Spree (Note: not to scale).

Last week, I wanted to add several additional sizes to be created upon upload to improve performance. This involved several steps, described below.

Step 1: Extend attachment_definitions

First, I had to override the image attachment styles, with the code shown below. My application is running on Spree 0.11.2 (Rails 2.3.*), so this was added inside the extension activate method, but in Rails 3.0 versions of Spree, this would be added inside the engine’s activate method.

Image.attachment_definitions[:attachment][:styles].merge!(
      :newsize1 => '200x200>',
      :newsize2 => '284x284>'
)

Step 2: Add Image Helper Methods

Spree has the following bit of code in its base_helper.rb, which in theory should create methods for calling each image (mini_image, small_image, product_image, large_image, newsize1_image, newsize2_image):

Image.attachment_definitions[:attachment][:styles].each do |style, v|
    define_method "#{style}_image" do |product, *options|
      options = options.first || {}
      if product.images.empty?
        image_tag "noimage/#{style}.jpg", options
      else
        image = product.images.first
        options.reverse_merge! :alt => image.alt.blank? ? product.name : image.alt
        image_tag image.attachment.url(style), options
      end
    end
  end

But for some reason in this application, perhaps based on order of extension evaluation, this was only applied to the original image sizes. I remedied this by adding the following code to my extension base helper:

  [:newsize1, newsize2].each do |style|
    define_method "#{style}_image" do |product, *options|
      options = options.first || {}
      if product.images.empty?
        image_tag "noimage/#{style}.jpg", options
      else
        image = product.images.first
        options.reverse_merge! :alt => image.alt.blank? ? product.name : image.alt
        image_tag image.attachment.url(style), options
      end 
    end 
  end

Step 3: Create Cropped Images for Existing Images

Finally, instead of requiring all images to be re-uploaded to create the new cropped images, I wrote a quick bash script to generate images with the new sizes. This script was placed inside the RAILS_ROOT/public/assets/products/ directory, where product images are stored. The script iterates through each existing directory and creates cropped images based on the original uploaded image with the ImageMagick command-line tool, which is what Paperclip uses for resizing.

#!/bin/bash

for i in `ls */original/*`
do
    image_name=${i#*original\/}
    dir_name=${i/\/original\/$image_name/}
    mkdir $dir_name/newsize1/ $dir_name/newsize2/
    convert $i -resize '200x200' $dir_name/newsize1/$image_name
    convert $i -resize '284x284' $dir_name/newsize2/$image_name
    echo "created images for $i"
done

Step 4: Update Views

Finally, I added newsize1_image and newsize2_image methods throughout the views, e.g.:

<%= link_to newsize1_image(product), product %>
<%= link_to newsize2_image(taxon.products.first), seo_url(taxon) %>

Conclusion

It would be ideal to remove Step 2 described here by investigating why the image methods are not defined by the Spree core BaseHelper module. It’s possible that this is working as expected on more recent versions of Spree. Other than that violation of the DRY principle, it is a fairly simple process to extend the Paperclip image settings to include additional sizes.

Spree Performance Benchmarking

2011-05-25T00:00:00+00:00

I see a lot of questions regarding Spree performance in the spree-user group, but they are rarely answered with metrics. I put together a quick script using the generic benchmark tool ab to review some data. Obviously, the answer to how well a site performs and scales is highly dependent on the host and the consumption of the web application, so the data here needs to be taken with a grain of salt. Another thing to note is that only two of the following use cases are running on Rails 3.0 — many of our current Spree clients are on Spree 0.11.2 or older. I also included one non-Spree Rails ecommerce application, in addition to a few non-Rails applications for comparison. All of the tests were run from my home network, so in theory there shouldn’t be bias on performance tests for sites running on End Point servers.

	ab -n 100
	-c 2 homepage	-c 20 homepage	-c 2 product page	-c 20 product page
Client #1 Spree: 0.11.2 Hosting: 4 cores, 512 GB RAM DB: MySQL # Products: <100	7.49	24.75	6.49	19.87	Requests per second
266.889	808.041	307.997	1006.552	Time per request (ms)
Client #2 Spree 0.11.2 Hosting: Engineyard, medium instance DB: MySQL # Products: 100s	5.32	20.28	5.36	18.03	Requests per second
375.713	986.309	373.289	1109.524	Time per request (ms)
Client #3 Spree: 0.9.0 Hosting: 4 cores, 1 GB RAM DB: PostgreSQL # Products: <100	4.91	25.39	1.98	6.54	Requests per second
407.135	787.782	1011.875	3060.062	Time per request (ms)
(Former) Client #4 Spree: 0.11.2 Hosting: Unknown DB: PostgreSQL # Products: >5000	20.69	8.84	10.15	19.28	Requests per second
96.673	2262.105	196.996	1037.146	Time per request (ms)
Client #5 Spree: 0.11.2 Hosting: EngineYard, small instance DB: MySQL # Products: 1	12.28	16.23	N/A	N/A	Requests per second
162.909	1231.945	N/A	N/A	Time per request (ms)
Client #6 Spree: 0.40 Hosting: 4 cores, 1 GB RAM DB: MySQL # Products: 50-100	3.61	8.93	2.96	3.06	Requests per second
553.569	2240.657	675.306	6539.433	Time per request (ms)
SpreeDemo Spree: Edge Hosting: Heroku, 2 dynos DB: Unknown # Products: 100s	8.17	12.79	4.7	5.48	Requests per second
244.831	1563.642	425.27	3652.927	Time per request (ms)
Client #7 *custom Rails ecommerce app Hosting: 1.0 GB RAM DB: MySQL # Products: 1000s	5.43	29.8	4.45	23.14	Requests per second
368.409	671.082	448.962	864.24	Time per request (ms)
Interchange Demo Hosting: 4 cores, 2 GB RAM DB: MySQL # Products: >500	7.41	55.27	7.5	13.93	Requests per second
269.942	361.875	266.492	1435.51	Time per request (ms)
Client #8 *PHP site, serves fully cached pages with nginx with no app server or db hits Hosting: 4 cores, 4 GB RAM	10.81	30.54	6.05	9.87	Requests per second
184.994	654.858	330.727	2027.092	Time per request (ms)
Magento Demo Hosting: Unknown DB: Unknown # Products: 100s	4.26	44.85	2.68	36.29	Requests per second
469.831	445.931	745.472	551.11	Time per request (ms)

Here’s the same data in graphical form:

Requests per Second

Time Per Request (ms)

We expect to see high performance on some of the sites with significant performance optimization. On smaller VPS, we expect to see the the server choke with higher concurrency.

ActiveProduct — Just the Spree Products

2011-03-28T00:00:00+00:00

ActiveProduct

I wanted to see how difficult it would be to cut out the part of Spree that makes up the product data model and turn it into a self sufficient Rails 3 engine. I followed the tutorial here to get started with a basic engine plugin. Since it sounded good and nobody else seems to be using it, I decided to call this endeavor ActiveProduct.

Which Bits?

The next step was to decide which parts I needed to get. Minimally, I need the models and migrations that support them. If that works out, then I can decide what to do about the controllers and views later.

That said, the lines between what is needed to create a product and the rest of the system are not always so clear cut. You have to cut somewhere, though, so I cut like this:

Image
InventoryUnit
OptionType
OptionValue
ProductGroup
ProductOptionType
ProductProperty
Product
ProductScope
Property
Prototype
Variant

Models

Each of these has a model file in spree/core/app/models, which I just copied over to the app/models directory of my engine.

Migrations

It’d be convenient if I could have just carved the appropriate parts out of the schema.rb file for the migration. But said file does not appear to be in evidence. Building a spree instance, and trying to coerce one out of it just seems too annoying, so I did something else.

I started from the first migration, removed all of the table definitions that didn’t interest me and manually applied all of the migrations in the migration file to the remaining definitions. By manually applied, I mean I went through each migration file one at a time and made the specified change to the original set of definitions. There are, of course, all kinds of reasons why this is a terrible idea. For a reasonably small set of tables with a simple set of relations, the trade-off isn’t too bad.

Migration Generator

With a single migration in hand, I followed the tutorial at here as a guide to create a generator for it in the engine. With the migration set up as a generator, I went to my sandbox rails app and ran the migration by doing the following:

$ rails g active_product create_migration_file
$ rake db:migrate

Did it Work?

At this point, I had some the tables in the database and the model files in place it was time to see if things worked.

$ rails console
rb(main):001:0> p = Product.new

…and I got a big wall of error messages. So I could not even instantiate the class, much less start using it. Well, I kind of expected that.

Missing Constants

Following the error messages started with an unresolved dependency on delegate_belongs_to. A little sleuthing lead me into the Spree lib directory were a copy of this plugin lives. Some further knocking around the interwebs lead me to this project which appears to be the canonical version of the plugin. Since I was trying to create a stand alone module, I wanted set this up as an external dependency (which I will defer figuring out how to enforce in the engine until later).

As an aside, (the newer version of) delegate_belongs_to has an issue with and API change in ActiveRecord for Rails 3. A version that will at least load with ActiveProduct can be found here.

The active_product engine currently assumes that delegates_belongs_to is available in the project that it is installed in. I set it up as a normal plugin in the vendor/plugins directory.

Circular Dependencies

With that out of the way, the next error seemed to be about Variants and Scope. In spree/core/lib/scopes there are a couple of files that interact with the Product and Variant classes in a somewhat messy way. In order to make use of the scopes that are defined there, I needed to pull them in. Ultimately, it probably makes sense to include the changes directly into the affected class files. Since I was still experimenting here, I just moved them to approximately the same place in the engine.

It turns out that the dependency relationships between Product, Variant, and the Scopes module are pretty complex. I spent a fair amount of time trying to sort them out manually, but was unable to find any reasonable way. Eventually, I decided to give up and fall back on the auto loader to handle it for me.

The auto-loader in Rails seems to cover a multitude of sins. A well behaved independent module will need to remove all of these interdependencies. There are a couple of significant problems with leaving them be:

Other potential users of such a module will not necessarily make sure that everything is auto-loaded, so a this module would just be broken. Sinatra comes to mind.
Interdependencies increase complexity. While complexity is not inherently bad, it can be a source of bugs and errors, so it ought to be avoided when possible.

To start with, I moved the scope.rb file and the scope directory to active_product/lib/auto. And I added the following to the ActiveProduct module definition in active_product/lib/active_product/engine.rb:

module ActiveProduct
  class Engine < Rails::Engine
    config.autoload_paths += %W(#{config.root}/lib/auto)

There are two interesting things about this to note:

The engine lib directory is not auto-loaded in the same way that app/models, app/controllers, etc are. There apparently is no convention for loading a lib directory. I picked ‘lib/auto’, but there are not any constraints on what can be added.
The engine has its own config variable that is loaded and honored as part of the Rails app config.

Now What?

Now when I tried to instantiate the class I found that it called a couple of methods that I’m not quite sure what I am going to do with yet. These are:

make_permalink
search_methods

make_permalink is provided by an interestingly named Railslove module in the spree_core lib and seems harmless enough. For now, I commented the call out of the Product lib.

search_methods is provided by the MetaSearch plugin which is a Spree dependency. Search is neat, but I’ll sort it out later. Again, I commented it out and will deal with it if it causes problems.

Where are we now

I can now instantiate a new product object from the console. That seems to somewhat validate the effort to isolate the module. You may be tempted to ask if you could use that product instance for anything; saving a copy to the data store, for instance. Here’s a hint: circular dependencies.

The code that I’ve worked on up till now can be seen here.

A Ruby on Rails Tag Cloud Tutorial with Spree

2011-03-07T00:00:00+00:00

A tag cloud from a recent End Point blog post.

Tag clouds have become a fairly popular way to present data on the web. One of our Spree clients recently asked End Point to develop a tag cloud reporting user-submitted search terms in his Spree application. The steps described in this article can be applied to a generic Rails application with a few adjustments.

Step 1: Determine Organization

If you are running this as an extension on Spree pre-Rails 3.0 versions, you’ll create an extension to house the custom code. If you are running this as part of a Rails 3.0 application or Spree Rails 3.0 versions, you’ll want to consider creating a custom gem to house the custom code. In my case, I’m writing a Spree extension for an application running on Spree 0.11, so I create an extension with the command script/generate extension SearchTag.

Step 2: Data Model & Migration

First, the desired data model for the tag cloud data should be defined. Here’s what mine will look like in this tutorial:

Next, a model and migration must be created to introduce the class, table and it’s fields. In Spree, I run script/generate extension_model SearchTag SearchRecord and update the migration file to contain the following:

class CreateSearchRecords < ActiveRecord::Migration
  def self.up
    create_table :search_records do |t|
      t.string :term
      t.integer :count, :null => false, :default => 0
    end
  end

  def self.down
    drop_table :search_records
  end
end

I also add a filter method to my model to be used later:

class SearchRecord < ActiveRecord::Base
  def self.filter(term)
    term.gsub(/\+/, ' ')
      .gsub(/\s+/, ' ')
      .gsub(/^\s+/, '')
      .gsub(/\s+$/, '')
      .downcase
      .gsub(/[^0-9a-z\s-]/, '')
  end
end

Step 3: Populating the Data

After the migration has been applied, I’ll need to update the code to populate the data. I’m going to add an after filter on every user search. In the case of using Spree, I update search_tag_extension.rb to contain the following:

def activate
  Spree::ProductsController.send(:include, Spree::SearchTagCloud::ProductsController)
end

And my custom module contains the following:

module Spree::SearchTagCloud::ProductsController
  def self.included(controller)
    controller.class_eval do
      controller.append_after_filter :record_search, :only => :index
    end
  end

  def record_search
    if params[:keywords]
      term = SearchRecord.filter(params[:keywords])
      return if term == ''
      record = SearchRecord.find_or_initialize_by_term(term)
      record.update_attribute(:count, record.count+1)
    end
  end
end

The module appends an after filter to the products#index action. The after filter method cleans the search term and creates a record or increments the existing record’s count. If this is added directly into an existing Rails application, this bit of functionality may be added directly into one or more existing controller methods to record the search term.

Step 4: Reporting the Data

To present the data, I create a controller with script/generate extension_controller SearchTag Admin::SearchTagClouds first. I update config/routes.rb with a new action to reference the new controller:

map.namespace :admin do |admin|
  admin.resources :search_tag_clouds, :only => [:index]
end

And I update my controller to calculate the search tag cloud data, shown below. The index method method retrieves all of the search records, sorts, and grabs the the top x results, where x is some configuration defined by the administrator. The method determines the linear solution for scaling the search_record.count to font sizes ranging from 8 pixels to 25 pixels. This order of terms is randomized (.shuffle) and linear equation applied. This linear shift can be applied to different types of data. For example, if a tag cloud is to show products with a certain tag, the totals per tag must be calculated and scaled linearly.

class Admin::SearchTagCloudsController < Admin::BaseController
  def index
    search_records = SearchRecord.all
      .collect { |r| [r.count, r.term] }
      .sort
      .reverse[0..Spree::SearchTagCloud::Config[:count]]
    max = search_records.empty? ? 1 : search_records.first.first

    # solution is: a*x_factor - y_shift = font size
    # max font size is 25, min is 8
    x_factor = (Spree::SearchTagCloud::Config[:max] -
      Spree::SearchTagCloud::Config[:min]) / max.to_f
    y_shift = max.to_f*x_factor - Spree::SearchTagCloud::Config[:max]

    @results = search_records.shuffle.inject([]) do |a, b|
      a.push([b[0].to_f*x_factor - y_shift, b[1]])
      a
    end
  end
end

The data is presented to the user in the following view:

<h3>Tag Cloud:</h3>
<div id="tag_cloud">
<% @results.each do |b| %>
<span style="font-size:<%= b[0] %>px;"><%= b[1] %></span>
<% end -%>
</div>

Step 5: Adding Flexibility

In this project, I added configuration variables for the total number of terms displayed, and maximum and minimum font size using Spree’s preference architecture. In a generic Rails application, this may be a nice bit of functionality to include with the preferred configuration architecture.

Example tag cloud from the extension. Additional modifications can be applied to change the overall styling or color of individual search terms.

Conclusion

These steps are pretty common for introducing new functionality into an existing application: data migration and model, manipulation on existing controllers, and presentation of results with a new or existing controller and view. Following MVC convention in Rails keeps the code organized and methods simple. In the case of Spree 0.11, this functionality has been packaged into a single extension that is abstracted from the Spree core. The code can be reviewed here, with a few minor differences.

Integrating the Estes Freight Shipping SOAP API as a Spree Shipping Calculator

Estes API Documentation

Ruby SOAP Client

Spree Shipping Calculators

Code Example

Conclusion

wroc_love.rb 2017 part 1

Kafka / Karafka by Maciej Mensfeld

Machine Learning to the Rescue by Mariusz Gil

Spree lightning talk by sparksolutions.co

The merchant login ID or password is invalid or the account is inactive, and to how to fix it in Spree

Summary

Spree Admin pages unreachable (500 errors)

Spree Commerce “invalid value for Integer(): "09"” in Spree​::Checkout​/update

The Issue

Octal Numbers

Solution

Create a sales functionality within Spree 2.3 using Spree fancy

Introduction

Set-up

Let’s create our app

Spree-ify our app

Extensions in 3.5 steps

Step 1: Update the Gemfile

Step 1.5: We’ve hit an error!

Step 2: Create a sales extension

Step 3: Adding a controller Action to HomeController

Let’s set a sale price for the variant

Decorate your variant

Deface overrides

Conclusion

Spree Authorization Failure for Customized Role

Enhancing the labelsontime.com Spree application

UPGRADING THE SPREE PLATFORM

USING SPREE GEMS

WHAT WE’RE WORKING ON NEXT

Spree Commerce, Take Care When Offering Free Shipping Promotion

Unable to Bcc in mail, Spree 2.0 Stable Rails 3.2.14

Spree Security Update 2.x.x Error, undefined method ‘assume_from_symbol’ for Money:Class (ActionView::Template::Error)

Spree Active Shipping Gem “We are unable to calculate shipping rates for the selected items.” Error

A Brief Retrospective of Spree

How to Dynamically Update A Spree Product’s Price Based on Volume Pricing

Step 1a: Create an array of the prices

Step 1b: Create to_range function for Strings & create a function to return lowest possible price per unit

Step 2: Load Your New Volume Pricing Array and Lowest Possible Price

Step3: Write JavaScript Code to Handle Quantity Changes

Buy One Get One Promotion with Spree

Promotion Eligibility

Adding a Custom Promotion Action

Pre-flight check

Buy One Get One Logic

Locked Line Items with Additional Text

Test Driving

Little Spree Big Performance Problems

H12 timeout errors

Issue #1: Real-time reports

Solution

Issue #2: Large numbers

Solution

Issue #3: Real-time emails

Solution

Issue #4: Lazy-loading

Solution: Eager-loading

Issue #5: Dangerous code all over the place

Solution

No long-running tasks in the web request!

Spree’s New Release Policy

Deprecation Warnings

Master Branch Receives All Patches

Current Stable Release Branch

Two Releases Behind Master

Three and Four Releases Behind Master

Managing the Upgrade Treadmill

Company Presentation: Ecommerce as an Engine

Developing a Spree Application

Multi-store Architecture for Ecommerce

Option #1: Copy of Code Base and Database for Every Site

Option #2: Single Code Base, Single Database

Option #3: Single Code Base, Single Database with Schemas or Views Per Store

Conclusion

Spree Commerce “invalid value for Integer(): "09"” in Spree::Checkout/update