Documentation You are here: start » v » 1.0 » cart

Table of Contents

The Cart of The Foxy

What Is The Cart?

The “cart” in “FoxyCart” is where your products are stored for each visitor to your website. The cart itself is highly flexible, and can be loaded as HTML or as JSON, allowing for unlimited customization potential.

When we say “the cart” we will generally be referring to the cart when it is loaded by itself, but a representation of the cart is also usually included on the checkout, the receipt, and email receipts. When the cart is included in those sections it is static, only displaying its current contents. When you're interacting with it directly is where you'll see it in action.

The Standard (HTML) Cart Implementation

The default approach to the cart is to display it as HTML inside an iframe, loaded in an excellent jQuery-powered modal window script, Colorbox. Using the “standard” theme it looks something like this:

The FoxyCart cart as HTML in an iframe, in a Colorbox-generated modal window

There are a few things to notice here:

  • Products, including all product options, quantities, and prices. Product thumbnails, if configured, are also displayed.
  • Quantity fields allow for modifying the quantity of products in the cart.
  • “X” links to remove the product from the cart.
  • A link to checkout using PayPal Express Checkout, if configured for the store.
  • A link to checkout normally, if a gateway is configured for the store.
  • A link to continue shopping.
  • A link to update, which is disabled and 50% transparent until a change is made to the cart (ie. a quantity is modified), in which case it transitions to 100% opaque while the checkout links fade to 50% transparent.
  • A link to add a coupon code, if active coupon codes exist for the store. (Otherwise this link will not be shown, as studies have shown that they can decrease conversion rates. Potential customers may leave your site to search for a coupon code, where they may become distracted or find a competitor.)
  • A subtotal and order total.

It's important to note that though this is what the FoxyCart-powered cart will look like by default, you can customize nearly every aspect to fit your specific needs.

Customizing Your Cart

Customizing the HTML version of your cart (as opposed to a JSON-based approach) is basically identical to customizing any other FoxyCart template, except that the cart by default loads in an iframe, which can be quite tricky to understand at first. The issue is that the default cart display (in the modal window) is actually two separate pieces:

  1. The HTML generated that’s part of your site's <body>, which is where the “continue shopping” or “x” link is (to close the modal window).
  2. The cart itself in an iframe, inside the modal window. This is an entirely separate HTML page, and thus cannot be styled by the parent frame’s CSS.

So, if you want to customize the cart itself, you need to add your new CSS to the cart template (as pasted in or cached in the FoxyCart admin). If you want to customize the “framing” of the modal window, that'd happen on your site, and not in the cart template in the FoxyCart admin. To get a feel for which is which, either use Firebug's DOM inspector, or right-click on the cart and view the frame in a new tab.

Customizing the Default Cart's Colorbox

As mentioned above, FoxyCart uses Colorbox, a very nice and flexible modal window script for jQuery, as the default modal window for FoxyCart's cart display. While you don't have to use Colorbox (and can indeed use any other modal window script or other method to display the cart), we provide some tips for quick customizations to Colorbox below.

Changing the Style

Colorbox includes five default styles by default, and we've added a modification of style1 to handle the “continue shopping” link. FoxyCart defaults to style1_fc, but you can replace that with any number one through five (ie. style2, style3, etc.) to try different themes. You can see demos of these themes at the Colorbox site. So to try different themes you'd just change the style1_fc in your stylesheet <link> tag: 

<link rel="stylesheet" href="http://static.foxycart.com/scripts/colorbox/1.3.16/style5/colorbox.css" type="text/css" media="screen" charset="utf-8" />

Changing the Size

By default, FoxyCart sets the size of the Colorbox to 70% of the browser's width and height. If you'd like to set this to bigger or smaller or explicit pixel values you can do so like this (using example values): 

	<script type="text/javascript" charset="utf-8">
		var colorbox_width = "500px";
		var colorbox_height = "70%";
	</script>

Just put that before your foxycart.complete.js call.

Avoiding box-sizing bugbears

If you are using 

* {box-sizing: border-box}

in your CSS file, you will need to override it for the colorbox to avoid having “cropped” right and bottom edges. Add the following to your CSS file underneath your original box-sizing statement: 

div#colorbox{
-moz-box-sizing: content-box; -webkit-box-sizing: content-box; box-sizing: content-box; }
}

This can be slightly confusing, but the “Continue Shopping” link in the cart is actually not part of your cart template, but part of the colorbox modal window by way of a customised close button. You can edit this in the same way as the size options described above: 

	<script type="text/javascript" charset="utf-8">
		var colorbox_close = '<span>&laquo;</span> Continue Shopping';
	</script>

