gulp-liquidate v0.1.5

gulp-liquidate

A gulp plugin to facilitate the use of shopify-liquid or any other liquid compiler via strategy pattern in gulp-managed projects.

To spend 60 seconds making your own super simple compiler strategy to wrap your liquid compiler of choice, see lib/CompileStrategy for the strategy interface and some examples. It's really quite straight forward.

Build the documentation (see below) for information on features bundled with the plugin's public interface.

Also does children's parties.

Installation

To install with all optional dependencies (i.e. shopify-liquid compiler):

npm install gulp-liquidate --save

npm install gulp-liquidate --save-dev

To install just gulp-liquidate and required dependencies without the optional dependencies:

npm install gulp-liquidate --no-optional --save

Usage and Examples

Basic out-of-the-box functionality if you want to get started using Liquid immediately:

const gulp = require('gulp');
const liquidate = require('gulp-liquidate');

gulp.src('./src/*.liquid')
    .pipe(liquidate({ 'localVarOne': true, 'localVarTwo': false }))
    .pipe(gulp.dest('./dist'));

Usage with a custom shopify-liquid engine using the included ShopifyLiquidCompileStrategy class:

const gulp = require('gulp');
const liquidate = require('gulp-liquidate');
const Liquid = require('shopify-liquid');
const ShopifyLiquidCompileStrategy = liquidate.CompileStrategy.ShopifyLiquidCompileStrategy;

// Make a new instance of the shopify-liquid engine
let engine = Liquid({ /* some custom settings here! */ });

// There are two ways to use a custom compilation strategy:

// The first way: set the default compilation strategy globally and be done with it!
// Note that defaultCompileStrategy defaults to DummyCompileStrategy unless shopify-liquid
// is available, which should be the case unless you didn't install the optional
// dependencies.
liquidate.CompileStrategy.defaultCompileStrategy = new ShopifyLiquidCompileStrategy(engine);

gulp.src('./src/*.liquid')
    .pipe(liquidate({ 'localVarOne': true, 'localVarTwo': false }))
    .pipe(gulp.dest('./dist'));

// The second way: pass in your preferred compilation strategy as an option to
// gulp-liquidate at one specific point in your pipeline. 
gulp.src('./src/*.liquid')
    .pipe(liquidate(
        { 'a':'will be visible from within the Liquid template', 'b': 'so will this' },
        { 'compileStrategy': new ShopifyLiquidCompileStrategy(engine) }
    ))
    .pipe(gulp.dest('./dist'));

// Both of the above methods will yield the same output.

Quickly and easily get gulp-liquidate to work with whatever liquid engine you want (in this example, TinyLiquid):

const gulp = require('gulp');
const liquidate = require('gulp-liquidate');
const engine = require('tinyliquid');

const CompileStrategy = liquidate.CompileStrategy;

class TinyLiquidCompileStrategy extends CompileStrategy
{
    constructor(engine)
    {
        super();
        this._engine = engine;
    }

    compile(raw, context)
    {
        let render = this._engine.compile(raw);
        let engineContext = this._engine.newContext({ 'locals': context });
    
        // XXX: gulp-liquidate expects #compile() to return a Promise
        return new Promise((resolve, reject) =>
        {
            render(engineContext, err =>
            {
                if(err) reject(err);
                resolve(engineContext.getBuffer());
            });
        });
    }

    getActiveEngine()
    {
        return this._engine;
    }
}

liquidate.CompileStrategy.defaultCompileStrategy = new TinyLiquidCompileStrategy(engine);

gulp.src('./src/*.liquid')
    .pipe(liquidate({ 'localVarOne': true, 'localVarTwo': false }))
    .pipe(gulp.dest('./dist'));

Note: In the case of using the builtin shopify-liquid compilation strategy, when using the {% include 'somefile.liquid' %} liquid tag, keep in mind that, unless you set the root explicitly via instantion of a custom Liquid engine, the root will default to the current working directory. If you're using Liquid for the purposes of preprocessing, that means only run gulp from the root directory of your project (by default).

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.1.x Rapid iteration