• View
• Edit
• History
• Attach
• Print
• Backlinks

SimpleCart

Description

Instructions on how to add a simple shopping cart based on simpleCart.js. Visit http://simplecartjs.com/ to download script and for documentation how it is integrated into a HTML page. The following attempts to give some advise on how to adapt it to PmWiki, to offer a simple and fully integrated cart, easy to customise to your site, and a joy to use because additions to the cart and changes are instant. The script is also very small in size, so downloads rapid to a browser. It writes the cart content as a cookie, so one can go from page to page in the shop without problems.

Clicking the checkout link will submit the entire cart to the PayPal or Google payment gateway, and the shopper finds again the items selected listed, with quantities and prices, and shipping costs (if used) and Total. Going through the payment process will result that the entire order is e-mailed to the seller, with the advise that the payment has been made, as part of the PayPal or Google service.

Installation

Download simpleCart.js from http://simplecartjs.com/download.html.
Copy file to a new folder pub/simpleCart/.
Assuming you want a shop with shopping cart in group Shop in your wiki, create a new php file in folder local/ called Shop.php and add this as first line:

Add to this file:

$HTMLHeaderFmt['simpleCart'] = "
  <script type='text/javascript' src='$PubDirUrl/simpleCart/simpleCart.js'></script>
"; 

Configuration

Add other configuration script code into the same $HTMLHeaderFmt entry, for instance:

$HTMLHeaderFmt['simpleCart'] = "
  <script type='text/javascript' src='$PubDirUrl/simpleCart/simpleCart.js'></script>
  <script type='text/javascript'>
    simpleCart.checkoutTo = PayPal;
    simpleCart.email = 'you@yours.com';
    simpleCart.currency = GBP;
    simpleCart.shippingFlatRate = 0.5;
    simpleCart.shippingQuantityRate = 0.1;
    simpleCart.shippingTotalRate = 0;	
    simpleCart.cartHeaders = ['Thumb_image_noHeader', 'decrement_noHeader' ,  'Quantity_noHeader' , 'increment_noHeader' ,  'Total_noHeader' , 'Remove_noHeader' , 'Name_noHeader' ];
  </script>
"; 

Please see http://simplecartjs.com/documentation.html under Configuration for what you may need to initialise the script.

simpleCart.cartHeaders is explained under Cart Formatting in the script documentation. It determines what controls, info etc. and in what order those appear in the cart. In my example the cart will list selected items with a thumb image first, followed by a decrement link (minus sign), the quantity, an increment link (plus sign), the total for that item, a Remove link, and the name of the item. You may well want the name after a thumb image, or no image, and less control links. The appearance is done chiefly via css styling. For this create a file pub/css/Shop.css. All shopping cart elements are generated in js in their own divs with class names, so to get some tabular listing I use

These class names are determined in the script.

Usage

The Shelf

Some other class names are used by the cart script to find out what action commands are given, and what constitutes a shopping item, and what attributes each item should have. We can use some of those class names within wiki markup. Here is an example of a shopping item written with PmWiki markup in a wiki page:

(:div class=simpleCart_shelfItem:)
%item_thumb%Attach:example.jpg
%item_name%Example%%
%item_price%$15.00%% (:input text value='1' class=item_quantity size='1' :) (:sc_add:)
(:divend:)

The div with class=simpleCart_shelfItem provides a wrapper for one shelf item, and HTML elements with class names item_name, item_thumb, item_price, item_quantity, item_size are providing the data for the item. See The Shelf in the documentation.

It may be worth noting that one can use input controls, like the text field above, or a input select control, or a hidden control, without further form elements. The script picks up changes of values in these controls, because of the use of special class names. A hidden control can be useful to pass a value to the cart, as an attribute of an item, without it appearing on the shelf.

Special Control Link Markup

The markup (:sc_add:) is a custom markup for cart control links. Add to local/Shop.php:

Markup('sc_links','directives', '/\\(:sc_(add|empty|checkout)\\s?(.*?)?:\\)/e',"SimpleCartLinkFmt('$1', PSS('$2'))");
function SimpleCartLinkFmt($type, $label) {
  switch($type) {
    case 'add':
      $class = 'item_add';
      if(!$label) $label = 'Add to Cart';
      break;
    case 'empty':
      $class = 'simpleCart_empty';
      if(!$label) $label = 'Empty Cart';
      break;		
    case 'checkout':
      $class = 'simpleCart_checkout';
      if(!$label) $label = 'Checkout with PayPal';
      break;
  }
  $out = '<a href="javascript:;" class="'.$class.'">'.$label.'</a>';
  return Keep($out);
}

This adds markups (:sc_add:), (:sc_empty:) and (:sc_checkout:), and one can give a custom link text inside like (:sc_add Add to Basket:)

The links (:sc_empty:) and (:sc_checkout:) are used normally within the shopping cart container.

The Shopping Cart

How you display and style your shopping cart is up to you.
In my shop I created a page Shop.ShoppingCart, and included it in all pages of the Shop group via Shop.GroupHeader, with an entry there (:include ShoppingCart:). Then I used the Toggle recipe to create toggle links, which folds the cart content conveniently out of the way initially.

Here is my own cart, slightly simplified, as an example:

(:div0 id=sc_container:)
%rfloat%[+(:toggle id=basket id2=info init=hide show='Show' hide='redbt.gif':)+]%% %cart_title%Your Shopping Basket:%%
(:div1 id=info style='float:left;':)
%simpleCart_quantity% %% items
(:div1end:)
(:div2 id=basket:)
||width=100%
||%simpleCart_quantity% %% items || %simpleCart_total green% %%||
||Shipping & Handling || %simpleCart_shippingCost green% %%||
|| Total|| %simpleCart_finalTotal green% %%||
(:div3 id=cartitems class="simpleCart_items":)
(:div3end:)
(:sc_checkout:) %rfloat%(:sc_empty Empty Basket:)%% 
(:div2end:)
(:div0end:)

In this example you can see the use of several special simpleCart class names, for instance %simpleCart_quantity% %% will provide an empty HTML <SPAN> element, which the script uses to show the quantity of items in the cart. Note the space before the closing %%.

Notes

You can see my little shop here http://naturalscotland.co.uk/Shop/Shop (sorry, shop is closed at present), which offers photo greeting cards. I've done a few other things not explained, for instance using PHP and custom markup for generating an entire page with shelf items, to cut down on repetitious wiki code.

I also use the PayPal checkout image via custom markup in the checkout link. I defined the markup (:ppcheckout:) in Shop.php:

Markup('pp_checkout', '>block', '/\\(:ppcheckout:\\)/', '
<a href="javascript:;" class="simpleCart_checkout"><img src="https://www.paypal.com/en_US/i/btn/btn_xpressCheckout.gif" align="left" style="margin-right:7px;"></a>');

Paypal, I am told, provides good mechanisms to calculate shipping costs, in various ways, even different costs for different regions, like State internal, US wide, international. But it does not provide such service to non-US customers. That is why I opted to have shipping costs calculated within my site, and not within the PayPal gateway.

For this to work I've made use of the View Modes recipe, not to display different content, but to let a shopper select amongst a number of shipping regions, right at the start before adding to the cart. The selected value is consequently used to set various shipping rates, in Shop.php, and these PHP variables are passed to the javascript to set it's shipping-rate variables.

Change log / Release notes

2012-04-11: initial release

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

See also

Contributors

Comments

See discussion at SimpleCart-Talk