Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100755 223 lines (157 sloc) 7.814 kB
436b5af changed readme to .md
Brett Wejrowski authored
1 #simpleCart(js)
2
3 No databases, no programming, no headaches. A simple javascript shopping
085dea3 @brettwejrowski merged v3 to master
brettwejrowski authored
4 cart that you can setup in minutes. It's lightweight, fast,
436b5af changed readme to .md
Brett Wejrowski authored
5 simple to use, and completely customizable. All you need to know is basic HTML.
6
7
085dea3 @brettwejrowski merged v3 to master
brettwejrowski authored
8 Copyright (c) 2012 Brett Wejrowski
436b5af changed readme to .md
Brett Wejrowski authored
9 Dual licensed under the MIT or GPL licenses.
085dea3 @brettwejrowski merged v3 to master
brettwejrowski authored
10
11
12 ##This is version 3
13
14 If you would like to use an older version, you can use a different branch or see them in the
15 downloads area
16
179e2c0 @brettwejrowski added .on, fixed shipping/currency bug, multiple bind events
brettwejrowski authored
17 v3.0.4 changelog
18 - added .on alias for .bind
19 - allowing for multiple event bindings at once with space separated list
20 - fixed check to bug with switched currency and shipping
74e2fae @brettwejrowski Added support for preventing items from being removed/added using eve…
brettwejrowski authored
21
10c266a @brettwejrowski updated Readme
brettwejrowski authored
22
23 ## Quick Start
24
25 To get started, just add the simpleCart javascript file to your page, and set your PayPal checkout:
26
27 <script src="simpleCart.js"></script>
28 <script>
29 simpleCart({
30 checkout: {
31 type: "PayPal" ,
32 email: "you@yours.com"
33 }
34 });
35 </script>
36
37 If you want to change options, like the tax or currency, you can do that as well:
38
39 simpleCart({
40 checkout: {
41 type: "PayPal" ,
42 email: "you@yours.com"
43 },
44 tax: 0.075,
45 currency: "EUR"
46 });
47
48 To sell items, you add them to your "Shelf" by simply adding a few classes to your html:
49
50
51 <div class="simpleCart_shelfItem">
52 <h2 class="item_name"> Awesome T-shirt </h2>
53 <input type="text" value="1" class="item_Quantity">
54 <span class="item_price">$35.99</span>
55 <a class="item_add" href="javascript:;"> Add to Cart </a>
56 </div>
57
58
59 You can use almost any type of html tag, and set any values for the item you want by adding a class of "item_[attrname]".
60 Here is a more complex item with options and images:
61
62 <div class="simpleCart_shelfItem">
63 <img src="/images/item_thumb.jpg" class="item_thumb" />
64 <h2 class="item_name"> Awesome T-shirt </h2>
65 <select class="item_size">
66 <option value="Small"> Small </option>
67 <option value="Medium"> Medium </option>
68 <option value="Large"> Large </option>
69 </select>
70 <input type="text" value="1" class="item_Quantity">
71 <span class="item_price">$35.99</span>
72 <a class="item_add" href="javascript:;"> Add to Cart </a>
73 </div>
74
75
76 Please check out our documentation to see all of the options simpleCart has available!
77
78
085dea3 @brettwejrowski merged v3 to master
brettwejrowski authored
79 ## Version 3 Documentation
436b5af changed readme to .md
Brett Wejrowski authored
80
085dea3 @brettwejrowski merged v3 to master
brettwejrowski authored
81 A work in progress..... I'm putting it here until we
436b5af changed readme to .md
Brett Wejrowski authored
82 have the new site up so I can put it...well.. there.
085dea3 @brettwejrowski merged v3 to master
brettwejrowski authored
83
436b5af changed readme to .md
Brett Wejrowski authored
84
85 ##simpleCart(js) Setup/Initialization
86
87 simpleCart(js) _requires using jQuery, Prototype, or Mootools_. No extra configuration
9a1ba27 updated readme and minified
Brett Wejrowski authored
88 is needed as long as one of those libraries is included on the page
436b5af changed readme to .md
Brett Wejrowski authored
89
90 You can set/change simpleCart options at any time:
91
92 simpleCart({
93 option1: "value" ,
94 option2: "value2"
95 });
96
97
98 Here are the possible options and their default values:
99
100 simpleCart({
101
102 // array representing the format and columns of the cart, see
103 // the cart columns documentation
104 cartColumns: [
105 { attr: "name" , label: "Name" },
106 { attr: "price" , label: "Price", view: 'currency' },
107 { view: "decrement" , label: false },
108 { attr: "quantity" , label: "Qty" },
109 { view: "increment" , label: false },
110 { attr: "total" , label: "SubTotal", view: 'currency' },
111 { view: "remove" , text: "Remove" , label: false }
112 ],
113
114 // "div" or "table" - builds the cart as a table or collection of divs
115 cartStyle: "div",
116
117 // how simpleCart should checkout, see the checkout reference for more info
118 checkout: {
119 type: "PayPal" ,
120 email: "you@yours.com"
121 },
122
123 // set the currency, see the currency reference for more info
124 currency: "USD",
125
126 // collection of arbitrary data you may want to store with the cart,
127 // such as customer info
128 data: {},
129
130 // set the cart langauge (may be used for checkout)
131 language: "english-us",
132
133 // array of item fields that will not be sent to checkout
134 excludeFromCheckout: [],
135
136 // custom function to add shipping cost
137 shippingCustom: null,
138
139 // flat rate shipping option
140 shippingFlatRate: 0,
141
142 // added shipping based on this value multiplied by the cart quantity
143 shippingQuantityRate: 0,
144
145 // added shipping based on this value multiplied by the cart subtotal
146 shippingTotalRate: 0,
147
148 // tax rate applied to cart subtotal
149 taxRate: 0,
150
151 // true if tax should be applied to shipping
152 taxShipping: false,
153
154 // event callbacks
155 beforeAdd : null,
156 afterAdd : null,
157 load : null,
158 beforeSave : null,
159 afterSave : null,
160 update : null,
161 ready : null,
162 checkoutSuccess : null,
163 checkoutFail : null,
164 beforeCheckout : null
165 });
166
167
168
169 ##The Shelf
170
58f4120 working on docs for currency and events
Brett Wejrowski authored
171 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:
172
173 <div class="simpleCart_shelfItem">
174 <h2 class="item_name"> Awesome T-shirt </h2>
175 <select class="item_size">
176 <option value="Small"> Small </option>
177 <option value="Medium"> Medium </option>
178 <option value="Large"> Large </option>
179 </select>
180 <input type="text" value="1" class="item_Quantity">
181 <span class="item_price">$35.99</span>
182 <a class="item_add" href="javascript:;"> Add to Cart </a>
183 </div>
184
185 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.
186
187 ####Some notes:
188 *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.
189 *If you are planning on checking out to googleCheckout or paypal, it is a good idea to use a name field
190 *If you use a link for the add to cart button, its a good idea to set the href to `"javascript:;"`
191
436b5af changed readme to .md
Brett Wejrowski authored
192 ##Cart Columns
193
58f4120 working on docs for currency and events
Brett Wejrowski authored
194 The Cart Columns allow the user to specify how the cart will be formatted and displayed. There is a lot of flexibility here, take a look at the default setup:
195
196 simpleCart({
197 cartColumns: [
198 { attr: "name" , label: "Name" } ,
199 { attr: "price" , label: "Price", view: 'currency' } ,
200 { view: "decrement" , label: false , text: "-" } ,
201 { attr: "quantity" , label: "Qty" } ,
202 { view: "increment" , label: false , text: "+" } ,
203 { attr: "total" , label: "SubTotal", view: 'currency' } ,
204 { view: "remove" , text: "Remove" , label: false }
205 ]
206 });
207
09f5e9c readme
Brett Wejrowski authored
208 Each column is represented by an object, the most basic setup simple specifies which attribute to display and how to label the column:
58f4120 working on docs for currency and events
Brett Wejrowski authored
209
36f5be8 checkout docs
Brett Wejrowski authored
210 { attr: "name" , label: "Name" }
09f5e9c readme
Brett Wejrowski authored
211
212 There are also some built in 'views' that will create a special column. For example, an 'increment' view:
213
36f5be8 checkout docs
Brett Wejrowski authored
214 { view: "increment" , label: false , text: "+" }
12f193c using .html instead of .text so currency chars aren't escaped
Brett Wejrowski authored
215
90900b7 docs n docs n docs. yay!
Brett Wejrowski authored
216 will have a link that increments the quantity. Setting the `label:false` will hide the label for the view. You can specify the text of the link with that `text:` attribute.
58f4120 working on docs for currency and events
Brett Wejrowski authored
217
218 You can add `view: "currency"` to format the column as currency (see the currency section on more information on currency formatting).
219
220
436b5af changed readme to .md
Brett Wejrowski authored
221 **For more information, please go to simplecartjs.com**
222
Something went wrong with that request. Please try again.