(NOTE - THIS IS NO LONGER MAINTAINED)


MinimalCart
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

As the name implies, MinimalCart is very lightweight shopping cart plugin for Rails that leverages ActiveMerchant as a payment gateway. Why minimal? Implementing an entire off the shelf shopping cart system would inevitably restrict the use and configuration of you application, and / or force you to switch to such an application undermining the ability for you to simply 'add a cart system' to you existing application. With this in mind, MinimalCart assumes at least a basic understanding of building rails applications and is designed with the active developer in mind.

All monetary values are stored in pennies to avoid float rounding errors


INSTALL
------------------------------------------------------
./script/plugin install svn://rubyforge.org/var/svn/minimalcart

GENERATE DATABASE
------------------------------------------------------
./script/generate minimal_cart MinimalCart
rake db:migrate 

CONFIGURE 
------------------------------------------------------
vi /vendor/plugins/minimal_cart/config/config.yml


REFERENCE IN APP
------------------------------------------------------
In the controller of your choice simply add the reference:

class ShopController < ApplicationController
  include MinimalCart
  miminal_cart
  ...

This will add all functionality to the controller

EXTENDING PRODUCT 
------------------------------------------------------
MinimalCart comes with a basic Product model with the following attributes:

:name
:byline
:description
:price
:weight

Additional attributes can added by simply extending the Product model, e.g.

class TwelveInchVinyl < Product 
  validates_presence_of :sound_clip, :label, :origin
  acts_as_taggable
  attachment_fu
end

As implied above, images are deliberately left out for basic product in favor
of your favorite __ plugin [such as attachment_fu]. Extending the Product model
is, of course, a critical polymorphic requirement.  

USING 
------------------------------------------------------

Once referenced in your controller, it now has the following methods:

add_cart(id)
remove_cart(id)
update_cart(id, quantity)
clear_cart


CHECKING OUT
------------------------------------------------------
 At this point you will have to dig in and read / understand the included Billing and Customer Models since you will need to populate them in order to process your order [calling the get_billing method will return a Newly created Billing object with a Customer object as well]

Once you've managed that you can retrieve the subtotal / total with the following methods:

        subtotal_cart
        total_cart
      

An when you are ready to process the transaction, ensure that you have set the Customer and Billing data using:

        ship_to(customer)
        bill_to(customer, billing)
      

and use the

        process_card
      

method to process the card. At this point it's a good idea to store this entire transaction so you can come back to it at some point. This is accomplished by using the

        check_out
      

This will create a ShoppingTransaction model, save it, and return it to you [or throw an assortment of exceptions if there's a problem].

Transactions [minus the Billing information] are stored in the ShoppingTransaction persistence. One very important note is that manually destroy this information in the session after you have successfully completed a transaction:

        session[:billing] = nil
        session[:shipping] = nil


TAX / SHIPPING NOTES
------------------------------------------------------
Both Tax and Shipping totals are supported with ShippingRate / CountryGroup and TaxRate models respectively. There are fixtures included with fairly recent rates from the USPS but will likely change. Again, like products themselves, it is assumed that the you will handle the interaction / setting / etc of these rates. Once set though, the MinimalTax and MinimalShipping modules will calculate the rates and include in the transaction. All shipping weights are in ounces.



FAQs
------------------------------------------------------
But wait how do I add and manage my products? - by building your own interface to them, again this is beyond the scope of what MinimalCart is..

Where did this come from? - MinimalCart was extracted from existing ecommerce application written in Ruby on Rails.

Does MinimalCart store Credit Card info? - Definitely Not. Billing information IS stored in the session during the life of the transaction and it is very important that you destroy this information when done with it.


Copyright (C)2007 John Bresnik

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.