Using the Spiffy Ajax API - Revision history

Admin: /* Spiffy.getCart(callback) */

2015-08-28T02:59:16Z

Spiffy.getCart(callback)

Admin: /* Spiffy.formatMoney(price, format) */

2015-08-28T02:58:51Z

Spiffy.formatMoney(price, format)

Admin: /* Wrapper Library Function Reference */

2015-08-28T02:49:57Z

Wrapper Library Function Reference

Admin: /* POST /cart/clear.js */

2015-08-28T02:22:10Z

POST /cart/clear.js

Admin: /* POST /cart/clear.js */

2015-08-28T02:12:26Z

POST /cart/clear.js

Admin: /* POST /cart/change.js */

2015-08-27T07:44:53Z

POST /cart/change.js

Admin: /* POST /cart/change.js */

2015-08-27T07:42:57Z

POST /cart/change.js

Admin: /* POST /cart/change.js */

2015-08-27T07:11:27Z

POST /cart/change.js

Admin: /* POST /cart/change.js */

2015-08-27T07:02:41Z

POST /cart/change.js

Admin: /* POST /cart/update.js */

2015-08-27T07:01:26Z

POST /cart/update.js

@@ Line 56: / Line 56: @@
 ==== <code>Spiffy.addItemFromForm(form_id, callback)</code> ====
-==== <cpde>Spiffy.getCart(callback)</code> ====
+==== <code>Spiffy.getCart(callback)</code> ====
 ==== <code>Spiffy.getProduct(handle, callback)</code> ====

@@ Line 39: / Line 39: @@
 '${{amount}}'
 </pre>
 == Spiffy Ajax API Reference ==

← Older revision		Revision as of 02:49, 28 August 2015
Line 19:		Line 19:

	== Wrapper Library Function Reference ==		== Wrapper Library Function Reference ==
		+
		+	=== Utility Functions ===
		+
		+	==== <code>Spiffy.formatMoney(price, format)</code> ====
		+
		+	Returns a formatted string, given a numberic price and optional format string.
		+
		+	The price is the floating-point value in the base unit of currency. For example, the price 1234.45 would be formatted as ''$1,234.56'' using the default format.
		+
		+	The format string can include any characters, along with a substitution variable with the following values:
		+
		+	* amount - Default formatting for the currency
		+	* amount_no_decimals - Uses only the base currency unit
		+	* amount_with_comma_separator - Uses a comma to specify the decimals
		+	* amount_no_decimals_with_comma_separator - Uses a comma decimal separator
		+
		+	For example, the default format string is
		+	<pre>
		+	'${{amount}}'
		+	</pre>

	== Spiffy Ajax API Reference ==		== Spiffy Ajax API Reference ==

@@ Line 564: / Line 564: @@
 <pre>
+{
-   "token": "1d19a32178501c44ef2223d73c54d16d",
+   "token": "618409804635da614f1060f363bec493",
-   "note": null,
+   "note": "",
-   "attributes": {},
+   "attributes": "",
-   "total_price": 0,
+   "total_price": "0.00",
    "total_weight": 0,
    "item_count": 0,
-   "items": [],
+   "items": [
-   "requires_shipping": false
+}
 </pre>
-Ajax requests that update the cart must be queued and sent synchronously to the server. Meaning: you must wait for your 1st ajax callback, to send your 2nd request, and then wait for its callback to send your 3rd request, etc.
+A request queue can be created simply by using a Javascript array.
+<pre>
 Spiffy.queue = [];
-As you examine your quantity fields, you will add requests to that queue:
+All you need to do is to search through all the quantity fields, and add the requests to the queue.
+<pre>
 jQuery('.quantity').each(function() {
    Spiffy.queue.push( {
      variantId: jQuery(this).data('variant-id'),
      quantity: parseInt(jQuery(this).val(), 10) || 0
-   } );
+   });
 });
