The parent Ruby on Rails application must be on Rails 3.1.*. Piggybak has shown to be compatible with both Ruby 1.8 and Ruby 1.9. While it is not a requirement that the parent application be using RailsAdmin, it is a recommendtion. RailsAdmin depends on Devise for user authentication. CanCan is also used for authorization by RailsAdmin. It is highly recommended that you be familiar with RailsAdmin, Devise, and CanCan while working with Piggybak.

Installation is similar to installation of other Rails gems. First, install the gem by adding the following line to your Gemfile:

gem "piggybak"

Install the gem:

bundle install

Copy over migrations from the Piggybak gem to your application.

rake piggybak_engine:install:migrations

Apply the migrations. Note that Piggybak creates several tables that are not namespaced. They will fail if there is conflict in table names.

rake db:migrate

Mount the Engine to your config/routes.rb file. This may look like:

mount Piggybak::Engine => '/checkout', :as => 'piggybak'" to config/routes

The engine may be mounted anywhere without affecting it's functionality.

After installation, Piggybak has several integration points:

acts_as_variant

acts_as_variant can be added inside any ActiveRecord models in your application to make tha item become sellable. This results in a nested form for variant data in the admin interface.

acts_as_orderer

acts_as_orderer must be added to the Devise user model. This creates the Ruby on Rails association between user and orders.

<%= cart_form(@some_item) %>

The cart_form helper renders a basic add to cart form.

<%= cart_link %>

The cart_link helper displays a link with total number of items and price to the user's shopping cart.

<%= orders_link("Order History") %>

The orders_link helper renders a link to a logged in user's orders, with an argument to control the link anchor text.

<%= piggybak_track_order("Piggybak Demo") %>

The piggybak_track_order helper renders Google Analytics order tracking, with an argument to control the store name.

Piggybak views may be overridden to present custom appearances for the shopping cart, checkout, receipt, and order history pages. To do this, simply copy over views directly from the gem source into the primary application to mirror the directory structure.

Overridable views include:

• Add to cart form
• Items display (on cart, order, receipt)
• Cart page
• Address form on checkout page
• Order details partial
• Order list page
• Order receipt page
• Order submission page
• Order download text page
• Order email notification view

Looking for a few tips on integration in the parent application? Here they are.

Redirect After Log In and Log Out

The one page checkout has functionality to allow users to log in and log out. This must be coordinated in the parent application to handle redirects on log in and log out. Using Devise's callbacks for these actions, the following can be added to the ApplicationController to handle redirects.

before_filter :set_last_page
def set_last_page
  if !request.xhr? && !request.url.match(/users\/sign_in/) && !request.url.match(/users\/sign_out/)
    session[:return_to] = request.url
  end 
end 
def after_sign_in_path_for(resource_or_scope)
  session[:return_to] || root_url
end 
def after_sign_out_path_for(resource_or_scope)
  session[:return_to] || root_url
end 

CanCan Integration

Since the parent Ruby on Rails application introduces custom models, it also must make the decision on how to authorize Piggybak elements to users. Here's a basic setup which allows users with administrative rights access to the full set of Piggybak actions.

class Ability
  include CanCan::Ability
  def initialize(user)
    if user && # method for user has administrative rights
      can :access, :rails_admin
      can :manage, [ #Parent Application models
                    ::Piggybak::Variant,
                    ::Piggybak::ShippingMethod,
                    ::Piggybak::PaymentMethod,
                    ::Piggybak::TaxMethod,
                    ::Piggybak::State,
                    ::Piggybak::Country]

      # can't delete orders
      can [:email, :download, :cancel, :read, :create, :update, :history, :export], ::Piggybak::Order

      can :refund, ::Piggybak::Payment
    end
  end
end

What's on the road map for this gem? Here are the current priorities:

• Add testing support
• Move to ActiveSupport::Concern for acts-as-* method

The parent application can override Piggybak's configuration options with a standard config initializer.

Piggybak.config do |config|
  # Config attr_accessors are:
  # shipping_calculators
  # payment_calculators
  # tax_calculators
  # default_country
  # activemerchant_test mode

  # Add calculators with the following method
  config.shipping_calculators << "Pickup"

  # Or, Override calculatores with the following override
  config.payment_calculators = ["BeanstreamGateway"]

  # Override the default country
  config.default_country = "CA"

  # Override the activemerchant billing mode
  config.activemerchant_mode = :test
end