Quick Start Guide
Configuration
The Shelf
Cart FormattingQuick Start
After downloading the files, simply place a copy of the simpleCart.js in your site directory, and attach it to each page that will be using the cart. Payment:
PayPal is the default checkout option. We also support payment processing merchant services from High Risk Merchants and Patriot Bankcard. So if you have a Paypal account, you will need to set your account email:
Items for Sale
To have an item for sale (like an awesome t-shirt), you can put it on your "Shelf" like so:
To create a shelf item, you create a div with a class of “simpleCart_shelfItem”. Any field you want for your item can be set by creating a tag with a class of “item_field-name” and the contents or value of the tag will be the value added for the item. Please check out Shelf Setup for more info about the shelf.
You can also add an item to the cart with a simple link:
Add To Cart
Cart Links and Cart Summary
If you want to display information about the cart anywhere on your page, simple create any tag (div, span, a, h2, …etc) with a specific class name.
For the total items in the cart, use “simpleCart_quantity”
You have items in your Cart.
For the cart total, use “simpleCart_total”
Cart total:
You can create a Checkout link or Empty Cart link by using "simpleCart_checkout" and "simpleCart_empty"
Checkout Empty
The checkout link will immediately send all the items to PayPal (or another checkout option like Google Checkout) when you click it. These don't have to be links, however, you can also use a div, images, or any other tag by simply setting the class correctly.
The Cart
You can display the full cart on any page by simply creating a div with a class of "simpleCart_items"
SimpleCart(js) will automatically populate the div with all the items in the cart. You can change the appearance of your cart or what columns are in the cart by checking out Cart Header Formatting.
Configuration
After downloading the files, simply place a copy of the simpleCart.js in your site directory, and create a link to it on each page that will be using the cart:
After you've added the simpleCart.js script to your pages you will need to add another inline script tag to set your options. All of the following code snippets will take place inside that inline script tag.
Checkout Options
Set your email if you plan on using the Paypal checkout method:
simpleCart.email = "brett@wojodesign.com";
If you want to make sure the cart will checkout to Paypal, just use:
simpleCart.checkoutTo = PayPal; simpleCart.email = "brett@wojodesign.com";
If you want to use GoogleCheckout set the checkoutTo as follows:
simpleCart.checkoutTo = GoogleCheckout;
Instead of inputing an email, you use your Google Checkout Merchant Id:
simpleCart.merchantId = "111111111111111";
Currency
The default currency is USD ( US dollars ), but if you want to change it:
simpleCart.currency = GBP;
or
simpleCart.currency = PoundSterling;
Google Checkout only currently supports GBP and USD, but paypal supports several Paypal Currency List .
Changing the currency not only changes the checkout method, it will correctly format any output on the page with the correct symbol.
There is no exchange rate, it is assumed any price inputs are already in your chosen currency.
Tax Rate
If you want to set the tax rate use:
simpleCart.taxRate = 0.07;
If you would like to display the tax rate or tax charges for the order, you can use:
Tax Rate: Tax on this Order:
Any element with a class of “simpleCart_taxRate” will be populated with the tax rate shown as a percentage, and an element with a class of “simpleCart_taxCost” will be populated with the current tax cost as a dollar amount.
Shipping
There are several methods for adding a shipping cost to your cart. First, you can setup some basic shipping calculation for the entire cart:
simpleCart.shippingFlatRate = 10.00; //add a flat shipping rate to the entire order simpleCart.shippingQuantityRate = 3.00; //add a shipping cost of 3.00 for every item in the cart simpleCart.shippingTotalRate = 0.05; // add a shipping cost as a percentage of the total cost
You can implement any combination of these shipping options and they will add together for the total cost.
simpleCart(js) allows you to set a shipping field for an item that will add a special shipping cost for that item. If you are using the Shelf ( [[Shelf Setup]] ) you can add a hidden field for an item:
Or, if you are using the 'add' function for adding items to the cart:
onclick="simpleCart.add('name=T-shirt','price=15.00','quantity=1','shipping=5.00');"
If you require some advanced calculations for shipping, you can use the prototype object for CartItems:
CartItem.prototype.shipping=function(){
// we are using a 'size' field to calculate the shipping,
// so we first make sure the item has a size
if(this.size){
if( this.size == 'small' ){
return this.quantity*5.00;
} else if( this.size == 'large') {
return this.quantity*7.50;
} else {
return this.quantity*10.00;
}
} else {
// use a default of $2.00 per item if there is no 'size' field
return this.quantity*2.00;
}
}
The 'this' here refers to the item, and we are using a 'size' field and the item 'quantity' to calculate the shipping. Because an item may or may not have a size, we check to make sure it does with the 'if(this.size)'. If there is a size field, we use a different rate for each size and return a value based on the item quantity. Otherwise, we use a base rate of 2.00. simpleCart(js) will use the global shipping rates, and then add the shipping value for each item in the cart.
If you set a shipping field in the Shelf Item or when adding, it will override this function method. You can use a combination of all these methods to create some very advanced shipping calculations.
Shelf
You can make items be available to your users by simple using class names in your html. For any Item you want to be available to be added to the cart, you make a container with a class name of "simpleCart_shelfItem". Then add classes to tags inside of that container that have the general form "item_[name of field]" and simpleCart will use the value or innerHTML of that tag for the cart. For example, if you wanted to sell a T-shirt with 3 different sizes, you can do this:
Notice here that you can use a select to change options for the item when you add it to the cart. You can also use a text input to change the quantity (or any other field!). These classes will work with any tag, so feel free to use what works best for you. Finally, notice that a tag with the class "item_add" will have an event listener on its click. So when the contents of that tag are clicked, an item will be added to the cart with the values of each of the tags in the container with the "item_something" class.
Some notes:
- You will want to always supply a quantity and price. Although the cart won't break if you don't, all the quantities and totals are created from it, so the cart will assign a price of $0 if there is none, and a quantity of 1 if no quantity is provided.
- If you are planning on checking out to googleCheckout or paypal, it is a good idea to use a name field
- If you use a link for the add to cart button, its a good idea to set the href to "javascript:;"
- You can pretty much anything to the items on your "shelf", so be creative. Images will work fine too!
Cart Formatting
Displaying Cart Information
There are keywords for displaying information on your page. For example, if you give a class name of "simpleCart_total" to any tag, the innerHTML will be replace with the cart total. Here are the other options:
//will be display as a percentage ( ie 7% )
//will be displayed as currency ( ie $25.00 ) and will be the cost of the taxRate times the total
//will display the total of the cart after adding tax and shipping
Displaying Items in Your Cart
You can display the full cart on any page by simply creating a div with a class of "simpleCart_items"
You can format how the cart is displayed by adding this in your configuration script (see Configuration):
simpleCart.cartHeaders = [ "Name" , "Price" , "Quantity" , "Total" ];
Of course, you can change the order, or add any other fields that the items in your cart has. If you want a field to be in a text input so users can change it will looking at the cart, you can use:
simpleCart.cartHeaders = [ "Name", "Price", "Quantity_input" , "Total" ];
If you want to use decrement and increment links that will show up in a column like "-" and "+", respectively, use:
simpleCart.cartHeaders = ["Name" , "Price" , "decrement" , "Quantity" , "increment" , "Total" ];
If you want a link to remove the item from the cart:
simpleCart.cartHeaders = ["Name", "Price", "decrement" , "Quantity" , "increment" , "Remove", "Total" ];
If you want to hide the header for a particular column:
simpleCart.cartHeaders = ["Name", "Price", "decrement_noHeader" , "Quantity" , "increment_noHeader" , "Remove_noHeader", "Total" ];
If there is an Image field for the items in you cart, you can use:
simpleCart.cartHeaders = ["Image" , "Name" , "Price" , "decrement" , "Quantity" , "increment" , "Total" ];
simpleCart(js) will recognize the "Image" keyword and output an img tag. However, if you have a field in the items called "thumb" and want to display an image, you can use:
simpleCart.cartHeaders = ["Thumb_image" , "Name" , "Price" , "decrement" , "Quantity" , "increment" , "Total" ];
Styling the Cart
Since the HTML for the cart is generated by simpleCart(js) styling it should be done with the aide of Firebug or the Safari Element Inspector. Either one will show you the HTML structure being created by simpleCart(js). Then it's all up to you to add your own CSS.
For reference, the headers would all be in a div called "cartHeaders". Each item will have a class of "itemContainer" with divs inside, each having a class corresponding the the field name after the word 'item'. So for size: "itemSize".
NameSizePriceQuantityTotal
