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:
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:
- 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).
- 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.
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 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):
Just put that before your
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 instead of any product options. This is discussed below in non-product cart parameters.
The 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.
- Description: The
cartparameter 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
add: The default cart action. If you don't include a cart input,
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
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
updateinfoflag 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.
(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:prefix on the
namemakes 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.
- 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.
- 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
redirectoption below for more.
- Description: Immediately redirects the user to a page on cart load, such as
- 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.extif your store's domain in FoxyCart is
example.com. Additionally, you may need to URL encode any
&symbols in a redirection path.
- Description: Specify the output format for the cart request.
json(will load the JSON cart object)
- Description: Used to make an
- Description: Used with Single Sign-On (SSO) to allow a customer to proceed through to the checkout. ===== Customer Information Pre-Population ===== If you're considering pre-populating customer info on the checkout you should probably look at using the API and Single Sign-On (SSO) as well, as those two methods will provide more power and flexibility. All of the following values are optional, and can be passed in individually.
- Notes: Must be a properly formatted email address.
- Notes: No validation is performed on values passed in.
- Notes: Accepts 2-character ISO codes for the state or province of the country determined by the customer's IP address. Because pre-populating the country isn't supported, pre-populating the state/province field only works correctly if the value passed in is valid for the country automatically determined by FoxyCart.
- Notes: Pre-populating the country is not currently supported.