This repository has been archived by the owner on Jul 15, 2020. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 13
/
documentation.html
296 lines (277 loc) · 14.4 KB
/
documentation.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
<!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 & 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> » 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 © 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 & 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>