====== 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 includes the details of the customers cart, as well as store configuration settings and other variables relating to both the customer and the page. For an overview of all the different variables that are included within the FoxyCart JSON, see the [[v:2.0:templates:view_data|Templates View Data]] page.

===== 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.

===== Making a JSONP call to the cart =====

Triggering a JSONP call to the cart is easy in 2.0 - there's a simple helper to make the request and get back the JSON you need to update things on your end. All you need to do is pass it a URL like this:

<code javascript>FC.client.request('https://'+FC.settings.storedomain+'/cart?name=My+Product&price=20');</code>

That function call will add a product called "My Product" to the cart priced at $20. On completion, ''client.updateJSON();'' is called, as well as ''FC.session.initialize()'' or ''FC.session.reset()'' to ensure the correct session ID and cookie are set.

If you need to perform some custom actions after the request is completed though, you simply append a ''done()'' handler to the end, like this:

<code javascript>FC.client.request('https://'+FC.settings.storedomain+'/cart?name=My+Product&price=20').done(function(dataJSON) {
  // Perform custom code here 
});</code>

In that example, ''dataJSON'' will contain the up to date version of the JSON object, which will also match ''FC.json''.

If you want to render the cart or checkout after a request, put the ''render()'' function call in the ''done()'' callback, like this:
<code javascript>FC.client.request('https://'+FC.settings.storedomain+'/cart?empty=true').done(function() {
     FC[FC.json.context].render();
});</code>

===== Modifying or Removing Items with JSONP =====
If you want to update the **quantity** of a specific item, send this with the add to cart URL: 
<code>
&cart=update&quantity=<new quantity>&id=<product id from json>
</code>

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.
<code>
&cart=update&1:quantity=0&1:id=<product id from json>&2:quantity=0&2:id=<product id from json>
</code>

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:
<code javascript>
FC.client.on('ready.done', function () {
  // Automatically add a coupon
  if ($.isEmptyObject(FC.json.coupons)) {
    FC.client.request('https://'+FC.settings.storedomain+'/cart?coupon=YOUR_COUPON_CODE').done(function() {
        if (FC.util.hasError('coupon')) {
            FC.util.removeError('coupon');
        }
    });
  }
  // Add a hidden session variable
  FC.client.request('https://'+FC.settings.storedomain+'/cart?h:foo=bar');
});
</code>

This function hooks into the ''ready.done'' event to ensure that the FoxyCart JSON object has been loaded, and checks if the coupons object is empty. If it is, it then triggers the request to add a coupon to the cart, and removes any coupon errors in case it's expired or removed. This is just a simple example, but hopefully gives you an idea of how to get started.

If you want to run code like that on pageload //of your own website//, you'd need to wrap it in the [[.:javascript#accessing_the_fc_object_on_your_own_website|FC.onLoad() wrapper]], like this:
<code javascript>
var FC = FC || {};
FC.onLoad = function () {
	FC.client.on('ready.done', function () {
		FC.client.request('https://'+FC.settings.storedomain+'/cart?h:foo=bar');
	});
};
</code>
===== 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. You can get this from ''FC.json.session_name'' and ''FC.json.session_id'', or the complete URL parameter like this like ''fcsid=nf0237u4ng0ed7'' through ''FC.session.get()'':

<code javascript>var url = "https://" + FC.settings.storedomain + "/cart?name=My+Product&price=25&" + FC.session.get();</code>

<WRAP center round info 90%>
If you make use of the standard ''FC.client.request()'' function for running your request, it will automatically include the session ID for you. You only need to add the session yourself if performing your own requests.
</WRAP>