Vendr Cart API Proposal

[mattbrailsford]

Vendr Cart API Proposal

Install / Global Config

Vendr Cart is initialized via a global JS script

<script>
  window.VendrCartSettings = {
    storeId: 1234,
    loadCss: false,
    addProductBehavior: "none", // "show-cart"
  };
</script>
<script src="/App_Plugins/VendrCart/vendrcart.api.js" defer></script>

Options

Option	Description
storeId	[Required] Sets the global ID of the Store this cart is associated with.
loadCss	Defines whether to load the default CSS styles or not
addProductBehavior	Defines what should happen when a product is added. none = nothing happens, show-cart (default) = open the shopping cart modal

Components

All components are delared by custom data attributes. There is a primary data attribute that will signal that a DOM element is a specific component and there will be addition data attributes to provide configuration to the given attribute.

NB We could have used CSS classes instead of the primary attribute, but I think using data attributes makes it clearer this is dynamic behaviour.

data-vendr-variants

The variants component displays a series of select list drop downs for the given products variants. If the product has multi variants, then the select lists will be connected to dynamically work out the given variants product reference which can be accessed by various other components. In order for other components to access the vairants value, the component must be given an ID

Snippet:

<div id="variants" data-vendr-variants   
  data-vendr-product-reference="1234"
  data-vendr-variants-mode="children">
</div>

Options:

Option	Description
data-vendr-product-reference	The primary product reference
data-vendr-variants-mode	The mode for accessing variants. children = child node variants, editor = multi-variants editor

---

data-vendr-price

The price component displays the formatted price of the given product / variant. If the variant option is a ref (#) then the value should automatically update as the variants component selection changes.

TODO Need either a config option, or another component to use on product list pages to show either price ranges, or a From $2.00

Snippet:

<span data-vendr-price  
  data-vendr-product-reference="1234"
  data-vendr-product-variant-reference="#variants"></span>

Options:

Option	Description
data-vendr-product-reference	The primary product reference
data-vendr-product-variant-reference	Id or ref (#) to a product variant reference

---

data-vendr-stock

The stock component displays the remaining stock of the given product / variant. If the variant option is a ref (#) then the value should automatically update as the variants component selection changes.

Snippet:

<span data-vendr-stock   
  data-vendr-product-reference="1234"
  data-vendr-product-variant-reference="#variants">
</span>

Options:

Option	Description
data-vendr-product-reference	The primary product reference
data-vendr-product-variant-reference	Id or ref (#) to a product variant reference

---

data-vendr-quantity

The quantity component attaches to a numeric input element to limit it's value to the remaining stock value of the given product / variant. If the variant option is a ref (#) then the limit should automatically update as the variants component selection changes.

Snippet:

<input id="quantity" type="numeric" data-vendr-quantity
  data-vendr-product-reference="1234"
  data-vendr-product-variant-reference="#variants" />

Options:

Option	Description
data-vendr-product-reference	The primary product reference
data-vendr-product-variant-reference	Id or ref (#) to a product variant reference

---

data-vendr-add-to-cart

The add to cart component attaches to an button to perform adding a product to the cart. The add to cart button pulls all other component together, such as variants and quantity, where these value can either be fixed or a ref (#) to another component to read it's value dynamically.

The add to cart component also has an API for adding properties to an order line / order. These attributes could either be a hard coded value, or a ref (#) to another input field. The name of the property should either be taken from the data attribute itself (the part after data-vendr-property-) or from any value: prefix in the attributes value.

TODO Need some way of being able to add bundles to an order

Snippet:

<button data-vendr-add-to-cart
  data-vendr-product-reference="1234"
  data-vendr-product-variant-reference="#variants" 
  data-vendr-quantity="#quantity"
  data-vendr-property-width="frameWidth:#frame-width"
  data-vendr-property-height="frameHeight:#frame-height"  
  data-vendr-order-property-test="frameHeight:#frame-height">
  Add to Cart
</button>

Options:

Option	Description
data-vendr-product-reference	The primary product reference
data-vendr-product-variant-reference	Id or ref (#) to a product variant reference
data-vendr-quantity	Value or ref (#) to a quantity value for this item
data-vendr-property-{key}	Value or ref (#) to a property value to add to the order line
data-vendr-order-property-{key}	Value or ref (#) to a property value to add to the order

---

data-vendr-item-count

The item count component shows the total number of items in the cart.

Snippet:

<span data-vendr-item-count></span>

---

data-vendr-total-price

The total price component shows the total price of all items in the cart.

Snippet:

<span data-vendr-total-price></span>

---

data-vendr-cart

The cart component attached to a button or link element to trigger opening the cart modal.

Snippet:

<button data-vendr-cart>View cart</button>

Macros

The API above offers a simple way to integrate a cart for those that know a little HTML, but there is still potentially those with less knowledge and so it's whether a series of macro wrappers around these component could help for easier input into templates using the back office template editor?

I think in these scenarios it's going to have to render more DOM elements so it'll have to be a bit opinionated.

I think we'll need a macro to inject the scripts and maybe this one also injects an extra CSS file for these extra DOM elements so they look "good" no matter what they are dropped in. These could follow a similar approach to Vendr.Checkout having configurable colour scheme etc.

We could then have macros for most if not all of the components above.