Learn how to configure the Umbraco Commerce Cart package.
The Cart package is configured using a JavaScript, CSS, and data attributes-based API.
Before adding items to a cart, it is required that the Cart package is initialized with some default settings. This is done using the UCC.init global function which should be executed after the umbraco-commerce-cart.js file is loaded.
The core initialization settings are shown in the table below.
store
The ID or alias of the store the cart should be associated with.
checkoutUrl
The URL of the checkout page the cart should redirect to on checkout.
showPricesIncludingTax
Define whether to show prices inclusive or exclusive of sales tax. Defaults to false.
Calling the init method will also automatically bind any UI elements configured using the following APIs.
With Umbraco Commerce Cart, products that can be added to a cart are defined by adding attributes to HTML elements on your site. Most likely this will be a "buy" <button> element, however, any HTML element can become an add-to-cart component.
The first step when defining an add-to-cart component is to add the ucc-add-to-cart class to the element. This informs Umbraco Commerce Cart that it should react to that element's click event.
Along with the ucc-add-to-cart class, a series of data attributes provides information about the product being added to the cart. At a minimum, a data-ucc-product-reference is required, but the following table outlines all the available configuration options.
data-ucc-product-reference
The unique reference for the product being added. This is usually the Key of the product Umbraco node.
data-ucc-product-variant-reference
The unique reference for a variant of the primary product being added. This is usually either a child variant node Key or the Key of a complex variant item from the Variants property editor.
data-ucc-quantity
The amount of the given product to be added.
data-ucc-property1-key
The key of a property to set on the added order line.
data-ucc-property1-value
The value of a property to set on the added order line.
data-ucc-bundle-reference
A unique reference to use to mark this item as a bundle.
data-ucc-bundle-item1-product-reference
The unique reference of a product to add as a bundle item.
data-ucc-bundle-item1-product-variant-reference
The unique reference of a product variant to add as a bundle item.
data-ucc-bundle-item1-quantity
The amount of the given product to add as a bundle item.
data-ucc-bundle-item1-property1-key
The key of a property to set on the added bundle item.
data-ucc-bundle-item1-property1-value
The value of a property to set on the added bundle item.
Some attributes end with a number. This signifies that the attribute defines a collection and so multiple attributes can be defined with each distinct combination incrementing the number by 1. It is important that these attributes start from 1 and must be sequential without gaps.
With an add-to-cart button defined, clicking on the button will automatically add the product and open the cart for display.
While the cart will open automatically when an item is added, you can also enable the customers to open their carts manually. To do this, add a ucc-cart class to a link or button element. The Umbraco Commerce Cart will then automatically bind a click event handler to trigger opening the cart.
Another common feature on commerce sites is the ability to display the total number of items in the current cart. To do this, define an HTML element with a ucc-cart-count class applied. Umbraco Commerce Cart will then automatically update its text value whenever the cart changes.
As well as the automatic API defined above, it is possible to trigger Umbraco Commerce Cart commands manually via a number of JavaScript functions.
The cart UI supports being translated into any language. Out of the box, it comes with a default English translation, but additional locales can be configured.
Localization is controlled via the lang attribute in the <html> tag of your site.
In the above example, Umbraco Commerce Cart will look for a French locale. If a given locale can't be found, then it will default back to English.
Additional locales can be added either via the UCC.init method or by calling the UCC.addLocale command.
The default English locale has the following values and defines the required keys for a locale.
To override a locale you can re-add it by reusing the same language key.
If you capture any custom properties, you may want to display them within the cart. Displaying properties is achieved in two steps.
First, you define the property keys you wish to display either via the UCC.init command, or the UCC.showProperty command.
Next, you define a localization key to use as a label for each property.
Now, when the cart is displayed, the defined properties will be displayed using the localization value as their label.
To allow customization of the cart UI, CSS variables are used to allow overriding of the default styles.
The following details the default values, and the available keys to override.
Styles can be overridden by including a stylesheet after the Umbraco Commerce Cart stylesheet, replacing the desired keys.
By default, Umbraco Commerce Cart will log any request errors to the console. If you would like to display errors to your users or handle them differently you can provide an error handler function.
