shopify-liquid-external

Extends shopify-liquid with a new tag external that renders content (including Liquid code) differently depending on environment settings.

Essentially: any text, Liquid code, or what have you found between {% external %} and {% endexternal %} will be rendered as if between {% raw %} and {% endraw %} if the environment is in production, otherwise it will be rendered normally.

The use case for this tag is when one uses Liquid as one would a preprocessor/templating language but also needs to use Liquid to interact with a third party application/API (e.g. Shopify) in the same source. The Liquid code meant for external third party compilation is easily confused with the Liquid code meant for immediate preprocessing, hence the creation of this tag.

With this tag, one can compile something like a Shopify theme into HTML files for purely local viewing/testing and into liquid files for remote testing and production use on Shopify's servers.

Also does children's parties.

Installation

To install just shopify-liquid-external and required dependencies without the optional dependencies:

npm install shopify-liquid-external --save

npm install shopify-liquid-external --save-dev

Usage and Examples

const Liquid = require('shopify-liquid');
const engine = Liquid();

// First: bind shopify-liquid-external 
const addExternalTagTo = require('shopify-liquid-external');

// Second: add the new `external` tag to the Liquid engine instance
addExternalTagTo(engine, process.env.NODE_ENV == 'production');
// addExternalTagTo(engine); // You can omit the second argument, in which case process.env.NODE_ENV == 'production' will be used as a default

// Third: go about your business!
engine.parseAndRender('{{ name }}{% external %}{{ name }}{% endexternal %}{{ name }}', { name: 'Ricky' }).then(html => console.log(html));

More succinctly:

const engine = require('shopify-liquid-external')(require('shopify-liquid')());

// Go about your business!
engine.parseAndRender('{{ name }}{% external %}{{ name }}{% endexternal %}{{ name }}', { name: 'Abe' }).then(html => console.log(html));

Documentation

See API.md

You can also build and view the holistic and very pretty docdash version of the documentation locally (requires jsdoc).

With jsdoc installed globally (using npm or otherwise):

jsdoc -c jsdoc.json

Or, if you're using gulp:

gulp make-docs

---

With jsdoc installed locally using npm:

./node_modules/.bin/jsdoc -c jsdoc.json

Tests

npm test

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code.

Release History

• 0.2.x Extended functionality; differentiated from the raw tag
• 0.1.x Initial release (all unit tests passed)