shopify-liquid

shopify-liquid

A feature-rich Liquid implementation for Node.js, with compliance with Jekyll and Github Pages.

Installation:

npm install --save shopify-liquid

Render from String

Parse and Render:

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

engine.parseAndRender('{{name | capitalize}}', {name: 'alice'});  // Alice

Caching templates:

var tpl = engine.parse('{{name | capitalize}}');
engine.render(tpl, {name: 'alice'}); // Alice

Render from File

var engine = Liquid({
    root: path.resolve(__dirname, 'views/'),  // for layouts and partials
    extname: '.liquid',
    cache: false
});
// equivalent to: engine.renderFile("hello", {name: 'alice'});
var html = engine.renderFile("hello.liquid", {name: 'alice'});

cache default to false, extname default to .liquid, root default to "".

Use with Express.js

app.engine('liquid', engine.express());
app.set('views', './views');        // specify the views directory
app.set('view engine', 'liquid');   // register the template engine

Includes

// file: color.liquid
color: '{{ color }}' shape: '{{ shape }}'

// file: theme.liquid
{% assign shape = 'circle' %}
{% include 'color' %}
{% include 'color' with 'red' %}
{% include 'color', color: 'yellow', shape: 'square' %}

The output will be:

color: '' shape: 'circle'
color: 'red' shape: 'circle'
color: 'yellow' shape: 'square'

Layouts

// file: default-layout.liquid
Header
{% block content %}My default content{% endblock %}
Footer

// file: page.liquid
{% layout "default-layout" %}
{% block content %}My page content{% endblock %}

The output of page.liquid:

Header
My page content
Footer

• It's possible to define multiple blocks.
• block name is optional when there's only one block.

Register Filters

// Usage: {{ name | uppper }}
engine.registerFilter('upper', function(v){
  return v.toUpperCase();
});

See existing filter implementations: https://github.com/harttle/shopify-liquid/blob/master/filters.js

Register Tags

// Usage: {% upper name%}
engine.registerTag('upper', {
    parse: function(tagToken, remainTokens) {
        this.str = tagToken.args; // name
    },
    render: function(scope, hash) {
        var str = Liquid.evalValue(this.str, scope); // 'alice'
        return str.toUpperCase(); // 'Alice'
    }
});

See existing tag implementations: https://github.com/harttle/shopify-liquid/blob/master/tags/

All Tags

Documentation: https://shopify.github.io/liquid/basics/introduction/#tags

Tag	Document	Source	Test
case/when	Document	Source	Test
if	Document	Source	Test
unless	Document	Source	Test
elsif/else	Document	Source	Test
for	Document	Source	Test
break	Document	Source	Test
continue	Document	Source	Test
for: limit,offset,range,reversed	Document	Source	Test
cycle	Document	Source	Test
cycle: group	Document	Source	Test
tablerow	Document	Source	Test
tablerow: cols,limit,offset,range	Document	Source	Test
assign	Document	Source	Test
capture	Document	Source	Test
increment	Document	Source	Test
decrement	Document	Source	Test
raw	Document	Source	Test
comment	Document	Source	Test
include	Document	Source	Test
layout, block	Document	Source	Test

All Filters

Documentation: https://shopify.github.io/liquid/basics/introduction/#filters

Filter	Document	Source	Test
abs	Document	Source	Test
append	Document	Source	Test
capitalize	Document	Source	Test
ceil	Document	Source	Test
date	Document	Source	Test
default	Document	Source	Test
divided_by	Document	Source	Test
downcase	Document	Source	Test
escape	Document	Source	Test
escape_once	Document	Source	Test
first	Document	Source	Test
floor	Document	Source	Test
join	Document	Source	Test
last	Document	Source	Test
lstrip	Document	Source	Test
map	Document	Source	Test
minus	Document	Source	Test
modulo	Document	Source	Test
newline_to_br	Document	Source	Test
plus	Document	Source	Test
prepend	Document	Source	Test
remove	Document	Source	Test
remove_first	Document	Source	Test
replace	Document	Source	Test
replace_first	Document	Source	Test
reverse	Document	Source	Test
round	Document	Source	Test
rstrip	Document	Source	Test
size	Document	Source	Test
slice	Document	Source	Test
sort	Document	Source	Test
split	Document	Source	Test
strip	Document	Source	Test
strip_html	Document	Source	Test
strip_newlines	Document	Source	Test
times	Document	Source	Test
truncate	Document	Source	Test
truncatewords	Document	Source	Test
uniq	Document	Source	Test
upcase	Document	Source	Test
url_encode	Document	Source	Test

Operators

Documentation: https://shopify.github.io/liquid/basics/operators/

==, !=, >, <, >=, <=, or, and, contains.

Async Support

harttle/shopify-liquid do NOT support async rendering, this is by design.

The primary principle of harttle/shopify-liquid is EASY TO EXTEND. Async rendering introduces extra complexity in both implementation and extension.

For template-driven projects, checkout these Liquid-like engines:

• liquid-node: https://github.com/sirlantis/liquid-node
• nunjucks: http://mozilla.github.io/nunjucks/