Home » Documentation

Documentation

The parent Ruby on Rails application must be on Rails 4.1 and Ruby 1.9.3 or newer. (Older versions of Rails and Ruby are supported in older versions of Piggybak.) 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.

Piggybak assumes that you already have a model User, which will connect with Devise. Devise will be installed via the Piggybak installation process, but you must have a model and migration in place for User.

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

Next, run the piggybak install command:

piggybak install

If you are using CanCan for Authorization in RailsAdmin, add the code below to your ability class to allow access to Piggybak's models. Refer to the demo source code for an example:

can :manage, Piggybak.config.manage_classes.map(&:constantize)
Piggybak.config.extra_abilities.each do |extra_ability|
  can extra_ability[:abilities], extra_ability[:class_name].constantize
end
								

After installation, Piggybak has several integration points:

acts_as_sellable 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_sellable

You may also need to make two changes to allow for the piggybak_sellable attributes to be accessible to your model depending on your application attribute settings. First, you may need to whitelist the piggybak_sellable_attributes in your model:

attr_accessible :piggybak_sellable_attributes

And you may also need to follow the RailsAdmin documentation to allow the piggybak_sellable fields to show up on your model's edit page. This can be accomplished by adding the specific field, or including all fields:

config.model YourModel do
  edit do
    #other fields
    include_all_fields
    # or field :piggybak_sellable
  end
end
								

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

acts_as_orderer

The cart_form helper renders a basic add to cart form.

<%= cart_form(@some_item) %>

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

<%= cart_link %>

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

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

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

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

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:

  • Testing support
  • Gift certificate support
  • Advanced variant support
  • Heroku support
  • Minor technical debt cleanup

The parent application can override Piggybak's configuration options with a standard config initializer. For an updated list of configuration options, view the config source code here.

Piggybak.config do |config|
  # 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

  # You may add additional order logging via the following configs
  # logging (defaults to false)
  # logging_file (defaults to /log/orders.log)

  # Other configuration options include:
  # activemerchant_mode
  # email_sender
  # order_cc
  # whois_url

  # The following options are advanced plugin configuration options:
  # line_item_types
  # secure_checkout
  # secure_prefix
  # extra_secure_paths
  # manage_classes
  # extra_abilities
end

Additional Support

Looking for support? You've come to the right place. Get in touch with support several ways:

End Point
Piggybak is sponsored and developed by End Point. End Point has over 15 years of ecommerce experience.

Questions or Comments?

Email the Piggybak Google Group or visit the GitHub repo today.