@eastsideco/escshopify
Version:
WIP JS library for Shopify, containing a variety of useful functionality.
281 lines (252 loc) • 16.6 kB
HTML
<html>
<head>
<meta charset="utf-8">
<base data-ice="baseUrl" href="../">
<title data-ice="title">Manual | @eastsideco/escshopify</title>
<link type="text/css" rel="stylesheet" href="css/style.css">
<link type="text/css" rel="stylesheet" href="css/prettify-tomorrow.css">
<script src="script/prettify/prettify.js"></script>
<script src="script/manual.js"></script>
</head>
<body class="layout-container manual-root" data-ice="rootContainer">
<header>
<a href="./">Home</a>
<a href="./manual/index.html" data-ice="manualHeaderLink">Manual</a>
<a href="identifiers.html">Reference</a>
<a href="source.html">Source</a>
<div class="search-box">
<span>
<img src="./image/search.png">
<span class="search-input-edge"></span><input class="search-input"><span class="search-input-edge"></span>
</span>
<ul class="search-result"></ul>
</div>
<a href="https://bitbucket.org/sigapps/escshopify.git">Repository</a></header>
<nav class="navigation" data-ice="nav"><div class="manual-toc-root">
<div data-ice="manual">
<ul class="manual-toc">
<li data-ice="manualNav" class="indent-h1" data-link="manual/overview.html"><a href="manual/overview.html" data-ice="link">Overview</a></li>
</ul>
</div>
<div data-ice="manual">
<ul class="manual-toc">
<li data-ice="manualNav" class="indent-h1" data-link="manual/entities.html"><a href="manual/entities.html" data-ice="link">Entities</a></li>
</ul>
</div>
<div data-ice="manual">
<ul class="manual-toc">
<li data-ice="manualNav" class="indent-h1" data-link="manual/cart.html"><a href="manual/cart.html" data-ice="link">Entities/Cart</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/cart.html"><a href="manual/cart.html#example" data-ice="link">Example</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/cart.html"><a href="manual/cart.html#getting-started" data-ice="link">Getting Started</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/cart.html"><a href="manual/cart.html#initializing-the-cart-state" data-ice="link">Initializing the cart state</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/cart.html"><a href="manual/cart.html#reading-the-cart" data-ice="link">Reading the cart</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/cart.html"><a href="manual/cart.html#setting-cart-items-and-attributes" data-ice="link">Setting cart items and attributes</a></li>
<li data-ice="manualNav" class="indent-h4" data-link="manual/cart.html"><a href="manual/cart.html#important-warning-about-async" data-ice="link">Important warning about async</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/cart.html"><a href="manual/cart.html#events" data-ice="link">Events</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/cart.html"><a href="manual/cart.html#update" data-ice="link">update</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/cart.html"><a href="manual/cart.html#add" data-ice="link">add</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/cart.html"><a href="manual/cart.html#item-updated" data-ice="link">item-updated</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/cart.html"><a href="manual/cart.html#remove" data-ice="link">remove</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/cart.html"><a href="manual/cart.html#clear" data-ice="link">clear</a></li>
</ul>
</div>
<div data-ice="manual">
<ul class="manual-toc">
<li data-ice="manualNav" class="indent-h1" data-link="manual/shop.html"><a href="manual/shop.html" data-ice="link">Entities/Shop</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/shop.html"><a href="manual/shop.html#examples" data-ice="link">Examples</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/shop.html"><a href="manual/shop.html#getting-started" data-ice="link">Getting Started</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/shop.html"><a href="manual/shop.html#initializing-the-shop-state" data-ice="link">Initializing the shop state</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/shop.html"><a href="manual/shop.html#events" data-ice="link">Events</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/shop.html"><a href="manual/shop.html#init" data-ice="link">init</a></li>
</ul>
</div>
<div data-ice="manual">
<ul class="manual-toc">
<li data-ice="manualNav" class="indent-h1" data-link="manual/plugins.html"><a href="manual/plugins.html" data-ice="link">Plugins</a></li>
</ul>
</div>
<div data-ice="manual">
<ul class="manual-toc">
<li data-ice="manualNav" class="indent-h1" data-link="manual/easycurrency.html"><a href="manual/easycurrency.html" data-ice="link">Plugins/EasyCurrency</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/easycurrency.html"><a href="manual/easycurrency.html#getting-started" data-ice="link">Getting started</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/easycurrency.html"><a href="manual/easycurrency.html#simple-example" data-ice="link">Simple example</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/easycurrency.html"><a href="manual/easycurrency.html#config-options" data-ice="link">Config options</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/easycurrency.html"><a href="manual/easycurrency.html#events" data-ice="link">Events</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/easycurrency.html"><a href="manual/easycurrency.html#extending-easycurrency" data-ice="link">Extending EasyCurrency</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/easycurrency.html"><a href="manual/easycurrency.html#formatters" data-ice="link">Formatters</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/easycurrency.html"><a href="manual/easycurrency.html#currency-resolvers" data-ice="link">Currency Resolvers</a></li>
</ul>
</div>
<div data-ice="manual">
<ul class="manual-toc">
<li data-ice="manualNav" class="indent-h1" data-link="manual/geoservice.html"><a href="manual/geoservice.html" data-ice="link">Plugins/Geoservice</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/geoservice.html"><a href="manual/geoservice.html#getting-started" data-ice="link">Getting started</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/geoservice.html"><a href="manual/geoservice.html#get-visitor-geolocation-info" data-ice="link">Get visitor geolocation info</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/geoservice.html"><a href="manual/geoservice.html#get-currency-exchange-rates" data-ice="link">Get currency exchange rates</a></li>
</ul>
</div>
<div data-ice="manual">
<ul class="manual-toc">
<li data-ice="manualNav" class="indent-h1" data-link="manual/utils.html"><a href="manual/utils.html" data-ice="link">Utilities</a></li>
</ul>
</div>
<div data-ice="manual">
<ul class="manual-toc">
</ul>
</div>
<div data-ice="manual">
<ul class="manual-toc">
<li data-ice="manualNav" class="indent-h1" data-link="manual/log.html"><a href="manual/log.html" data-ice="link">Utilities/Log</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/log.html"><a href="manual/log.html#using-salvo" data-ice="link">Using SALVO</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/log.html"><a href="manual/log.html#log-levels-and-tags" data-ice="link">Log levels and tags</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/log.html"><a href="manual/log.html#getting-started" data-ice="link">Getting started</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/log.html"><a href="manual/log.html#create-a-logging-module" data-ice="link">Create a logging module</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/log.html"><a href="manual/log.html#setting-a-log-level" data-ice="link">Setting a log level</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/log.html"><a href="manual/log.html#writing-new-loggers" data-ice="link">Writing new loggers</a></li>
</ul>
</div>
</div>
</nav>
<div class="content" data-ice="content"><div class="github-markdown" data-ice="content"><h1 id="entities-cart">Entities/Cart</h1><p>The Cart module provides an interface to the state of the visitor's cart and the cart AJAX API.</p>
<p>For member and method documentation, see the API reference. For event documentation and examples, see below.</p>
<h2 id="example">Example</h2><p>The following example shows a simple JS component which keeps track of the number of items in the visitor's cart.</p>
<p><strong>ES6</strong>:</p>
<pre><code class="lang-js"><code class="source-code prettyprint">import {entities, utils} from '@eastsideco/escshopify';
const cart = new entities.Cart;
export default class CartCounter {
constructor(element) {
this._element = element;
cart.on('update', () => this.render());
utils.onLoad(() => this.render());
}
async render() {
await cart.ready();
var count = cart.items.reduce((total, i) => total + i.quantity, 0);
this._element.innerText = count;
}
}</code>
</code></pre>
<h2 id="getting-started">Getting Started</h2><h3 id="initializing-the-cart-state">Initializing the cart state</h3><p>Before using the cart module, you should initialize it with the current state of the cart, for example from a binding created in Liquid.</p>
<p><em>This is done for you automatically if you use SALVO.</em></p>
<p><strong>ES6</strong>:</p>
<pre><code class="lang-js"><code class="source-code prettyprint">import {entities, utils} from '@eastsideco/escshopify';
const cart = new entities.Cart;
cartData = { token: '...', items: [ ... ], ... };
cart.initialize(cartData);</code>
</code></pre>
<h3 id="reading-the-cart">Reading the cart</h3><p>You can access the items in the cart using <code>.items</code>. It's highly recommended to check or wait for the cart entity to be 'ready' before doing this. Async/await makes this quite trivial.</p>
<p><strong>ES6</strong>:</p>
<pre><code class="lang-js"><code class="source-code prettyprint">import {entities, utils} from '@eastsideco/escshopify';
const cart = new entities.Cart;
// Using async/await
async function printCartItemNames() {
await cart.ready();
for (let cart.items as item) {
console.log(item.title + ' x' + item.quantity);
}
}
// Using promises
function printCartItemNames() {
cart.ready().then(() => {
for (let cart.items as item) {
console.log(item.title + ' x' + item.quantity);
}
});
}
// Checking cart state syncronously
function printCartItemNames() {
if (cart.isReady) {
for (let cart.items as item) {
console.log(item.title + ' x' + item.quantity);
}
}
}</code>
</code></pre>
<h3 id="setting-cart-items-and-attributes">Setting cart items and attributes</h3><p>You can modify the cart items using <code>#addItem</code>, <code>#updateItem</code>, etc.
You can modify cart attributes using <code>#setAttribute</code> or <code>#setAttributes</code>.</p>
<p><strong>ES6</strong>:</p>
<pre><code class="lang-js"><code class="source-code prettyprint">cart.addItem(variantId, 1);</code>
</code></pre>
<pre><code class="lang-js"><code class="source-code prettyprint">await cart.addItem(variantId, 1);
cart.updateItemById(variantId, 3);</code>
</code></pre>
<pre><code class="lang-js"><code class="source-code prettyprint">// Setting a line item attribute on each item in the cart:
for (let item, lineNumber of cart.items) {
cart.updateItem(lineNumber, item.quantity, {
promotion: 'Added by promotion'
});
}</code>
</code></pre>
<h4 id="important-warning-about-async">Important warning about async</h4><p><strong>Warning:</strong> Most setter methods are asynchronous. Await the promise fulfillment, or be aware that the cart state may not reflect your changes.</p>
<p>Examples:</p>
<p><strong>ES6</strong>:</p>
<pre><code class="lang-js"><code class="source-code prettyprint">// starting cart attributes: { test: 1 }
cart.setAttribute('test', 2);
console.log(cart.getAttribute('test')); // may still 1?</code>
</code></pre>
<pre><code class="lang-js"><code class="source-code prettyprint">// starting cart attributes: { test: 1 }
await cart.setAttribute('test', 2);
console.log(cart.getAttribute('test')); // definitely 2</code>
</code></pre>
<pre><code class="lang-js"><code class="source-code prettyprint">// starting cart attributes: { test: 1 }
cart.setAttribute('test', 2).then(() => {
console.log(cart.getAttribute('test'); // definitely 2
});</code>
</code></pre>
<p>You can use <code>Promise#all</code> to wait for multiple changes to complete:</p>
<pre><code class="lang-js"><code class="source-code prettyprint">// Set attributes on all line items and wait until complete
var promises = [];
for (let item, lineNumber of cart.items) {
promises.push(cart.updateItem(lineNumber, item.quantity, { attribute: 'test' }));
}
console.log(cart.items); // Attributes may or may not be updated?
await Promise.all(promises);
console.log(cart.items); // Attributes are definitely updated</code>
</code></pre>
<h2 id="events">Events</h2><p>Listen to the following events to track the lifecycle of this entity.</p>
<h3 id="update">update</h3><p>The cart was modified.</p>
<pre><code class="lang-txt"><code class="source-code prettyprint">Object[] items - The new state of items in the cart.
String operation - 'add', 'item-updated', 'remove', 'init', or 'attribute-updated'
Object|Null item - Item that was added/updated/removed.</code>
</code></pre>
<p>Updating an item to 0 qty is considered a <code>remove</code>.</p>
<pre><code class="lang-js"><code class="source-code prettyprint">cart.on('update', (e) => {
this.cartTotalMinusGiftcards = _.reduce(e.items, (total, item) => {
return item.gift_card ? total : total + item.line_price;
}, 0);
});</code>
</code></pre>
<h3 id="add">add</h3><p>An item has been added.</p>
<pre><code><code class="source-code prettyprint">Object[] items - The new state of items in the cart.
Object item - Item that was added.</code>
</code></pre><p>Updating an existing item with higher qty <em>does not</em> fire this event (see <code>item-updated</code>).</p>
<pre><code class="lang-js"><code class="source-code prettyprint">cart.on('add', (e) => {
// "Thanks for adding Example Product!"
window.alert('Thanks for adding ' + e.item.product_title + '!');
});</code>
</code></pre>
<h3 id="item-updated">item-updated</h3><p>An item has been modified.</p>
<pre><code><code class="source-code prettyprint">Object[] items - The new state of items in the cart.
Object item - Item that was updated (after update).</code>
</code></pre><p>Adding a new line item <em>does not</em> fire this event (see <code>add</code>).</p>
<h3 id="remove">remove</h3><p>An item has been removed.</p>
<pre><code><code class="source-code prettyprint">Object[] items - The new state of items in the cart.
Object item - Item that was removed.</code>
</code></pre><h3 id="clear">clear</h3><p>The cart is now empty.</p>
<pre><code><code class="source-code prettyprint">Object[] oldItems - Items that were previously in the cart.</code>
</code></pre><p>This will typically fire when the last item is removed from the cart.</p>
</div>
</div>
<footer class="footer">
Generated by <a href="https://esdoc.org">ESDoc<span data-ice="esdocVersion">(1.0.4)</span><img src="./image/esdoc-logo-mini-black.png"></a>
</footer>
<script src="script/search_index.js"></script>
<script src="script/search.js"></script>
<script src="script/pretty-print.js"></script>
<script src="script/inherited-summary.js"></script>
<script src="script/test-summary.js"></script>
<script src="script/inner-link.js"></script>
<script src="script/patch-for-local.js"></script>
</body>
</html>