|
| 1 | +--- |
| 2 | +description: Learn how to configure the Umbraco Commerce Cart package. |
| 3 | +--- |
| 4 | + |
| 5 | +# Configuration |
| 6 | + |
| 7 | +The Cart package is configured using a JavaScript, CSS and data attributes based API. |
| 8 | + |
| 9 | +## Initialization |
| 10 | + |
| 11 | +Before adding items to a cart, it is required the the Cart package is first 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. |
| 12 | + |
| 13 | +```javascript |
| 14 | +<script src="/App_Plugins/UmbracoCommerceCart/umbraco-commerce-cart.js" defer></script> |
| 15 | +<script> |
| 16 | + window.addEventListener('DOMContentLoaded', function() { |
| 17 | + UCC.init({ |
| 18 | + store: 'blendid', |
| 19 | + checkoutUrl: '/checkout', |
| 20 | + showPricesIncludingTax: true |
| 21 | + }); |
| 22 | + }); |
| 23 | +</script> |
| 24 | +``` |
| 25 | + |
| 26 | +The core intialization settings are: |
| 27 | + |
| 28 | +| Key | Description | |
| 29 | +| -- | -- | |
| 30 | +| `store` | The ID or alias of the store the cart should be associated with. | |
| 31 | +| `checkoutUrl` | The URL of the checkout page the cart should redirect to on checkout. | |
| 32 | +| `showPricesIncludingTax` | Define whether to show prices inclusive of exclusive of sales TAX. Defaults to `false`. | |
| 33 | + |
| 34 | +Calling the `init` method will also automatically bind any UI elements configured using the following APIs. |
| 35 | + |
| 36 | +## UI Elements |
| 37 | + |
| 38 | +### Add to Cart Buttons |
| 39 | + |
| 40 | +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. |
| 41 | + |
| 42 | +The first step when defining a 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. |
| 43 | + |
| 44 | +```html |
| 45 | +<button class="ucc-add-to-cart" |
| 46 | + data-ucc-product-reference="828c0bfe-c0e7-4891-a36b-187b658357fc"> |
| 47 | + Add to cart |
| 48 | +</button> |
| 49 | +``` |
| 50 | + |
| 51 | +Along with the `ucc-add-to-cart` class we also use a series of data attributes to provide information about the product being added to the cart. At minimum a `data-ucc-product-reference` is required, but the following table outlines all the available configuration options. |
| 52 | + |
| 53 | +| Key | Description | |
| 54 | +| -- | -- | |
| 55 | +| `data-ucc-product-reference` | The unique reference for the product being added. This is usually the Key of the product Umbraco node. | |
| 56 | +| `data-ucc-product-variant-reference` | The unique reference for a variant of the primary product being added. This is usually either a child variant nodes Key or the Key of a complex variant item from the Variants property editor. |
| 57 | +| `data-ucc-quantity` | The amount of the given product to be added. | |
| 58 | +| `data-ucc-property1-key` | The key of a property to set on the added order line. | |
| 59 | +| `data-ucc-property1-value` | The value of a property to set on the added order line. | |
| 60 | +| `data-ucc-bundle-reference` | A unique reference to use to mark this item as a bundle. | |
| 61 | +| `data-ucc-bundle-item1-product-reference` | The unique reference of a product to add as a bundle item. | |
| 62 | +| `data-ucc-bundle-item1-product-variant-reference` | The unique reference of a product variant to add as a bundle item. | |
| 63 | +| `data-ucc-bundle-item1-quantity` | The amount of the given product to add as a bundle item. | |
| 64 | +| `data-ucc-bundle-item1-property1-key` | The key of a property to set on the added bundle item. | |
| 65 | +| `data-ucc-bundle-item1-property1-value` | The value of a property to set on the added bundle item. | |
| 66 | + |
| 67 | +Where an attribute ends with a number, this signifies that this 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. |
| 68 | + |
| 69 | +With an add to cart button defined, clicking on the button should now automatically add the given product to the cart and open the cart for display. |
| 70 | + |
| 71 | + |
| 72 | + |
| 73 | +### Open Cart Button |
| 74 | + |
| 75 | +Whilst the cart will open automatically when an item is added to the cart, it's also likely that you will want the ability for customers to open their carts manually. To do this you can add a `ucc-cart` class to a link or button element and Umbraco Commerce Cart will automatically bind a click event handler to trigger opening the cart. |
| 76 | + |
| 77 | +```html |
| 78 | +<a href="#" class="ucc-cart">Cart</a> |
| 79 | +``` |
| 80 | + |
| 81 | +### Cart Count Label |
| 82 | + |
| 83 | +Another common feature on commerce sites is the ability to display a total number of items in the current cart. To do this you can define a html element with a `ucc-cart-count` class applied and Umbraco Commerce Cart will automatically update it's text value whenever the cart changes. |
| 84 | + |
| 85 | +```html |
| 86 | +<a href="#" class="ucc-cart">Cart (<span class="ucc-cart-count">0</span>)</a> |
| 87 | +``` |
| 88 | + |
| 89 | +## Commands |
| 90 | + |
| 91 | +As well as the automatic API defined above, it is also possible to trigger Umbraco Commerce Cart commands manually via a number of JavaScript functions. |
| 92 | + |
| 93 | +```javascript |
| 94 | +// Open the cart |
| 95 | +UCC.openCart(); |
| 96 | + |
| 97 | +// Close the cart |
| 98 | +UCC.closeCart(); |
| 99 | + |
| 100 | +// Re-bind UI API elements |
| 101 | +UCC.bind(); |
| 102 | + |
| 103 | +// Update the store configuration |
| 104 | +UCC.setStore('brewed'); |
| 105 | + |
| 106 | +// Update the checkout URL |
| 107 | +UCC.setCheckoutUrl('/new-checkout'); |
| 108 | + |
| 109 | +// Set whether to display prices inclusive of exclusive of sales TAX |
| 110 | +UCC.showPricesIncludingTax(true); |
| 111 | + |
| 112 | +// Show a property in the cart |
| 113 | +UCC.showProperty('myProp'); |
| 114 | + |
| 115 | +// Change the language of the cart UI |
| 116 | +UCC.setLang('dk'); |
| 117 | + |
| 118 | +// Add or replace a localization dictionary |
| 119 | +UCC.addLocale('en', { |
| 120 | + key: 'value', |
| 121 | + ... |
| 122 | +}); |
| 123 | + |
| 124 | +// Set the error handler |
| 125 | +UCC.setOnError(msg => { |
| 126 | + console.log(msg); |
| 127 | +}); |
| 128 | +``` |
| 129 | + |
| 130 | +## Localization |
| 131 | + |
| 132 | +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. |
| 133 | + |
| 134 | +Localization is controlled via the `lang` attribute in the `<html>` tag of your site. |
| 135 | + |
| 136 | +```html |
| 137 | +<!DOCTYPE html> |
| 138 | +<html lang="fr"> |
| 139 | + <head> |
| 140 | + <title></title> |
| 141 | + </head> |
| 142 | + <body></body> |
| 143 | +</html> |
| 144 | + |
| 145 | +``` |
| 146 | + |
| 147 | +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. |
| 148 | + |
| 149 | +Additional locales can be added either via the `UCC.init` method, or by calling the `UCC.addLocale` command. |
| 150 | + |
| 151 | +```javascript |
| 152 | +// Init command example |
| 153 | +UCC.init({ |
| 154 | + store: 'blendid', |
| 155 | + checkoutUrl: '/checkout', |
| 156 | + locales: { |
| 157 | + fr: { |
| 158 | + cart_title: 'Mon Panier', |
| 159 | + close_cart: 'Fermer le panier (ESC)', |
| 160 | + checkout: 'Vérifier', |
| 161 | + taxes: 'Impôts', |
| 162 | + subtotal: 'Total', |
| 163 | + total: 'Total', |
| 164 | + shipping_and_discounts_message: "Calculez les frais d'expédition et appliquez des remises lors du paiement", |
| 165 | + remove: 'Retirer', |
| 166 | + cart_empty: 'Votre panier est vide', |
| 167 | + } |
| 168 | + } |
| 169 | +}); |
| 170 | + |
| 171 | +// Add locale command example |
| 172 | +UCC.addLocale('fr', { |
| 173 | + cart_title: 'Mon Panier', |
| 174 | + close_cart: 'Fermer le panier (ESC)', |
| 175 | + checkout: 'Vérifier', |
| 176 | + taxes: 'Impôts', |
| 177 | + subtotal: 'Total', |
| 178 | + total: 'Total', |
| 179 | + shipping_and_discounts_message: "Calculez les frais d'expédition et appliquez des remises lors du paiement", |
| 180 | + remove: 'Retirer', |
| 181 | + cart_empty: 'Votre panier est vide', |
| 182 | +}) |
| 183 | +``` |
| 184 | + |
| 185 | +The default English locale has the following values, and also defines the required keys for a locale. |
| 186 | + |
| 187 | +```javascript |
| 188 | +{ |
| 189 | + cart_title: 'My Cart', |
| 190 | + close_cart: 'Close Cart (ESC)', |
| 191 | + checkout: 'Checkout', |
| 192 | + taxes: 'Taxes', |
| 193 | + subtotal: 'Subtotal', |
| 194 | + total: 'Total', |
| 195 | + shipping_and_discounts_message: 'Calculate shipping and apply discounts during checkout', |
| 196 | + remove: 'Remove', |
| 197 | + cart_empty: 'Your cart is empty', |
| 198 | +} |
| 199 | +``` |
| 200 | + |
| 201 | +To override a locale you can re-add it reusing the same language key |
| 202 | + |
| 203 | +```javascript |
| 204 | +// Init command example |
| 205 | +UCC.init({ |
| 206 | + store: 'blendid', |
| 207 | + checkoutUrl: '/checkout', |
| 208 | + locales: { |
| 209 | + en: { |
| 210 | + ...UCC.defaultLocales.en, // Clone the default locale |
| 211 | + remove: 'Remove item', // Update the `remove` key value |
| 212 | + } |
| 213 | + } |
| 214 | +}); |
| 215 | + |
| 216 | +// Add Locale command example |
| 217 | +UCC.addLocale('en', { |
| 218 | + ...UCC.defaultLocales.en, // Clone the default locale |
| 219 | + remove: 'Remove item', // Update the `remove` key value |
| 220 | +}) |
| 221 | +``` |
| 222 | + |
| 223 | +## Displaying Properties |
| 224 | + |
| 225 | +If you capture any custom properties, you may wish to display them within the cart. Displaying properties is achieved in two steps. |
| 226 | + |
| 227 | +We first define the property keys we wish to display either via the `UCC.init` command, or the `UCC.showProperty` command. |
| 228 | + |
| 229 | +```javascript |
| 230 | +// Init command example |
| 231 | +UCC.init({ |
| 232 | + store: 'blendid', |
| 233 | + checkoutUrl: '/checkout', |
| 234 | + properties: [ 'message' ] |
| 235 | +}); |
| 236 | + |
| 237 | +// Show property command example |
| 238 | +UCC.showProperty('message'); |
| 239 | +``` |
| 240 | + |
| 241 | +Next we define a localization key to use as a label for each property. |
| 242 | + |
| 243 | +```javascript |
| 244 | +// Init command example |
| 245 | +UCC.init({ |
| 246 | + store: 'blendid', |
| 247 | + checkoutUrl: '/checkout', |
| 248 | + properties: [ 'message' ], |
| 249 | + locales: { |
| 250 | + en: { |
| 251 | + ...UCC.defaultLocales.en, // Clone the default locale |
| 252 | + property_message: 'Message', // Provide a key translation prefixed with `property_` |
| 253 | + } |
| 254 | + } |
| 255 | +}); |
| 256 | + |
| 257 | +// Show property + add locale command example |
| 258 | +UCC.showProperty('message'); |
| 259 | +UCC.addLocale('en', { |
| 260 | + ...UCC.defaultLocales.en, // Clone the default locale |
| 261 | + property_message: 'Message', // Provide a key translation prefixed with `property_` |
| 262 | +}) |
| 263 | +``` |
| 264 | + |
| 265 | +Now when the cart is displayed, the defined properties will be displayed using the localization value as their label. |
| 266 | + |
| 267 | + |
| 268 | + |
| 269 | +## Theming |
| 270 | + |
| 271 | +In order to allow customization of the cart UI, CSS variables are used to allow easy overiding of the default styles. |
| 272 | + |
| 273 | +The following details the default values, and the available keys to override. |
| 274 | + |
| 275 | +```css |
| 276 | +:root { |
| 277 | + |
| 278 | + /* Colors */ |
| 279 | + --ucc-primary-color: #155dfc; |
| 280 | + --ucc-primary-color-light: #51a2ff; |
| 281 | + --ucc-primary-color-dark: #193cb8; |
| 282 | + --ucc-danger-text-color: #9f0712; |
| 283 | + --ucc-danger-background-color: #ffc9c9; |
| 284 | + |
| 285 | + /* Font */ |
| 286 | + --ucc-font-family: ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji', sans-serif; |
| 287 | + |
| 288 | + /* Text */ |
| 289 | + --ucc-text-color: #364153; |
| 290 | + --ucc-text-color-light: #99a1af; |
| 291 | + --ucc-text-color-lighter: #c1c7d0; |
| 292 | + --ucc-text-color-dark: #101828; |
| 293 | + --ucc-text-lg: 20px; |
| 294 | + --ucc-text-md: 16px; |
| 295 | + --ucc-text-sm: 14px; |
| 296 | + |
| 297 | + /* Borders */ |
| 298 | + --ucc-border-color: #ddd; |
| 299 | + --ucc-border-radius: 5px; |
| 300 | + |
| 301 | + /* Components */ |
| 302 | + --ucc-button-background-color: var(--ucc-primary-color); |
| 303 | + --ucc-button-text-color: #fff; |
| 304 | + --ucc-button-background-color-hover: var(--ucc-primary-color-dark); |
| 305 | + --ucc-button-text-color-hover: #fff; |
| 306 | + --ucc-button-background-color-disabled: #d1d5dc; |
| 307 | + --ucc-button-text-color-disabled: #fff; |
| 308 | + --ucc-modal-width: 550px; |
| 309 | + --ucc-modal-background-color: #fff; |
| 310 | + --ucc-modal-overlay-color: rgba(0, 0, 0, 0.5); |
| 311 | +} |
| 312 | +``` |
| 313 | + |
| 314 | +Styles can be overridden by including a stylesheet after the Umbraco Commerce Cart stylesheet, replacing the desired keys. |
| 315 | + |
| 316 | +```html |
| 317 | +<link href="/App_Plugins/UmbracoCommerceCart/umbraco-commerce-cart.css" rel="stylesheet"> |
| 318 | +<style> |
| 319 | + :root { |
| 320 | + --ucc-button-background-color: #4FD1C5; |
| 321 | + --ucc-button-background-color-hover: #38B2AC; |
| 322 | + } |
| 323 | +</style> |
| 324 | +``` |
| 325 | + |
| 326 | +## Error Handling |
| 327 | + |
| 328 | +By default Umbraco Commerce Cart will just log any request errors to the console. If you would like to display errors to your users, or handle them differently you can do so by providing an error handler function. |
| 329 | + |
| 330 | +```javascript |
| 331 | +// Init command example |
| 332 | +UCC.init({ |
| 333 | + store: 'blendid', |
| 334 | + checkoutUrl: '/checkout', |
| 335 | + onError: (msg) => console.log(msg) |
| 336 | +}); |
| 337 | + |
| 338 | +// Set on error command example |
| 339 | +UCC.setOnError(msg => console.log(msg)); |
| 340 | +``` |
0 commit comments