Differences

This shows you the differences between two versions of the page.

--- v:0.7.0:advanced:javascript [2010/09/23 00:36] – foxybrett
+++ v:0.7.0:advanced:javascript [2017/04/26 07:02] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
-====== FoxyCart's Javascript, JSON, and JSONP ======
+====== FoxyCart's Javascript: foxycart.js ======
 FoxyCart's ''foxycart.js'' file is full of goodies that you probably won't ever need to think twice about. If default configurations are an anathema to you, if you need to get advanced for a custom integration, or if you're just curious about what's under the hood please explore this page and the "raw" version of the ''foxycart.js'', and [[http://forum.foxycart.com|let us know]] if you have any questions.
@@ Line 8: / Line 8: @@
   * Automatically (mostly) handles determining at what level to set your store's FoxyCart cookie. (ie. Determines to set it at ''.example.com'' or ''.example.co.uk'' or ''.custom.example.com''.)
   * Makes it easy for custom events or validation to be run before products are added to the cart.
-  * Makes it easy for custom events on an attempted add-to-cart (ie. the default [[http://colorpowered.com/colorbox/|Colorbox]] modal window, custom JSONP functionality, etc.).
+  * Makes it easy for custom events on an attempted add-to-cart (ie. the default [[http://colorpowered.com/colorbox/|Colorbox]] modal window, custom [[.:json|JSONP]] functionality, etc.).
   * Makes it easy for custom events or validation to be run //after// products are added to the cart.
   * Automatically attaches ''onclick'' and ''onsubmit'' handling to all links and forms (even dynamically created elements) pointing to your store's FoxyCart cart URL.
-  * Keeps the FoxyCart JSON object (''FC.json'') current before and after cart requests.
+  * Keeps the FoxyCart [[.:json|JSON]] object (''FC.json'') current before and after cart requests.
   * Alerts if jQuery isn't loaded.
@@ Line 18: / Line 18: @@
 ===== Available Files =====
-  * ''http://cdn.foxycart.tld/YOURDOMAIN/foxycart.complete.js'': Compressed. Includes the code to automatically set your store's domain, your store's FoxyCart domain, to initialize the ''FC'' object as ''fcc'', and to attach [[http://colorpowered.com/colorbox/|Colorbox]] to all add-to-cart links and forms.
+  * ''http://cdn.foxycart.com/YOURDOMAIN/foxycart.complete.js'': Compressed. Includes the code to automatically set your store's domain, your store's FoxyCart domain, to initialize the ''FC'' object as ''fcc'', and to attach [[http://colorpowered.com/colorbox/|Colorbox]] to all add-to-cart links and forms.
-  * ''http://cdn.foxycart.tld/YOURDOMAIN/foxycart.js'': Compressed. Includes the code to automatically set your store's domain, your store's FoxyCart domain, and to initialize the ''FC'' object as ''fcc''.
+  * ''http://cdn.foxycart.com/YOURDOMAIN/foxycart.js'': Compressed. Includes the code to automatically set your store's domain, your store's FoxyCart domain, and to initialize the ''FC'' object as ''fcc''. Note that the ''preprocess'' and ''process'' events don't actually have any behavior in this version of the file, and that ''postprocess'' is not referenced at all, since ''postprocess'' should be called by whatever ''process'' events you've defined.
-  * ''http://cdn.foxycart.tld/YOURDOMAIN/foxycart.raw.js'': Uncompressed. Does not set your store's domain, your store's FoxyCart domain, nor does it initialize the ''fcc'' object. This will generally only be used for special circumstances or advanced users needing access to the uncompressed code.
+  * ''http://cdn.foxycart.com/YOURDOMAIN/foxycart.raw.js'': Uncompressed. Does not set your store's domain, your store's FoxyCart domain, nor does it initialize the ''fcc'' object. This will generally only be used for special circumstances or advanced users needing access to the uncompressed code.
 ===== What's Different from Previous Versions =====
 Almost everything but some of the ways that sessions are set has been rewritten, but here are the main changes from the ''foxycart_includes.js'' in v0.6.0:
@@ Line 28: / Line 28: @@
   * ''fc_BuildFoxyCart()'' has similarly been changed to a ''postprocess()'' method described below.
   * Setting the FoxyCart Session ID (''fcsid'') at a subdomain, third-level domain, or specific path is now possible without rewriting core functions.
+  * ''fc_AddSession'' doesn't exist anymore, the current session can be retrieved using ''fcc.session_get()''. Note that the new javascript uses jQuery's ''live()'' event to find any links or forms that are directed at FoxyCart and adds the session to them automatically, so you don't generally have to use this. If you are altering the href of a link dynamically though, you will need to re-add the session to the updated href, otherwise FoxyCart will assume its a new link and you'll get double ups on the process functions (ie: 2 carts in colorbox).
+  * ''fc_tb_show'' doesn't exist anymore as 070 now uses colorbox as the default modal window. If you check out the ''foxycart.js'' you add to your page, you can see the colorbox being initialized there. Its just a vanilla colorbox implementation so you can use colorbox for whatever else you need modals for too.
@@ Line 42: / Line 44: @@
 This setting is only important if your site isn't at the second-level domain, or if you want to restrict your FoxyCart sessions by subdomain. For example, if your site is ''example.co.uk'', you don't want the cookie set at ''.co.uk''. Or if you want to have different FoxyCart sites at ''donations.example.com'' and ''products.example.com'', you'd need the cookies //not// to be set at ''.example.com'' or the sessions would overlap with unexpected results. (Another example would be if your site is at a 3rd party provider like ''example.squarespace.com'', you don't want all ''*.squarespace.com'' sites sharing your FoxyCart sessions.)
-The only thing to keep in mind is that <wrap tip>the ''www'' subdomain is effectively ignored</wrap>, so if you //do// want to lock your sessions down to ''.www.example.com'' you'll need to set the ''sitedomain'' value to something like ''www1.example.com''. The actual value doesn't matter; it's only counting the dots in the value after it strips the ''www''.
+The only two things to keep in mind are:
+  - <wrap tip>The ''www'' subdomain is effectively ignored</wrap>, so if you //do// want to lock your sessions down to ''.www.example.com'' you'll need to set the ''sitedomain'' value to something like ''www1.example.com''. The actual value doesn't matter; it's only counting the dots in the value after it strips the ''www''.
+  - <wrap important>You //cannot// have the FoxyCart javascript at any other subdomains</wrap> if you are isolating by subdomain. For example, if you have two separate stores at ''products.example.com'' and ''donations.example.com'' you //cannot// also have your ''foxycart.js'' at ''www.example.com'' or ''example.com'', as that will set the session cookie at ''.example.com'', which will override the ''products'' and ''donations'' session cookies.
 ==== ''cookiepath'': The Path on Which Your Visitor's FoxyCart Cookies Are Set ====
 The ''cookiepath'' determines the ''fcsid'' cookie's path. This is almost always going to be empty, so the cookies would be set at ''.example.com'', but if you do need to have multiple FoxyCart sessions on the same domain you could use this setting to restrict cookies to something like ''.example.com/en/'' and ''.example.com/es/'' (to split English and Spanish FoxyCart stores, for example).
@@ Line 49: / Line 52: @@
 <wrap important>The ''cookiepath'' value must end in a ''/''</wrap> or you may run into issues, especially with Internet Explorer. The leading slash is automatically applied by the ''foxycart.js'', so if you want a path of ''/en/'' you would enter ''cookiepath = 'en/';''.
-===== "Mini-Cart" Display and Helper Functionality =====
+*Example:* Suppose you have a donations section and a bookstore, located at ''http://example.com/donations/'' and ''http://example.com/bookstore/''. (<wrap important>Note that the trailing slash is critical.</wrap> If you have something like ''http://example.com/bookstore'' and ''http://example.com/donations'' this method will not work and the sessions will collide.) Add the following code before your calls to ''foxycart.complete.js'' or ''foxycart.js''. Obviously, change out the "donations" with "bookstore" depending on where you're placing this code.
+<code html><script type="text/javascript" charset="utf-8">
+	if (typeof(cookiepath) == 'undefined') {
+		var cookiepath = 'donations/';
+	}
+</script></code>
+===== Helper Functions ====
+==== "Mini-Cart" Display and HTML Helper Functionality ====
 When the ''FC'' class is initialized (via the ''.init()'' method) and on the ''.cart_update()'' method, elements with the following classes or IDs are modified:
   * ''#fc_minicart'', ''.fc_minicart'': If the ''FC.json.product_count'' is greater than 0, these elements will be shown. Otherwise they'll be hidden
@@ Line 55: / Line 66: @@
   * ''#fc_total_price'', ''.fc_total_price'': The inner HTML will be replaced by the value in ''FC.json.total_price'', formatted using the ''_currency_format'' function (which adds decimals but doesn't add currency symbols).
+==== ''session_get'' Appending the FCSID to Requests ====
+=== What It Is ===
+The ''fcsid'' (FoxyCart Session ID) cookie stores the unique session ID of the customer, and is arguably the most important piece of a FoxyCart implementation. If the ''fcsid'' isn't sent to FoxyCart when the cart is requested, the customer will lose the entire contents of their cart, and may see other errors as well.
+=== How It Works: Overview ===
+When a webpage with ''foxycart.js'' loads, ''foxycart.js'' attempts to set a ''fcsid'' cookie according to the ''sitedomain'' and ''cookiepath'' values discussed above. Most of this is handled automatically
-===== Adding Your Own Events =====
+=== How It Works: Details ===
+The ''session_get'' method will look for and set an ''fcsid'' cookie with the value retrieved from (in this order):
+  - A hash in the loaded URL (ie. ''#fcsid=abc123'').
+  - An ''fcsid'' cookie.
+  - The ''FC.session_id'' in the [[.:json|JSON]].
+=== How To Use It: JSONP and Dynamically Modified Elements ===
+If you're generating actions (cart-adds, ''JSONP'' requests, dynamically changing an add-to-cart link's ''href'', etc.), you'll need to manually add the ''fcsid'' to your request. Luckily, this is fairly easy with the ''session_get()'' method. Assuming a normal ''foxycart.complete.js'' or ''foxycart.js'' inclusion in your template, you would create the link or ''JSONP'' URL like this (in javascript):
+<code javascript>
+// Just the link to the cart itself
+var cart_request = 'https://'+storedomain+'/cart?'+fcc.session_get();
+// Adding a product
+var cart_request = 'https://'+storedomain+'/cart?name=Test_Product&price=9.99'+fcc.session_get();
+// Retrieving the cart via JSONP
+jQuery.getJSON('https://'+storedomain+'/cart?'+fcc.session_get()+'&output=json&callback=?', function(data) {
+	// callback function goes here
+});
+</code>
+The ''fcc.session_get()'' call will return something like ''&fcsid=abc123su2eoba8r9oknf7qa4b3''. If you just need the ''fcsid'' value itself you can easily retrieve it from the ''JSON'' with ''FC.session_id''.
+<wrap important>Are you **//creating//** or **//modifying//** elements?</wrap> If you're dynamically //creating// add-to-cart links or forms, you don't need to bother with this at all. It will be handled automatically. If however you're //modifying// the ''href'' of an add-to-cart link that was present on pageload you //do// need to append the ''fcsid''. This has to do with how FoxyCart binds ''onclick'' handlers to elements while also making it easy to add new add-to-cart link or form elements.
+===== Adding Your Own Events =====
+The following "events" below have the following methods:
+  * ''add'': Adds the function to the event's function array.
+  * ''add_pre'': Adds the function to the event's function array //before// any other functions in the array.
+  * ''execute'': Execute's all the functions in the array, stopping if ''false'' is returned. (This is mostly an internal method, and won't likely be used by even very advanced integrations.)
 ==== ''preprocess'': Before an Add-To-Cart ====
 === What It Is ====
@@ Line 64: / Line 108: @@
 === How It Works: Overview ===
-When a link or form pointing to your FoxyCart's cart URL (ie. ''https://example.foxycart.tld/cart'') is clicked or submitted, ''foxycart.js'' first checks to see if any functions have been added to your ''preprocess'' array. If any functions exist, they are run in order of entry (first-in-first out) passing in two arguments:
+When a link or form pointing to your FoxyCart's cart URL (ie. ''https://example.foxycart.com/cart'') is clicked or submitted, ''foxycart.js'' first checks to see if any functions have been added to your ''preprocess'' array. If any functions exist, they are run in order of entry (first-in-first out) passing in two arguments:
   - The submitted element itself.
   - An array of name/value pairs to be submitted to the cart-add request. This array is built using an "unserialize" function inside the ''FC'' object.
@@ Line 117: / Line 161: @@
 The ''process'' functionality is nearly identical to the ''preprocess'' functionality described above, but whether ''true'' or ''false'' is returned may be a bit more nuanced. Generally you'll only want _one_ event in the ''process'' array, though you can have more if necessary.
-One thing to keep in mind is that a ''return false;'' is probably desired if you actually do anything here, such as a ''JSONP'' request or a modal window call, since //that// is where the item is added to the cart. If you don't return ''false'' then the add-to-cart link or form will fire and the request will likely be duplicated.
+One thing to keep in mind is that a ''return false;'' is probably desired if you actually do anything here, such as a [[.:json|JSONP request]] or a modal window call, since //that// is where the item is added to the cart. If you don't return ''false'' then the add-to-cart link or form will fire and the request will likely be duplicated.
 === How It Works: Details ===

Differences

Page Tools

Site Tools

User Tools