Contact me concerning this article at paypalhelper@aol.com. Mention Basic Cart in your note.
Individual help starting at $25.00 for simple JS solutions.
* 20 March, 2006. Corrected error when 1st item in FORM is an add to total rather than set total.
* 19 June, 2005. Changed transmission to PayPal from "get" to "post". Major security and reliability implications.
* 11 April, 2005. ReadForm function requires 2nd argument for item total!!
* 10 April, 2005. Cart quantity and total amount now available in HTML pages.
* 8 April, 2005. Corrected error in applying discounts in PayPal cart.
* 19 March, 2005. Mail FORM now an optional, user-selected display.
* 15 February, 2005. Each option of an item may now have its own weight.
* 2 October, 2004. Added one-time charge to items (qty no difference).
* 30 August, 2004. Record coupon code in custom rather than invoice.
* 7 August, 2004. Added percent of amount based shipping charges.
* 17 July, 2004. PayPal shipping preferences completely ignored.
* 3 July, 2004. Coupon amount discount (in addition to percent)
* 18 June, 2004. Fixed cookie problem for some browsers.
* 13 June, 2004. Set-list moved to separate file to fix some browser problems.
* 12 June, 2004. Tax charged on handling and gift wrapping.
* 4 June, 2004. Set min/max item quantity to order.
* 30 May, 2004. Coupons moved to the set-list.
* 29 May, 2004. Fixed installation documentation error.
* 26 May, 2004. User may bypass image resizing in cart.
* 25 May, 2004. Cart displays selected currency.
* 16 May, 2004. Address form on cart page optional.
* 15 May, 2004. Select pounds or kilograms for shipping weights.
* 19 April, 2004. Giftwrap charge per item.
* 29 March, 2004. PayPal page style support, and fix for NN4.7.
* 4 March, 2004. Minimum order (qty or amt), and amount-based, percent discount.
* 24 February, 2004. Different rates for different coupons.
* 5 February, 2004. Added item-specific handling and shipping charges - adds to cart totals.
* 1 February, 2004. Added "agree to terms" checkbox.
* 10 December, 2003. Corrected problem sometimes causing zero shipping. (FINALLY!)
* 27 November, 2003. Corrected tax calculation after discount.
This is a general, client-side JavaScript (JS) shopping cart (sometimes called a 3rd party cart) that inserts itself between your page and PayPal. You interact only with this shopping cart (no PayPal button factory stuff), and just use PayPal for checkout when the customer tour of your site is over.
This is a client-side cart that exists on the user's machine, and not in a server. This means there are limits. It means that no more than 15 different items may be placed into the cart. The greatest cause of such a limit is that this cart uses session cookies to remember cart contents across site pages, and that places a limit on items in the cart. But for small to medium sites, this is a super-fast cart with many features that normally exist only on server-side carts.
The purpose of this cart is to provide service to PayPal customers that PayPal simply cannot provide...
In your site HTML you just make JS calls from event handlers and let this cart take care of the PayPal interface. What you have to learn are the calls that are available to drive this cart - they are explained, below.
This cart reads through the FORMs of your site and extracts data from the value, or text, fields of those FORM elements and builds the selected items into a description. Notice how the cart works for two differently formatted FORMs in this example. It works for select (one or multiple), checkbox, radio, or text FORM fields. Just right-click on this page (and <view source>) to see how the interface works.
1. All of the SetAmt... and SetCart... calls are of the form (pc,a1,c1,a2,c2...). The first argument is the product category (starting at zero) followed by breakpoint/charge pairs of data. The first item of a pair is a breakpoint - a quantity or an amount. The 2nd item of each pair is the charge starting at that breakpoint such as percent or amount...
SetCartSH (0, 1, 2, 3, 4); // This sets quantity-based shipping.
This call sets up Product Catagory 0.
1 - 2 items cost $2.00 to ship,
3 - items cost $4.00
And (in the call definitions area),
pc = product category (class)
a = amount
c = charge
p = percent
q = quantity
w = weight
2. Anything that is item-based only lasts for that single item and must be reset for each item in the cart (such as SetQtyD).
There is a very special condition you must be aware of when the first item in the FORM is an add-to (+) rather than a set (@). If the first item in any FORM is not a set (@) then you MUST include this card as the 1st item within the FORM...
<input type="hidden" name="initer" value=" @0" />
What this card does is to initialize the amount to some value for the FORM. In this example it sets the initial value to zero, but you can set it to whatever you want - just be sure to use it if the first card in your form does not set (@) the amount of the item.
3. Cart-wide percent coupon discounts have codes that are set in the Set-list with the discount set in a corresponding array, and they are tested with the call...
ChkCoup ();
The discount established by this mechanism works in addition to any item or cart-wide discounts you may have established. The coupon entry appears in the cart window (if turned on in your first page with root.xx_coup = on), and once a successful entry is made, it disappears.
5. Cart-wide tax assigned by the region the goods are being ordered from. This item is assigned from a select where all of the relevant options are listed. In this example I have coded it for Ontario, Canada, where the local province has a higher tax rate, the rest of Canada has a lower tax rate, and the rest of the world has no taxes.
This item is filled from an unnamed select that may be included in a FORM on the cart display page (as in this example). You ask the customer their location, and the tax is applied to all items. Put this into the event handler of the select...
SetCartTX (this); // "this" gives access
Actually, it is best to use the method PayPal offers in their preferences because they can charge tax by country, so such a thing as one tax for England, and another for the rest of the EEC, is possible. But, if you must, I provide the possibility of a more complex tax structure.
6. Amount/quantity/weight based shipping options that are user selected (ground, air, zone, etc). Here the customer may select from all the different options you supply. Each option has a different amount or quantity based table that you define. An order cannot be placed until the user selects his shipping option (unless shipping is deactivated, below).
7. Product categories. Here, items may be placed into categories (classes) within which special things may be applied only to them, such as discounts or shipping charges. The default category is zero and everything normally is put into this category. If you have a special class of items, you place them into a specific category by calling SetPcat for that item in your HTML. Without that call, the default applies. Five is the current limit.
For example, if you had a special class of products that you only wanted to charge a one-time shipping fee of $1, no matter how many items within this class were ordered, you would do the following...
For each item in the special class you must set this call in every FORM onsubmit event handler...
SetPcat (1); // set class of item to 1 (special)
And in the set list at the beginning of the site (on the first page) you would include...
SetCartSH (1, 1, 1); // any number of cat-1 items, $1 to ship
Another example is if you have a class of items that require NO shipping or handling charges, and get no discounts (but everything else has these things apply to them, if ordered). In this case you would mark these items with the special call in the FORM event handler to set them to class 1, but would include NO calls in the set list on your first page for class 1. You set them aside for special treatment, and then apply no special treatment - which means they are exempt from normal order charges, discounts etc.
8. There are certain features of the cart page that may be changed in your HTML. The default is a minimal cart, but the set-list can override this and create a cart with many more displays. To be compatible with the most browsers, the set-list is containded in a separate JavaScript include file - set.js, and must be included in every page of your site where orders may be placed. Here are sample contents of that file...
// required entry to load the cookies (for older browsers)
LoadIt (); // force load of data
// set-list for any cart-wide options here
SetCartHN (0, 1, 1); // $1 handling for entire cart
// set cart display options, and internal PayPal options
root.xx_cc = on; // display credit card line
root.xx_cdmp = off; // root diagnostic cookie dump (leave off)
root.xx_chkbx= on; // terms agreement checkbox must be checked.
root.xx_coup = on; // ask for coupon code on cart page
root.xx_cval = "xcoup1,xcoup2"; // coupon values
root.xx_cdis = "10,0"; // corresponding coupon percent discounts
root.xx_camt = "0,1"; // corresponding coupon amount discount
root.xx_dadd = on; // display cart when add-cart is clicked.
root.xx_gwbx = on; // gift wrapping checkbox
root.xx_gwcg = 10; // giftwrapping charge per item (if selected)
root.xx_img = on; // show images in cart (SetImg)
root.xx_mamt = 0; // minimum amount of order, or zero.
root.xx_mqty = 1; // minimum quantity of order, or one.
root.xx_pc = on; // display product category in item list
root.xx_prt = on; // print email line and addr form
root.xx_ship = on; // ask user for shipping options
root.xx_siz = on; // for img, on = resize, off = use orig size
root.xx_sum = off; // display product cat summaries
root.xx_tax = on; // ask user for tax options
root.xx_wt = on; // display weight totals
root.xx_wtent= ""; // default entry = ounces, "gm" = grams.
root.xx_wtrup= 10; // rounding value - oz always up to lbs
// gm rounds up to these grams.
// place for user-specific options
root.xx_can = ""; // place for PayPal cancel return path
root.xx_cur = "USD";// enter default currency code (or null)
root.xx_id = "jas22924@aol.com"; // PayPal ID
root.xx_lc = "US"; // enter default country code (or null)
root.xx_ret = ""; // place for PayPal return path
root.xx_sty = ""; // place for PayPal page style
// required entry to store stuff off.
root.store (); // required entry!!
9. You may now display images of selected items in the shopping cart. This involves two steps...
10. You can display the shopping cart total quantity and/or total amount within a FORM anywhere on your page. It will even show if you have it set up to display in several places. There are just two requirements...
Qty in cart -
<input type="text" name="cqty" size="4" value="" />
Cart Total -
<input type="text" name="ctot" size="11" value="" />
<body onload="LoadTots (document.forms);">
All of the item-based calls except the ReadForm call may be executed anywhere within your HTML page. However, they are best executed within a FORM because that structure gives you access to many different event handlers, and provides a natural mechanism for allowing the user to select options that may be available for an item. Note how this example HTML page works.
The following rules are offered as though all calls are executed within a FORM that surrounds a single item for sale...
SetOpt1 ('User name and address', '');
ReadForm (this.form);
What this does is to set the title for the field and let the user input fill in the value.<option value="item #7.5 @10.00">... That is a 7.5 oz item costing 10 dollars.
INSTALLATION. This is the installation of the basic cart. Most everything may be customized, but it is probably better to start with the default to see how it works before changing things.
This is a client-side cart that installs on your system (server hosting your site) - it does not reside on some other server, somewhere. The cookies that are talked about reside on your customer's system (as normal), not on your system - and you should not abuse their use.
<body>
<script type = "text/javascript"
src = "cart1.js">
</script>
<body>
<script type = "text/javascript"
src = "set.js">
</script>
LIMITS. There are limits that must be realized both for my cart and for the data going to the PayPal cart.
Since last update.
Contact me concerning this article at
paypalhelper@aol.com.
Mention Basic Cart in your note.
Individual help starting at $25.00 for simple JS solutions.