Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
297 lines (277 sloc) 14.4 KB
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head>
<meta http-equiv="Content-Script-Type" content="text/javascript" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1" />
<meta name="robots" content="index, follow" />
<meta name="keywords" content="" />
<meta name="title" content="Piggybak: A Mountable Ruby on Rails Ecommerce Solution" />
<meta name="description" content="" />
<title>Piggybak Documentation</title>
<link rel="shortcut icon" href="/favicon.ico" />
<!--CSS-->
<link rel="stylesheet" type="text/css" href="styles/site.css" media="screen" />
<!--Javascript-->
<script type="text/javascript" src="js/jquery-1.5.1.min.js"></script>
<script type="text/javascript" src="js/jquery.easing.1.3.js"></script>
<script type="text/javascript" src="js/tabs.js"></script>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-525312-15']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body>
<div id="wrapper">
<div id="wrapper-top">
<div class="container">
<div id="top">
<div id="logo" class="four columns">
<a href="index.html"><img height="60" src="images/piggybak.png" alt="Piggybak" /></a>
</div><!--#logo-->
<div id="nav" class="eight columns">
<ul id="topnav" class="sf-menu">
<li><a href="index.html">Home</a></li>
<li><a href="features.html">Features</a></li>
<li><a href="showcase.html">Showcase</a></li>
<li class="current"><a href="documentation.html">Documentation &amp; Support</a></li>
<li><a id="demo" href="demo_details.html">Visit the Demo</a></li>
</ul><!-- #topnav -->
</div><!--#nav-->
<div class="clearfix"></div>
</div><!--#top-->
</div><!--container-->
</div><!--#wrapper-top-->
<div id="wrapper-beforeheader">
<div class="container">
<div id="sn" class="six columns">
</div><!--#sn-->
<div id="toptext" class="six columns">
<span><a href="index.html">Home</a> &raquo; Documentation</span>
</div><!--#toptext-->
<div class="clearfix"></div>
</div><!--container-->
</div><!--#wrapper-beforeheader-->
<div id="wrapper-header">
<div class="container">
<div id="header" class="twelve columns">
<div id="header-text">
<h1>Piggybak: A Mountable Ruby on Rails Ecommerce Solution</h1>
<p><a href="https://github.com/piggybak/piggybak">Piggybak</a> is a Ruby on Rails Engine with basic shopping cart and one page checkout functionality. It uses <a href="https://github.com/sferik/rails_admin">RailsAdmin</a> to provide an admin interface to work with orders, products, shipping methods, payment methods, and tax methods. It is not a turn-key ecommerce solution, but is intended to be mounted on existing Rails applications. Piggybak is open-source and free to use.</p>
</div><!-- #header-text -->
</div><!--#header-->
</div><!--container-->
</div><!--#wrapper-header-->
<div id="wrapper-content">
<div class="container">
<div id="content" class="twelve columns">
<div class="title">
<h1><span class="f-left"></span><span class="titletext">Documentation</span><span class="f-right"></span></h1>
</div>
<div id="maincontent" class="twelve columns alpha">
<div class="tabcontainer">
<ul class="tabs">
<li><a class="bbase" href="#bbase">Base Application</a></li>
<li><a class="installation" href="#installation">Installation</a></li>
<li><a class="integration" href="#integration">Integration</a></li>
<li><a class="configuration" href="#configuration">Configuration</a></li>
<li><a class="appearance" href="#appearance">Appearance Overrides</a></li>
<li><a class="recipes" href="#recipes">Recipes</a></li>
<li><a class="roadmap" href="#roadmap">Road Map</a></li>
</ul>
<div id="tab-body">
<div id="tab_bbase" class="tab-content">
<p>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 <a href="https://github.com/sferik/rails_admin">RailsAdmin</a>, it is a recommendtion. RailsAdmin depends on <a href="https://github.com/plataformatec/devise">Devise</a> for user authentication. <a href="https://github.com/ryanb/cancan">CanCan</a> is also used for authorization by RailsAdmin. It is highly recommended that you be familiar with RailsAdmin, Devise, and CanCan while working with Piggybak.</p>
</div>
<div id="tab_installation" class="tab-content">
<p>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.</p>
<p>Installation is similar to installation of other Rails gems. First, install the gem by adding the following line to your Gemfile:</p>
<pre>gem "piggybak"</pre>
<p>Install the gem:</p>
<pre>bundle install</pre>
<p>Next, run the piggybak install command:</p>
<pre>piggybak install</pre>
<p>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 <a href="https://github.com/piggybak/demo/blob/master/app/models/ability.rb" target="_blank">the demo source code</a> for an example:</p>
<pre>
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
</pre>
</div>
<div id="tab_integration" class="tab-content">
<p>After installation, Piggybak has several integration points:</p>
<p>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.</p>
<pre>acts_as_sellable</pre>
<p>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:</p>
<pre>attr_accessible :piggybak_sellable_attributes</pre>
<p>And you may also need to follow the <a href="https://github.com/sferik/rails_admin">RailsAdmin documentation</a> 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:</p>
<pre>
config.model YourModel do
edit do
#other fields
include_all_fields
# or field :piggybak_sellable
end
end
</pre>
<p>acts_as_orderer must be added to the Devise user model. This creates the Ruby on Rails association between user and orders.</p>
<pre>acts_as_orderer</pre>
<p>The cart_form helper renders a basic add to cart form.</p>
<pre><%= cart_form(@some_item) %></pre>
<p>The cart_link helper displays a link with total number of items and price to the user's shopping cart.</p>
<pre><%= cart_link %></pre>
<p>The orders_link helper renders a link to a logged in user's orders, with an argument to control the link anchor text.</p>
<pre><%= orders_link("Order History") %></pre>
<p>The piggybak_track_order helper renders Google Analytics order tracking, with an argument to control the store name.</p>
<pre><%= piggybak_track_order("Piggybak Demo") %></pre>
</div>
<div id="tab_appearance" class="tab-content">
<p>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.</p>
<p>Overridable views include:</p>
<ul>
<li>Add to cart form</li>
<li>Items display (on cart, order, receipt)</li>
<li>Cart page</li>
<li>Address form on checkout page</li>
<li>Order details partial</li>
<li>Order list page</li>
<li>Order receipt page</li>
<li>Order submission page</li>
<li>Order download text page</li>
<li>Order email notification view</li>
</ul>
</div>
<div id="tab_recipes" class="tab-content">
<p>Looking for a few tips on integration in the parent application? Here they are.</p>
<h3>Redirect After Log In and Log Out</h3>
<p>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.</p>
<pre>
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
</pre>
<h3>CanCan Integration</h3>
<p>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.</p>
<pre>
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
</pre>
</div>
<div id="tab_roadmap" class="tab-content">
<p>What's on the road map for this gem? Here are the current priorities:</p>
<ul>
<li>Testing support</li>
<li>Gift certificate support</li>
<li>Advanced variant support</li>
<li>Heroku support</li>
<li>Minor technical debt cleanup</li>
</ul>
</div>
<div id="tab_configuration" class="tab-content">
<p>The parent application can override Piggybak's configuration options with a standard config initializer. For an updated list of configuration options, view the <a href="https://github.com/piggybak/piggybak/blob/master/lib/piggybak/config.rb">config source code here</a>.</p>
<pre>
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
</pre>
</div>
</div>
</div>
</div><!--#maincontent-->
<div class="clearfix"></div>
<div class="title" style="margin-top:45px;">
<h1><span class="f-left"></span><span class="titletext">Additional Support</span><span class="f-right"></span></h1>
</div>
<div id="maincontent" class="twelve columns alpha">
<p>Looking for support? You've come to the right place. Get in touch with support several ways:</p>
<ul>
<li><a href="https://groups.google.com/forum/?fromgroups#!forum/piggybak">Join or Email the Piggybak Google Group</a></li>
<li><a href="https://github.com/piggybak/piggybak">Jump on GitHub to comment or file project issues</a></li>
<li><a href="http://www.endpoint.com/#contact">Contact End Point directly with a development request</li>
</ul>
</div><!--#maincontent-->
<div class="clearfix"></div>
</div><!--#content-->
</div><!--container-->
</div><!--#wrapper-content-->
<div id="wrapper-beforefooter">
<div class="container">
<div id="slogantext" class="twelve columns">
<a href="http://www.endpoint.com/"><img src="./images/end_point.png" alt="End Point" /></a><br />
Piggybak is sponsored and developed by <a href="http://www.endpoint.com/">End Point</a>. End Point has over 20 years of ecommerce experience.
<h2>Questions or Comments?</h2>
<i>Email the <a href="https://groups.google.com/forum/?fromgroups#!forum/piggybak">Piggybak Google Group</a> or
visit the <a href="http://www.github.com/piggybak/piggybak">GitHub repo</a> today.</i>
</div><!--#slogantext-->
</div><!--container-->
</div><!--#wrapper-beforefooter-->
<div id="wrapper-footer">
<div class="container">
<div id="footer" class="twelve columns">
<span id="copyright">Copyright &copy; 2015 End Point. All Rights Reserved.</span>
<ul id="footnav">
<li><a href="index.html" >Home</a></li>
<li><a href="features.html">Features</a></li>
<li><a href="showcase.html">Showcase</a></li>
<li class="current"><a href="documentation.html">Documentation &amp; Support</a></li>
<li><a href="demo_details.html">Demo</a></li>
</ul><!-- #footnav -->
</div><!--#footer-->
</div><!--container-->
</div><!--#wrapper-footer-->
</div><!--#wrapper-->
</body>
</html>