A shopify compatible Liquid template engine in pure JavaScript.
MIT License
A shopify compatible Liquid template engine for Gulp using liquidjs.
npm install --save-dev @tuanpham-dev/gulp-liquidjs
const gulp = require('gulp')
const liquid = require('gulp-liquidjs')
gulp.task('liquid', () => {
return gulp.src('./src/*.liquid')
.pipe(liquid())
.pipe(gulp.dest('./dist'))
})
with gulp-data
gulp
.pipe(data(function(file) {
// build your data for liquid
})
.pipe(liquid())
All options are optional.
engine
Engine options.
.pipe(liquid({
engine: {
root: ['./src/liquid/templates', './src/liquid/snippets'],
extname: '.liquid'
}
}))
root
is a directory or an array of directories to resolve layouts and includes, as well as the filename passed in when calling .renderFile()
.
If an array, the files are looked up in the order they occur in the array.
Defaults to ["."]
extname
is used to lookup the template file when filepath doesn't include an extension name. Eg: setting to ".html"
will allow including file by basename. Defaults to ".liquid"
.
cache
indicates whether or not to cache resolved templates. Defaults to false
.
dynamicPartials
: if set, treat <filepath>
parameter in {%include filepath %}
, {%layout filepath%}
as a variable, otherwise as a literal value. Defaults to true
.
strictFilters
is used to enable strict filter existence. If set to false
, undefined filters will be rendered as empty string. Otherwise, undefined filters will cause an exception. Defaults to false
.
strictVariables
is used to enable strict variable derivation.
If set to false
, undefined variables will be rendered as empty string.
Otherwise, undefined variables will cause an exception. Defaults to false
.
trimTagRight
is used to strip blank characters (including
, \t
, and \r
) from the right of tags ({% %}
) until \n
(inclusive). Defaults to false
.
trimTagLeft
is similiar to trimTagRight
, whereas the \n
is exclusive. Defaults to false
. See [Whitespace Control][whitespace control] for details.
trimOutputRight
is used to strip blank characters (including
, \t
, and \r
) from the right of values ({{ }}
) until \n
(inclusive). Defaults to false
.
trimOutputLeft
is similiar to trimOutputRight
, whereas the \n
is exclusive. Defaults to false
. See [Whitespace Control][whitespace control] for details.
tagDelimiterLeft
and tagDelimiterRight
are used to override the delimiter for liquid tags.
outputDelimiterLeft
and outputDelimiterRight
are used to override the delimiter for liquid outputs.
greedy
is used to specify whether trim*Left
/trim*Right
is greedy. When set to true
, all consecutive blank characters including \n
will be trimed regardless of line breaks. Defaults to true
.
ext
Extension name of destination filename. Defaults to .html
.
.pipe(liquid({
ext: '.html'
}))
filters
Array of filter object to register custom filters: {<filter_name>: <filter_function>}
.
.pipe(liquid({
filters: {
// Usage: {{ name | upper }}
upper: v => v.toUpperCase(),
// Usage: {{ 1 | add: 2, 3 }}
add: (initial, arg1, arg2) => initial + arg1 + arg2
}
}))
See existing filter implementations here: https://github.com/harttle/liquidjs/tree/master/src/builtin/filters
tags
Array of tag object to register custom tags: {<tag_name> : {parse: <parse_function>, render: <render_function>}}
.pipe(liquid({
tags: {
// Usage: {% upper name %}
upper: {
parse: (tagToken, remainTokens) => {
this.str = tagToken.args // name
},
render: async (scope, hash) {
var str = await liquid.evalValue(this.str, scope) // 'alice'
return str.toUpperCase() // 'ALICE
}
}
}
}))
plugins
A pack of tags or filters can be encapsulated into a plugin, which will be typically installed via npm.
const somePlugin = require('./some-plugin')
gulp.task('liquid', () => {
return gulp.src('./src/*.liquid')
.pipe(liquid({
plugins: [somePlugin]
}))
.pipe(gulp.dest('./dist'))
})
// some-plugin.js
module.exports = (Liquid) => {
// here `this` refers to the engine instance
// `Liquid` provides facilities to implement tags and filters
this.registerFilter('foo', x => x);
}