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:
Install the gem:
Next, run the piggybak install command:
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.
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:
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.
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
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
Looking for support? You've come to the right place. Get in touch with support several ways: