====== JSON and JSONP with FoxyCart ======
===== What is JSON? =====
''JSON'' stands for JavaScript Object Notation ((More about JSON on [[wp>JSON|Wikipedia]] and [[http://json.org/|json.org]].)), and can be thought of as a very flexible method to store data. Conceptually it is similar to XML, but since it's actually a javascript object it's trivially easy to work with in javascript (whereas XML requires much more work to process by javascript).
FoxyCart's JSON looks like this:
{
"products":[
{
"id": "3045365",
"name": "Test Product",
"code": "foo123",
"image": "",
"url": "",
"length": "0",
"width": "0",
"height": "0",
"options": {"color":"red"},
"quantity": 1,
"price_each": 10,
"price": 10,
"weight_each": 1,
"weight": 1,
"shipto": "",
"category": "DEFAULT",
"sub_frequency": "",
"sub_startdate": "0000-00-00",
"sub_nextdate": "0000-00-00",
"sub_enddate": "0000-00-00"
},
{
"id": "3045366",
"name": "Second Product",
"code": "bar456",
"image": "",
"url": "",
"length": "0",
"width": "0",
"height": "0",
"options": {},
"quantity": 1,
"price_each": 100,
"price": 100,
"weight_each": 1,
"weight": 1,
"shipto": "",
"category": "DEFAULT",
"sub_frequency": "",
"sub_startdate": "0000-00-00",
"sub_nextdate": "0000-00-00",
"sub_enddate": "0000-00-00"
},
{
"id": "3045367",
"name": "Example Subscription",
"code": "xyz456",
"image": "",
"url": "",
"length": "0",
"width": "0",
"height": "0",
"options": {"color":"red"},
"quantity": 1,
"price_each": 6,
"price": 6,
"weight_each": 4,
"weight": 4,
"shipto": "",
"category": "DEFAULT",
"sub_frequency": "1m",
"sub_startdate": "2010-10-15",
"sub_nextdate": "2010-11-15",
"sub_enddate": "2013-01-01"
}
],
"product_count": 3,
"total_item_price": 116,
"total_discount": -5,
"total_price": 111,
"total_weight": 6,
"session_id": "9bpdjvm2ju0bulm6d7kkcf6d31",
"coupons":{
"test2":{
"id":"201",
"name":"test for line item coupon discount",
"discount":-5}
},
"custom_fields":{
"my_hidden_value":"I'm hidden!",
"example_hidden":"value_1"
},
"messages":{
"errors":[],
"warnings":[],
"info":[]
}
}
===== What is JSONP? =====
''JSONP'' is a magical tool that allows for relatively easy cross-domain javascript calls, which is impossible in most other ways (barring HTML5 functionality). We recommend [[wp>JSON#JSONP|getting a thorough understanding]], but the basic idea is this: You make a call to an endpoint (your FoxyCart cart) and you get back ''JSON'' //wrapped inside of a function call//. The reason for the function is so that your javascript can actually //do something// with the JSON you retrieve.
jQuery [[http://api.jquery.com/jQuery.getJSON/|makes this easy]], so let's try a quick example of retrieving the total number of products and the total cart price, less any discounts.
jQuery.getJSON('https://'+storedomain+'/cart?'+fcc.session_get()+'&output=json&callback=?', function(cart) {
console.info(cart.product_count);
console.info(cart.total_price);
console.info(cart.total_discount);
var total_price = cart.total_price - cart.total_discount;
console.log('You have '+cart.product_count+' products in your cart, totalling $'+total_price+' (which is after a $'+cart.total_discount+' discount).');
});
To try this out:
- Use Firefox to open up your website to a page where you have FoxyCart-powered add-to-cart links or forms.
- Add a product to your cart.
- Open [[http://getfirebug.com/|Firebug]]'s "console" tab and paste the above code into the command line, then run it.
- Look at your "Net" tab in Firebug to examine the request and response. Notice how the request substituted the ''?'' in the ''callback=?'' with something like ''jsonp1287171163698''. Then notice that the ''JSON'' response is wrapped inside a ''jsonp1287171163698()'' function call. That's the magic of ''JSONP''.
What it's actually doing is using jQuery's ''getJSON'' method to request your cart URL. The ''fcc.session_get()'' is inserting the FoxyCart session, so the right cart is actually retrieved, the ''output=json'' tells FoxyCart to return ''JSON'' and not the normal ''HTML'' cart, and the ''callback=?'' tells both FoxyCart and jQuery that it's a ''JSONP'' request. More about the ''output'' and ''callback'' parameters are on [[..:cheat_sheet|the cheat sheet#transaction_non-product_specific_options]].
The ''function(cart)'' bit is the "callback", and is run once the ''JSON'' is ready to be processed (after a momentary delay to actually make the request from the FoxyCart servers). It is passed in ''cart'', so you access the ''JSON'' as ''cart'' in the callback function. (This could just as easily be ''data'' or ''foo'' or ''ilovepuppies''. The important thing is that it's consistent, but ''data'' is a good choice. We've used ''cart'' in the example to make it clear that you're basically playing with the cart data itself.)
===== Modifying or Removing Items with JSONP =====
If you want to update the **quantity** of a specific item, send this:
&cart=update&quantity=&id=
If you want to modify multiple quantities at once you can prefix the separate products with a number prefix, similar to adding multiple products to the cart at the same time. Note that if you take this approach you //must// start at 1 and count up from there.
&cart=update&1:quantity=0&1:id=&2:quantity=0&2:id=
Note that the ''cart=update'' is required for these operations to function.
Unfortunately, modifying products in the cart beyond the quantity is not currently possible.
===== Adding a Coupon or Session Value Automatically Using JSONP =====
If you want to add a coupon code, affiliate tracking value, member group, user ID, or any other value to your visitor's FoxyCart session automatically and in the background you could use something like this:
That uses a ''setTimeout'' to wait 1.5 seconds((While this shouldn't need a ''setTimeout'', as of v0.7.0 it does. We'll be updating that in future versions.)), then check to see if a value already exists in the JSON (in this case we're checking to see if any coupons have been added to the session). If no that node in the ''FC.json'' object is undefined, we will use a JSONP call to add the coupon to the session. This is just an example, but hopefully it's useful in crafting your own scripts.
===== Important Notes for JSON(P) Implementations =====
The most critical thing about making successful JSON(P) calls to FoxyCart is remembering to include the ''fcsid'' (FoxyCart Session ID) in the request. The [[.:javascript|foxycart.js]] file includes a few helper functions, most notably the ''session_get()'' method (which you can see in action above), which will output a string like ''&fcsid=abc123su2eoba8r9oknf7qa4b3''. Please review the ''session_get()'' method below:
{{section>.:javascript#session_get_appending_the_fcsid_to_requests&noeditbutton&permalink&footer&nodate&nouser}}