TB Checkout

TB Checkout is a shopping cart engine intended for use with Rails and Twice Baked. The goal of this engine is to make a drop-in tool for shopping carts and transaction management to your existing product database.

TB Checkout is not a full-fledged product management system. Instead, our goal is to make it easy for any of your existing ActiveRecord models to fit into the shopping cart and facilite transactions through a payment gateway.

Requirements

Checkout requires at minimum the following gems:

  • Rails 4
  • TB Core 1.2
  • Active Merchant 1.43

Payment Gateways

Those familiar with Active Merchant will know that it supports a wide variety of payment gateways. However, it should be noted that TB Checkout is currently being built and tested against Authorize.net.

More gateways may be added in the future, but we do not intend to cover them all. Pull requests adding support for a particular gateway are welcome.

Installation & Usage

First, it is recommended you run the steps listed in the "Installation/Usage" section of the TB Core README file. Then, perform the following steps:

  1. Add the following to your Gemfile

    gem 'tb_checkout'

  2. Run bundle install

  3. Copy in database migrations to your new rails project

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

  4. Restart your application

Configuration

TB Checkout accepts the following configuration options.

TbCheckout.configure do |config|
  config.gateway = ActiveMerchant::Billing::AuthorizeNetGateway.new({ ... })
  config.card_types = [:visa, :master, :discover, :american_express]
  config.layout = 'application'
  config.canada_is_real = true
  config.cart_lifespan = 3.days
end

gateway

An ActiveMerchant gateway. See the Active Merchant documentation for help creating a payment gateway.

card_types

An array of acceptable credit card types. Remove any types you do not wish to see in the payment form.

layout

The base view layout to be used for all user-facing views. The default value will inherit from your base ApplicationController configuration.

canada_is_real

Set to true or false in order to show/hide Canadian provinces in the billing address section of the payment form. Defaults true.

cart_lifespan

Configures how long a cart lives until it is marked as abandoned. NOTE: Carts are not actually marked as abandoned until

Purchasable Models

As stated earlier, TB Checkout is not a product management system. You are expected to build your own library of products, categorizations, and so on. Once you have a product model, making it eligible for the shopping cart is easy.

At minimum, a product must have a price decimal attribute and a description string attribute. You can add these columns to your model using the built-in migration method add_tb_checkout_purchasable. Or you could treat these as virtual attributes using instance methods.

class AddPurchasableToProducts < ActiveRecord::Migration
  def change
    add_tb_checkout_purchasable :products
  end
end

And in your model you should include the TbCheckout::Purchasable concern.

class Product < ActiveRecord::Base
  include TbCheckout::Purchasable
end

Model Configuration

The TbCheckout::Purchasable concern also addes a couple class methods for optional configuration.

class Product < ActiveRecord::Base
  include TbCheckout::Purchasable

  # Disable the quanitity picker in the shopping cart
  tb_checkout_quantity_is_editable false

  # Run this block after a transaction is captured
  tb_checkout_after_capture ->(instance){
    logger.debug 'My transaction was completed!'
  }

  # Alternatively, pass a method name as a symbol
  tb_checkout_after_capture :after_capture

  def after_capture(instance)
    logger.debug 'My transaction was completed!'
  end

  # Delete this object if it is removed from the shopping cart
  tb_checkout_delete_on_removal true

  # Use this helper method to generate a product page url
  tb_checkout_url_builder ->(instance, view){
    view.product_path(product)
  }

  # Configure a partial that you want to render in the shopping cart
  tb_checkout_cart_detail_view '/products/cart_view'
end

tb_checkout_quantity_is_editable

Pass false to remove the ability to modify quantities in the shopping cart. This is useful in situations where it only makes sense to purchase 1 quantity of something, i.e., making a donation.

tb_checkout_after_capture

Pass a lambda literal, or a symbol naming the method you wish to call. This hook will be called after a successful transation.

tb_checkout_delete_on_removal

Set to true if the object should be permanently deleted when it is removed from the shopping cart. This might make sense in a scenario where your purchasable objects are one-time use records, but not if your purchasable objects are reused across many carts. Defaults to false.

tb_checkout_url_builder

Pass a lambda literal, or a symbol naming the method you wish to call. This method will be called whenever we want to generate a URL to your product.

tb_checkout_cart_detail_view

Sometimes you want to render some custom HTML in the row of a shopping cart. This configuration allows you to point to a partial view file in your project. This partial will be passed an item local variable.

NOTE: This partial will only be rendered after a succesful checkout. In-progress carts will only render the product description.

View Helpers

The following helper methods are provided for convenience. See the Rdocs for the most up to date information regarding arguments and return values.

tb_checkout_current_cart

Returns the currently active shopping cart or nil if no cart is active.

<%= tb_checkout_cart_link() %>

Returns a link to the shopping cart.

tb_checkout_add_to_cart

<%= tb_checkout_add_to_cart(my_product) %>

Returns a button that, when clicked, adds a product to the shopping cart.