Read Me

Rawcart - an example stand-alone shopping cart for the web
==========================================================

Motivation
==========

This project was started because I found that all shopping cart solutions
were in some way tied to a particular web publishing framework. I was
already working in Python with the Twisted framework, which doesn't have
a standard shopping cart. The solution was to write one and make it totally
independent of any framework. This allows a large amount of flexibility
that the developer has in using the cart.

Standards compliance
====================

The entire package complies to the XHTML 1.0 strict dtd. The pages
have been validated with the W3 validator. The Javascript used should
be fully conformant to the ECMA-262, 3rd edition ECMAScript Language
Specification.

Due to lack of support in IE7, the <script type="application/javascript">
tags have been replaced with <script type="text/javascript">. The latter
form has been deprecated by IANA.

Compatibility
=============

The package has been verified to work in the following browsers:

- Firefox 3.01 under Linux, amd64

- Konqueror 3.5.9 under Linux, amd64

- Internet Explorer 7

Dependencies
============

There are no dependencies, apart from the obvious web server that serves
the pages and a Javascript enabled web browser to use them.

Usage
=====

In order to use the cart, follow the following steps:

1. Install the whole set of files in a directory that can be served
by your webserver.

2. Load the shopcartindex.html page in your web browser. You should
see a page with 2 frames. The left one is the navigation frame
and the right one is the main frame.

Clicking on the links in the navigation frame should show you the
different pages with example merchandise for sale. Adding any to the
contents of the cart should update the cart view in the navigation
panel.

If you select the "Review Order / Check Out" link, you should be taken
to the check-out page. Filling in the form and selecting "Place Order"
should send a request to your web server, with a POST form with all the
order details. There is no page included to handle the response, so this
should generate a 404 error.

You have now tested that the basic shopping cart works.

3. Modify the navigation page to look like what you want. Be careful
to keep the tags with id's "itemcount" and "ordertotal" intact. They are
what makes the updates work whenever someone puts stuff in the cart.

4. Replace the order pages ("page1.html", "page2.html" and
"page3.html") and the "welcome.html" page with whatever you want on your
website. The important things with the order webpages are:

- they have to include the script "addsubtract.js"

- each item has to be specified in one of two different ways. Either
you need to put all the necessary information in the setItem/addItem
calls, as is done in "page1.html", or you need to put id's on the
elements in the page which show description, price and max number
availabe. This is demonstrated in "page2.html". In both cases, you have
to have an id on the input element that displays how many you have
ordered of an item.

I strongly recommend the second way of specifying the items for sale.
It does not repeat information, which ensures that you can't offer one
price in the text and then have a different one when actually placing
the order. Same goes for the other fields.

5. Modify the "order.html" page to look like you want it. If you change
the fields of the customer information, you have to modify the list
of customer fields in "order.js"

6. Build whatever you need you need to receive and process the order
form.  The default resource accessed when the form is posted is called
"placeorder", but you can rename this to whatever you want.

Renaming and changing things around
===================================

If you rename "shopcartindex.html", you need to change its name in
"not_in_frame.js" as well.

A built in assumption is that the navigation page is frame number 0
and that the main page is in frame number 1 of the frameset in
"shopcartindex.html". If you want to do this differently, you need to
go through the code and make the necessary changes.

Limitations
===========

We browsers only allow cookies to be 4096 characters long. They also
put limits on how many cookies a site can store. Currently the shopping
cart uses one cookie for the items in the cart and one for the customer
details. Both cookies are only saved for as long as the browser is
around (and the items cookie is cleared when the order is sent).

The big limitation is that the items ordered are stored in the cookie
with information about description, price, max number available and how
many the customer has ordered. This can easily require 200 characters
per item, limiting the number of items that can be saved to about 20.

When the maximum number that can be saved is reached, the customer is
alerted. The only consequence is that the contents of the cart will
not be restored if the customer reloads the cart web page, or
navigates away in order to come back later. It is still possible to
add to the list of purchased items and do a checkout.

Optimizations
=============

The cart is reasonably small and loads fairly quickly. However, there are
changes you can do if you need improved performance:

- Merge the Javascript files that are loaded in each of the head
sections of the html files into single files. This will save
roundtrips to the server.

- Use a tool like YUI Compressor to make the Javascript smaller.

- When a request for a new page is sent from the web browser to the
server, all cookies for the domain are sent as well. This can have a
negative impact if the user has a slow link and a full shopping cart.
If you encounter such problems, you should use one domain for the
"shopcartindex.html" and "order.html" pages and load the item pages
from a different domain. This will prevent the cookies from being sent
with the item page requests.

Work needed
===========

1. There are no tests. I would like to have a web page in the package
that loads the scripts and loads a plain Javascript test suite. I want
to preserve the stand-alone nature of the package and requiring an
external package for the tests is contrary to this goal.

2. The code should be more extensively commented.

3. This file assumes that you can read Javascript code. I would like
to have an even more newbie friendly document explaining how to use
the package. I am not the person to write this.

Acknowledgements and copyright concerns
=======================================

The shopping cart code was written by Jacob HallÚn. There was some
inspiration from an old and non-working cart implementation found
by searching the web. There are still some layout remnants from
that piece of code, though not a single line of the actual project
remains.

The files "objectsArraysString.js", "stringForms.js" and "cookies.js"
are taken from the Javascript & DHTML Cookbook, 2nd ed (O'Reilly 2007).
I have made minor modifications to the original scripts. The book permits
free usage of the code examples, even without attribution.

The shoppingcart images were downloaded from a website of public domain
images. The image actually used is a modification of the original image.
The white background has been replaced with a transparent one.

The html pages of the project are placed in the public domain. You can
do anything you wish with them.

The files "cart.js", "order.js" and "not_in_frame.js" are covered by the
GNU Lesser General Public Licence (LGPL).