Just put that before your foxycart.complete.js call.

If you want to change that link to be an image, or style it differently, you will need to add CSS styles to your *page* template (*NOTE:* not your cart template). The colorbox close button has an id of cbox_close, and to only alter the FoxyCart cart instance of colorbox's close button you can scope it as such: .fc_cbox #cbox_close

Interacting With the Cart

Adding Products to the Cart

Adding products to your cart is discussed in the products documentation.

Viewing the Cart

If you'd just like to load the cart without adding a product to it (ie. a “View Cart” button), you'd link to the cart like you were adding a product, but just include the cart=view option (as in /cart?cart=view) instead of any product options. This is discussed below in non-product cart parameters.

The Persistent "Mini-Cart"

Though you can get more advanced with the JSON cart interaction, FoxyCart's default javascript provides easy helper functions to create a persistent "mini-cart".

Bypassing Your Cart

There are a handful of reasons that you might want bypass the cart entirely and proceed either directly to your checkout, or somewhere else. For example, if you're selling just a single product, or a single conference registration, you might want to both empty the cart on a new product being added to the cart and then proceed directly to checkout. Or you may want to add the product to the cart but then redirect to an upsell page. A variety of options are available in this regard. Check the cart parameters section below for details.

Advanced (JSONP) Cart Implementations

If you've yawned at all of the above details about customization, if you need a highly specific cart display, or if you need to interact with the cart programmatically like via server-side programming or Flash, then the cart's JSON and JSONP functionality will be of interest. More details are here.

Non-Product Cart Parameters

Transaction Options are not product-specific. Instead, they impact the entire cart or session.

cart
Description: The cart parameter allows for various behaviors to be performed when the cart is requested. Note, these parameters are added after the cart page, like so: /cart?cart=view
Accepts:
  • add: The default cart action. If you don't include a cart input, add is assumed.
  • view: Displays the cart (if output=html) or returns the cart (if output=json) without adding any products to the cart. Custom session values can be added on a cart=view request.
  • checkout: Redirects to the checkout page immediately. Any “add to cart” requests are processed first, so you can add a product to the cart and go immediately to the checkout.
  • checkout_paypal_express: Redirects to PayPal for an Express Checkout immediately. Any “add to cart” requests are processed first, so you can add a product to the cart and go immediately to the checkout.
  • updateinfo: Redirects to the checkout page with the updateinfo flag set, allowing the customer to update their billing information without actually buying anything. This will empty the customer's cart. More info about the ''updateinfo'' functionality.
Default: view
h:…
(CUSTOM Session Values)
Description: “Session values”, as the name suggests, are added to the customer's session, and are not tied to products. Values stored in session values are available in the JSON, as well as the XML datafeed upon a successful transaction.
Accepts: Any h:name=value pair. The h: prefix on the name makes it a session value as opposed to a custom product option.
Notes: Session values are useful for synching custom fields between FoxyCart and your own system, or using information from an external system to manipulate FoxyCart. For example, you could pass in a customer ID value that would sync back to your own database. Or a referrer or affiliate ID could be added to the session and then processed via the XML datafeed upon a completed transaction.
empty
Description: This will clear the contents of the cart. If products are added in the same request, the cart will be emptied and then the products will be added.
Accepts: true
coupon
Description: Adds a coupon code directly to the cart.
Accepts: Any valid coupon code.
Notes: If an invalid code is added, or a code is re-added, an error may display on the cart. As with all coupon codes, once a code is added it will remain for the life of the session or until removed. This can be useful if you want to have a link with a coupon code that doesn't actually add a product to the cart but instead redirects to a order page or the website's homepage. Check the redirect option below for more.
Notes: If you're using the link and form validation, do not sign the coupon value.
redirect
Description: Immediately redirects the user to a page on cart load, such as &redirect=index.html.
Accepts: path/to/file.ext
Notes: For security reasons, the path must be at the store's domain (as entered in the store's FoxyCart settings). ie. You cannot redirect to example.org/path/to/file.ext if your store's domain in FoxyCart is example.com. Additionally, you may need to URL encode any ? and & symbols in a redirection path.
output
Description: Specify the output format for the cart request.
Accepts:
Default: html
callback
Description: Used to make an output=json request return a JSONP (instead of JSON) response. This will typically be used with a javascript library like jQuery.
fc_auth_token
Description: Used with Single Sign-On (SSO) to allow a customer to proceed through to the checkout.

Page Tools

Site Tools