-When you are done, you start your engine, using for instance Spiffy.addItem.
+Once the queue is ready to process, you can call the Ajax API, using the wrapper function '''Spiffy.addItem''' for example.
-The callback of this Ajax request should call a function that shifts (removes) a request from Spiffy.queue and then call Spiffy.addItem with the variantId and quantity stored in the next request. Of course, you'll check if the queue has any requests left in it. If it's empty, you must cheerfully redirect to the cart page.
+The callback for this Ajax request should be a function that removes the most recently processed request from '''Spiffy.queue''' and then calls '''Spiffy.addItem''' again to process the next request, for as long as requests remain in the queue to be processed.
-Something like this:
+For example:
+<pre>
-Spiffy.moveAlong = function() {
+Spiffy.procesQueue = function() {
-  // If we still have requests in the queue, let's process the next one.
+   if (Spiffy.queue.length > 0) {
      var request = Spiffy.queue.shift();
-     Spiffy.addItem(request.variantId, request.quantity, Spiffy.moveAlong);
+     Spiffy.addItem(request.variantId, request.quantity, Spiffy.processQueue);
+   } else {
-  // If the queue is empty, we will redirect to the cart page.
+    // If the queue is empty, then redirect back to the cart page.
      document.location.href = '/cart';
+   }
 };
+</pre>

@@ Line 559: / Line 559: @@
 === <code>POST /cart/clear.js</code> ===
-This call sets all quantities of all line items in the cart to zero.
+This call empties the cart by setting the quantities of all line items in the cart to zero.
+{
    "token": "1d19a32178501c44ef2223d73c54d16d",
@@ Line 575: / Line 573: @@
    "requires_shipping": false
+}
 Ajax requests that update the cart must be queued and sent synchronously to the server. Meaning: you must wait for your 1st ajax callback, to send your 2nd request, and then wait for its callback to send your 3rd request, etc.

@@ Line 555: / Line 555: @@
 The '/cart/change.js' call can only update the quantity of one line item at a time, and that line item must alreay be in the cart.
-If the item is not in the cart, '/cart/change.js' will not add it and it will then return a 404 error.
+If the item is not in the cart, '/cart/change.js' will not add it.
 === <code>POST /cart/clear.js</code> ===

@@ Line 549: / Line 549: @@
 </pre>
-The '''/cart/update.js''' and '''/cart/change.js''' calls appear to do very similar things, but there are important differences.
+The '/cart/update.js' and '/cart/change.js' calls appear to do very similar things, but there are important differences.
-The '''/cart/update.js''' call allows several line items to be updated at once, including items that may not yet be in the cart. These new items will be automatically added to the cart. In addition, the cart note and attributes can also be updated using this call.
+The '/cart/update.js' call allows several line items to be updated at once, including items that may not yet be in the cart. These new items will be automatically added to the cart. In addition, the cart note and attributes can also be updated using this call.
-The '''/cart/change.js''' call can only update the quantity of one line item at a time, and that line item must alreay be in the cart.
+The '/cart/change.js' call can only update the quantity of one line item at a time, and that line item must alreay be in the cart.
-If the item is not in the cart, /cart/change.js will not add it and it will then return a 404 error. Whereas the /cart/update.js controller updates no quantity when any of the requested update cannot be met, the /cart/change.js controller, on the other hand, will adjust the quantity to add all items in stock if what is requested is greater than what's available. Use your browser's JavaScript console to test things out if you're not sure about the behavior of the different request URLs.
+If the item is not in the cart, '/cart/change.js' will not add it and it will then return a 404 error.
 === <code>POST /cart/clear.js</code> ===

@@ Line 516: / Line 516: @@
 This call updates the quantity of an item already in the cart.
-POST data
+POST data is required and takes the form:
+{
-   quantity: 1,
+   id: '334234_1',
-   id: 794864053
+   quantity: 2
+}
-Response The JSON of the cart.
+The ''quantity'' indicates how many items you wish to add to the cart for the specified variation.
-If you use Line Item Properties you may end up with several items in the cart that share the same variant ID. How do you update the quantity of an item in the cart that has specific line item properties? Once you have identified the 1-based index of the item in the cart, you can use the line property instead of id like so:
+The cart is returned in response to this call in JSON format.
+{
-   quantity: 1,
+   line: 1,
-   line: 1
+   quantity: 10
+}
-jQuery.post('/cart/change.js', { quantity: 1, line: 1 });
+The '''/cart/update.js''' call allows several line items to be updated at once, including items that may not yet be in the cart. These new items will be automatically added to the cart. In addition, the cart note and attributes can also be updated using this call.
-Caution
+The '''/cart/change.js''' call can only update the quantity of one line item at a time, and that line item must alreay be in the cart.
-Although /cart/update.js and /cart/change.js may seem like they accomplish the same function, they truly are quite different. The /cart/update.js controller allows updates to several items at once, including items that may not yet be in the cart (it will add them), and it also allows updates of cart attributes and the cart note. The /cart/change.js controller is only able to update the quantity of one item at a time, and that item must be in the cart already. If the item is not in the cart, /cart/change.js will not add it and it will then return a 404 error. Whereas the /cart/update.js controller updates no quantity when any of the requested update cannot be met, the /cart/change.js controller, on the other hand, will adjust the quantity to add all items in stock if what is requested is greater than what's available. Use your browser's JavaScript console to test things out if you're not sure about the behavior of the different request URLs.
+If the item is not in the cart, /cart/change.js will not add it and it will then return a 404 error. Whereas the /cart/update.js controller updates no quantity when any of the requested update cannot be met, the /cart/change.js controller, on the other hand, will adjust the quantity to add all items in stock if what is requested is greater than what's available. Use your browser's JavaScript console to test things out if you're not sure about the behavior of the different request URLs.
 === <code>POST /cart/clear.js</code> ===

@@ Line 514: / Line 514: @@
 === <code>POST /cart/change.js</code> ===
-This call sets the quantity of an item already in the cart.
+This call updates the quantity of an item already in the cart.
 POST data

@@ Line 423: / Line 423: @@
 <pre>
+{
-   updates: {12345: 2, 67890: 3}
+   updates: { 12345: 2, 67890: 3 }
+}
 </pre>
@@ Line 470: / Line 470: @@
 <pre>
-jQuery.post('/cart/update.js', {updates: {2345345: 2, 364566: 3}});
+jQuery.post('/cart/update.js', { updates: { 2345345: 2, 364566: 3 } });
 </pre>
@@ Line 480: / Line 480: @@
 Similarly, a single line item can be updated as follows:
 <pre>
-jQuery.post('/cart/update.js', {updates: {2345345: 2}});
+jQuery.post('/cart/update.js', { updates: { 2345345: 2 } });
 </pre>
 Finally, line items can be removed from the cart by setting their quantity to zero:
 <pre>
-jQuery.post('/cart/update.js', {updates: {2345345: 0, 364566: 0}});
+jQuery.post('/cart/update.js', { updates: { 2345345: 0, 364566: 0 } });
 </pre>
-The properties of a line item can be set when an item is added to the cart. This means that the same variation can exist more than once in a cart.
+The properties of a line item can be set when an item is added to the cart. This means that the same variation can exist more than once in a cart, as each line item can have different customization data.
-If you use Line Item Properties you may end up with several items in the cart that share the same variant ID. How do you update the quantity of items in the cart when that happens? It turns out that you can also submit an array of numbers to /cart/update.js, where the size of the array will need to match the amount of line items in the cart.
+This means that it may not be possible to identify a unique variation in a cart by its '''id''', as multiple line items in the cart may have the same '''id'''.
-Example, say you have 3 line items in the cart, with quantities 1, 2 and 3, and you want to change those quantities to 3, 2 and 1, you can use the following:
+If this is the case, then the only way to update the line item quantities is to provide an array of new quantities for each line item, where the order of elements in the array matches the order of line items in the cart.
-jQuery.post('/cart/update.js', {updates: [3, 2, 1]});
+When you use this method of updating line items, the number of elements in the array must match the number of line items in the cart.
-If there's any problem with updating any quantity when submitting an array of number, there will be a 422 error, and the quantities will remain the same as they were.
+For example, if you have 3 line items in the cart, with quantities 1, 2 and 3, and you want to update these quantities to 3, 2 and 1, you can use the following example:
-To change the quantity of one line item, you will need to use /cart/change.js instead (see the following section) and provide the 1-based index of the item in the cart like so:
+<pre>
 jQuery.post('/cart/change.js', { line: 1, quantity: 1 });
-To change the quantity of the second line item in the cart, you'll use this:
+Similarly, to change the quantity of the second line item in the cart, we use this example:
+<pre>
 jQuery.post('/cart/change.js', { line: 2, quantity: 1 });
 === <code>POST /cart/change.js</code> ===