diff --git a/commerce-add-ons/packages/README.md b/commerce-add-ons/packages/README.md index eb69dc2f1f2..2480639d57c 100644 --- a/commerce-add-ons/packages/README.md +++ b/commerce-add-ons/packages/README.md @@ -6,8 +6,7 @@ description: Find detailed documentation for each of the official packages avail Below is an overview of the different add-ons that you can install into your Umbraco Commerce implementation. All add-ons are meant to extend the features and functionality already available in the core product. - - +
CheckoutUse this package to add additional functionality to the checkout flow for your Umbraco Commerce implementation.checkout
DeployThis package is used to enable the use of Umbraco Deploy with your Umbraco Commerce implementation.deploy
Product feedsThis plugin is a XML feed generator plugin which extracts product data from Umbraco node and generate structured XML feed.Product Feeds
CartUse this package to add a drop in cart solution to your Umbraco Commerce implementation.cart
CheckoutUse this package to add additional functionality to the checkout flow for your Umbraco Commerce implementation.checkout
DeployThis package is used to enable the use of Umbraco Deploy with your Umbraco Commerce implementation.deploy
Product feedsThis plugin is a XML feed generator plugin which extracts product data from Umbraco node and generate structured XML feed.Product Feeds
## Using These Docs diff --git a/commerce-add-ons/packages/SUMMARY.md b/commerce-add-ons/packages/SUMMARY.md index bd1d72ba3a3..006af55ddac 100644 --- a/commerce-add-ons/packages/SUMMARY.md +++ b/commerce-add-ons/packages/SUMMARY.md @@ -8,6 +8,13 @@ * [Commerce Payment Providers](https://docs.umbraco.com/umbraco-commerce-payment-providers) * [Commerce Shipping Providers](https://docs.umbraco.com/umbraco-commerce-shipping-providers) +## Cart + +* [Overview](cart/README.md) +* [Installation](cart/installation.md) +* [Configuration](cart/configuration.md) +* [Release Notes](cart/release-notes.md) + ## Checkout * [Overview](checkout/README.md) diff --git a/commerce-add-ons/packages/cart/README.md b/commerce-add-ons/packages/cart/README.md new file mode 100644 index 00000000000..178f1b3494d --- /dev/null +++ b/commerce-add-ons/packages/cart/README.md @@ -0,0 +1,22 @@ +--- +description: This is the documentation for the Cart package for Umbraco Commerce. +--- + +# Overview + +Umbraco Commerce Cart is a free and open-source add-on package for Umbraco Commerce. It provides a low-code solution for creating an instant shopping cart in your Umbraco Commerce stores. + +Umbraco Commerce Cart allows you to set up your shopping cart with minimal development costs. + +![A look at the Umbraco Commerce Cart UI](../media/cart/cart.png) + +In this section, you will learn the key steps necessary to get started with the Cart package for Umbraco Commerce. + +It is assumed that you already have an Umbraco website configured, Umbraco Commerce installed and a store set up. If you are not at this stage yet, please read the [core Umbraco Commerce documentation](https://docs.umbraco.com/umbraco-commerce/) to learn how to get started. + +## Useful links + +As well as the content in these documents, here are a few useful links to learn more about the Umbraco Commerce Cart package. + +* [Umbraco Commerce Cart source code](https://github.com/umbraco/Umbraco.Commerce.Cart) +* [Umbraco Commerce Cart issue tracker](https://github.com/umbraco/Umbraco.Commerce.Cart/issues) diff --git a/commerce-add-ons/packages/cart/configuration.md b/commerce-add-ons/packages/cart/configuration.md new file mode 100644 index 00000000000..b10e1ac0f9d --- /dev/null +++ b/commerce-add-ons/packages/cart/configuration.md @@ -0,0 +1,340 @@ +--- +description: Learn how to configure the Umbraco Commerce Cart package. +--- + +# Configuration + +The Cart package is configured using a JavaScript, CSS, and data attributes-based API. + +## Initialization + +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. + +```javascript + + +``` + +The core initialization settings are shown in the table below. + +| Key | Description | +| -- | -- | +| `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. + +## UI Elements + +### Add to Cart Buttons + +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" ` +``` + +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. + +| Key | Description | +| -- | -- | +| `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. + +![Shopping cart modal.](../media/cart/cart.png) + +### Open Cart Button + +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. + +```html +Cart +``` + +### Cart Count Label + +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. + +```html +Cart (0) +``` + +## Commands + +As well as the automatic API defined above, it is possible to trigger Umbraco Commerce Cart commands manually via a number of JavaScript functions. + +```javascript +// Open the cart +UCC.openCart(); + +// Close the cart +UCC.closeCart(); + +// Re-bind UI API elements +UCC.bind(); + +// Update the store configuration +UCC.setStore('brewed'); + +// Update the checkout URL +UCC.setCheckoutUrl('/new-checkout'); + +// Set whether to display prices inclusive or exclusive of sales tax +UCC.showPricesIncludingTax(true); + +// Show a property in the cart +UCC.showProperty('myProp'); + +// Change the language of the cart UI +UCC.setLang('dk'); + +// Add or replace a localization dictionary +UCC.addLocale('en', { + key: 'value', + ... +}); + +// Set the error handler +UCC.setOnError(msg => { + console.log(msg); +}); +``` + +## Localization + +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 `` tag of your site. + +```html + + + + + + + + +``` + +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. + +```javascript +// Init command example +UCC.init({ + store: 'blendid', + checkoutUrl: '/checkout', + locales: { + fr: { + cart_title: 'Mon Panier', + close_cart: 'Fermer le panier (ESC)', + checkout: 'Vérifier', + taxes: 'Impôts', + subtotal: 'Total', + total: 'Total', + shipping_and_discounts_message: "Calculez les frais d'expédition et appliquez des remises lors du paiement", + remove: 'Retirer', + cart_empty: 'Votre panier est vide', + } + } +}); + +// Add locale command example +UCC.addLocale('fr', { + cart_title: 'Mon Panier', + close_cart: 'Fermer le panier (ESC)', + checkout: 'Vérifier', + taxes: 'Impôts', + subtotal: 'Total', + total: 'Total', + shipping_and_discounts_message: "Calculez les frais d'expédition et appliquez des remises lors du paiement", + remove: 'Retirer', + cart_empty: 'Votre panier est vide', +}) +``` + +The default English locale has the following values and defines the required keys for a locale. + +```javascript +{ + cart_title: 'My Cart', + close_cart: 'Close Cart (ESC)', + checkout: 'Checkout', + taxes: 'Taxes', + subtotal: 'Subtotal', + total: 'Total', + shipping_and_discounts_message: 'Calculate shipping and apply discounts during checkout', + remove: 'Remove', + cart_empty: 'Your cart is empty', +} +``` + +To override a locale you can re-add it by reusing the same language key. + +```javascript +// Init command example +UCC.init({ + store: 'blendid', + checkoutUrl: '/checkout', + locales: { + en: { + ...UCC.defaultLocales.en, // Clone the default locale + remove: 'Remove item', // Update the `remove` key value + } + } +}); + +// Add Locale command example +UCC.addLocale('en', { + ...UCC.defaultLocales.en, // Clone the default locale + remove: 'Remove item', // Update the `remove` key value +}) +``` + +## Displaying Properties + +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. + +```javascript +// Init command example +UCC.init({ + store: 'blendid', + checkoutUrl: '/checkout', + properties: [ 'message' ] +}); + +// Show property command example +UCC.showProperty('message'); +``` + +Next, you define a localization key to use as a label for each property. + +```javascript +// Init command example +UCC.init({ + store: 'blendid', + checkoutUrl: '/checkout', + properties: [ 'message' ], + locales: { + en: { + ...UCC.defaultLocales.en, // Clone the default locale + property_message: 'Message', // Provide a key translation prefixed with `property_` + } + } +}); + +// Show property + add locale command example +UCC.showProperty('message'); +UCC.addLocale('en', { + ...UCC.defaultLocales.en, // Clone the default locale + property_message: 'Message', // Provide a key translation prefixed with `property_` +}) +``` + +Now, when the cart is displayed, the defined properties will be displayed using the localization value as their label. + +![Example property](../media/cart/property.png) + +## Theming + +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. + +```css +:root { + + /* Colors */ + --ucc-primary-color: #155dfc; + --ucc-primary-color-light: #51a2ff; + --ucc-primary-color-dark: #193cb8; + --ucc-danger-text-color: #9f0712; + --ucc-danger-background-color: #ffc9c9; + + /* Font */ + --ucc-font-family: ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji', sans-serif; + + /* Text */ + --ucc-text-color: #364153; + --ucc-text-color-light: #99a1af; + --ucc-text-color-lighter: #c1c7d0; + --ucc-text-color-dark: #101828; + --ucc-text-lg: 20px; + --ucc-text-md: 16px; + --ucc-text-sm: 14px; + + /* Borders */ + --ucc-border-color: #ddd; + --ucc-border-radius: 5px; + + /* Components */ + --ucc-button-background-color: var(--ucc-primary-color); + --ucc-button-text-color: #fff; + --ucc-button-background-color-hover: var(--ucc-primary-color-dark); + --ucc-button-text-color-hover: #fff; + --ucc-button-background-color-disabled: #d1d5dc; + --ucc-button-text-color-disabled: #fff; + --ucc-modal-width: 550px; + --ucc-modal-background-color: #fff; + --ucc-modal-overlay-color: rgba(0, 0, 0, 0.5); +} +``` + +Styles can be overridden by including a stylesheet after the Umbraco Commerce Cart stylesheet, replacing the desired keys. + +```html + + +``` + +## Error Handling + +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. + +```javascript +// Init command example +UCC.init({ + store: 'blendid', + checkoutUrl: '/checkout', + onError: (msg) => console.log(msg) +}); + +// Set on error command example +UCC.setOnError(msg => console.log(msg)); +``` diff --git a/commerce-add-ons/packages/cart/installation.md b/commerce-add-ons/packages/cart/installation.md new file mode 100644 index 00000000000..76d8426e435 --- /dev/null +++ b/commerce-add-ons/packages/cart/installation.md @@ -0,0 +1,33 @@ +--- +description: >- + Detailed instructions on how to install and configure Cart into your + Umbraco Commerce implementation. +--- + +# Installation + +The Cart package can be installed directly into your project's code base using NuGet packages. + +## NuGet Package Installation + +To install the Umbraco Commerce Cart package via NuGet run the following command directly in the NuGet Manager Console window in Visual Studio: + +```bash +PM> Install-Package Umbraco.Commerce.Cart +``` + +## Client Assets Installation + +Once installed, add the following CSS to your layout templates `head` section: + +```html + +``` + +Add following JavaScript before the closing `body` tag: + +```html + +``` + +Once installed, head to the [Configuration](./configuration.md) section to configure the Cart for your solution. diff --git a/commerce-add-ons/packages/cart/release-notes.md b/commerce-add-ons/packages/cart/release-notes.md new file mode 100644 index 00000000000..0914d77e475 --- /dev/null +++ b/commerce-add-ons/packages/cart/release-notes.md @@ -0,0 +1,3 @@ +# Release Notes + +For details of any changes to the **Umbraco Commerce Cart** plugin, please refer to the [Releases section on GitHub](https://github.com/umbraco/Umbraco.Commerce.Cart/releases). \ No newline at end of file diff --git a/commerce-add-ons/packages/media/cart/cart.png b/commerce-add-ons/packages/media/cart/cart.png new file mode 100644 index 00000000000..19c202e29df Binary files /dev/null and b/commerce-add-ons/packages/media/cart/cart.png differ diff --git a/commerce-add-ons/packages/media/cart/property.png b/commerce-add-ons/packages/media/cart/property.png new file mode 100644 index 00000000000..7052a5366e8 Binary files /dev/null and b/commerce-add-ons/packages/media/cart/property.png differ