@eastsideco/escshopify
Version:
WIP JS library for Shopify, containing a variety of useful functionality.
300 lines (264 loc) • 16.2 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="plugins-easycurrency">Plugins/EasyCurrency</h1><p>The EasyCurrency module provides easy-to-use and highly customizable frontend
currency conversion.</p>
<h2 id="getting-started">Getting started</h2><h3 id="simple-example">Simple example</h3><p>By default, EC will convert elements with <code>[data-money]</code>, optionally making use
of the <code>[data-money-currency]</code> property.</p>
<p>For example, this element:<br><code><span data-money="1234" data-money-currency="USD">$12.34</span></code><br>May be converted to:<br><code><span>£10.00</span></code><br>Note that amounts are specified in integer units (i.e. cents).</p>
<p>Note that the default parser removes the initialization properties from the element
after initialization, but this may not always be the case.<br><strong>Warning:</strong> Don't use the initialization properties to read/write conversion
state after initialization (as you would have in the classic EC) - there are
now other mechanisms for supporting this.</p>
<p><strong>ES6</strong>:</p>
<pre><code class="lang-js"><code class="source-code prettyprint">import {plugins, utils} from '@eastsideco/escshopify';
const easyCurrency = new plugins.EasyCurrency;
// Initialize EC once the page has loaded.
utils.onLoad(() => {
easyCurrency.useGeoserviceResolver();
easyCurrency.initialize({
defaultCurrency: 'GBP'
});
});</code>
</code></pre>
<p><strong>ES5</strong>:</p>
<pre><code class="lang-html"><code class="source-code prettyprint"><script src="escshopify.web.js"></script>
<script>
(function() {
// Initialize EC once the page has loaded.
escshopify.utils.onLoad(function() {
var easyCurrency = new escshopify.plugins.EasyCurrency();
easyCurrency.useGeoserviceResolver();
easyCurrency.initialize({
defaultCurrency: 'GBP'
});
});
})();
</script></code>
</code></pre>
<h3 id="config-options">Config options</h3><p>Here is an example with all of the config options and default values:<br>See the reference for Config#constructor for more info.</p>
<p><strong>ES6</strong>:</p>
<pre><code class="lang-js"><code class="source-code prettyprint">import {plugins, utils} from '@eastsideco/escshopify';
const easyCurrency = new plugins.EasyCurrency;
// Initialize EC once the page has loaded.
utils.onLoad(() => {
easyCurrency.useGeoserviceResolver();
easyCurrency.initialize({
// Currency to use before geolocation is first resolved.
defaultCurrency: 'GBP',
// List of currencies the user can use, or the string 'any'.
allowedCurrencies: 'any', // ['USD', 'EUR'],
// Whether to set currency based on geolocation.
useGeoForCurrency: true,
// Selectors to parse as MoneySpans
moneySpanSelectors: [
'[data-money]'
],
// How to extract amount + currency from the selected elements
moneySpanParser: function(el, easyCurrency) {
var amount = el.dataset.money;
var currency = el.dataset.moneyCurrency || easyCurrency.getState().currency;
delete el.dataset.money;
delete el.dataset.moneyCurrency;
amount = Number(amount);
return new Money(amount, currency);
},
});
});</code>
</code></pre>
<h2 id="events">Events</h2><p>EasyCurrency extends evee and provides a variety of events for to listening to changes. See the 'Emit' sections of the class reference for a list of events.
<strong>ES6</strong>:</p>
<pre><code class="lang-js"><code class="source-code prettyprint">import {plugins, utils} from '@eastsideco/escshopify';
const easyCurrency = new plugins.EasyCurrency;
// Initialize EC once the page has loaded.
utils.onLoad(() => {
easyCurrency.useGeoserviceResolver();
easyCurrency.initialize({
defaultCurrency: 'GBP',
});
easyCurrency.on('currencyChanged', (e) => {
alert('Currency is now: ' + e.data);
});
});</code>
</code></pre>
<h2 id="extending-easycurrency">Extending EasyCurrency</h2><h3 id="formatters">Formatters</h3><p>EasyCurrency uses a
<a href="./manual/../class/src/plugins/easycurrency/formatters/Formatter.js~Formatter.html">Formatter</a>
to format currencies.</p>
<p>To override currency formatting, make an object extending Formatter (or with #format),
and then call EasyCurrency#setFormatter.</p>
<p><strong>ES6</strong>:</p>
<pre><code class="lang-js"><code class="source-code prettyprint">// CustomFormatter.js
import {plugins} from '@eastsideco/escshopify';
export default class CustomFormatter extends plugins.EasyCurrency.formatters.Formatter {
format(amount, currency) {
return (amount / 100).toFixed(2) + ' ' + currency; // i.e. "12.34 USD"
}
}
// main.js
import {plugins, utils} from '@eastsideco/escshopify';
import CustomFormatter from './CustomFormatter';
const easyCurrency = new plugins.EasyCurrency;
// Initialize EC once the page has loaded.
utils.onLoad(() => {
easyCurrency.useGeoserviceResolver();
easyCurrency.setFormatter(new CustomFormatter);
easyCurrency.initialize({
defaultCurrency: 'GBP',
});
});</code>
</code></pre>
<h3 id="currency-resolvers">Currency Resolvers</h3><p>EasyCurrency uses a
<a href="./manual/../class/src/plugins/easycurrency/resolvers/CurrencyResolver.js~CurrencyResolver.html">CurrencyResolver</a>
to determine which currencies are available and the conversion rate between them.</p>
<p>To override convertion rates or available currencies, make an object extending CurrencyResolver (or with #getConversionRate and #listCurrencyCodes), and call EasyCurrency#setCurrencyResolver.</p>
<p><strong>ES6</strong>:</p>
<pre><code class="lang-js"><code class="source-code prettyprint">// CustomResolver.js
import {plugins} from '@eastsideco/escshopify';
export default class CustomResolver extends plugins.EasyCurrency.resolvers.CurrencyResolver {
async listCurrencyCodes() {
return ['USD', 'GBP', 'EUR'];
}
async getConversionRate(from, to) {
// Just an example, please don't write rates like this.
var rates = {
USD: { USD: 1, GBP: 0.8, EUR: 0.9 },
GBP: { USD: 1/0.8, GBP: 1, EUR: (1/0.8)*0.9 },
EUR: { USD: 1/0.9, GBP (1/0.9)*0.8, EUR: 1}
};
return rates[from][to];
}
}
// main.js
import {plugins, utils} from '@eastsideco/escshopify';
import CustomResolver from './CustomResolver';
const easyCurrency = new plugins.EasyCurrency;
// Initialize EC once the page has loaded.
utils.onLoad(() => {
easyCurrency.useGeoserviceResolver();
easyCurrency.setCurrencyResolver(new CustomResolver);
easyCurrency.initialize({
defaultCurrency: 'GBP',
});
});</code>
</code></pre>
</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>