Plugins/EasyCurrency

The EasyCurrency module provides easy-to-use and highly customizable frontend currency conversion.

Getting started

Simple example

By default, EC will convert elements with [data-money], optionally making use of the [data-money-currency] property.

For example, this element:
<span data-money="1234" data-money-currency="USD">$12.34</span>
May be converted to:
<span>£10.00</span>
Note that amounts are specified in integer units (i.e. cents).

Note that the default parser removes the initialization properties from the element after initialization, but this may not always be the case.
Warning: 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.

ES6:

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'
    });
});

ES5:

<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>

Config options

Here is an example with all of the config options and default values:
See the reference for Config#constructor for more info.

ES6:

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);
        },
    });
});

Events

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. ES6:

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);
    });
});

Extending EasyCurrency

Formatters

EasyCurrency uses a Formatter to format currencies.

To override currency formatting, make an object extending Formatter (or with #format), and then call EasyCurrency#setFormatter.

ES6:

// 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',
    });
});

Currency Resolvers

EasyCurrency uses a CurrencyResolver to determine which currencies are available and the conversion rate between them.

To override convertion rates or available currencies, make an object extending CurrencyResolver (or with #getConversionRate and #listCurrencyCodes), and call EasyCurrency#setCurrencyResolver.

ES6:

// 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',
    });
});