liquidjs

What is liquidjs?

LiquidJS is a JavaScript implementation of the Liquid templating language, which was originally created by Shopify. It allows you to render dynamic content in your web applications by using a simple and readable syntax. LiquidJS is highly extensible and can be used both on the server-side with Node.js and in the browser.

What are liquidjs's main functionalities?

Basic Template Rendering

This feature allows you to render basic templates with dynamic content. In this example, the template 'Hello, {{name}}!' is rendered with the variable 'name' set to 'World', resulting in 'Hello, World!'.

const { Liquid } = require('liquidjs');
const engine = new Liquid();
const template = 'Hello, {{name}}!';
engine.parseAndRender(template, { name: 'World' }).then(console.log);

Loops

This feature allows you to iterate over arrays and render each item. In this example, the template iterates over the 'items' array and renders each item, resulting in 'apple banana cherry '.

const { Liquid } = require('liquidjs');
const engine = new Liquid();
const template = '{% for item in items %}{{ item }} {% endfor %}';
engine.parseAndRender(template, { items: ['apple', 'banana', 'cherry'] }).then(console.log);

Conditionals

This feature allows you to use conditional statements in your templates. In this example, the template checks if the 'user' variable exists and renders 'Hello, Alice!' if it does, otherwise it renders 'Hello, Guest!'.

const { Liquid } = require('liquidjs');
const engine = new Liquid();
const template = '{% if user %}Hello, {{ user.name }}!{% else %}Hello, Guest!{% endif %}';
engine.parseAndRender(template, { user: { name: 'Alice' } }).then(console.log);

Filters

This feature allows you to use filters to transform output. In this example, the 'upcase' filter is used to convert the string 'hello' to uppercase, resulting in 'HELLO'.

const { Liquid } = require('liquidjs');
const engine = new Liquid();
const template = '{{ "hello" | upcase }}';
engine.parseAndRender(template).then(console.log);

Other packages similar to liquidjs

nunjucks

Nunjucks is a powerful templating engine for JavaScript, inspired by Jinja2. It offers a similar feature set to LiquidJS, including template inheritance, macros, and filters. Nunjucks is known for its flexibility and ease of use, making it a strong alternative to LiquidJS.

handlebars

Handlebars is a popular templating engine that provides a simple way to build semantic templates. It supports features like nested templates, partials, and helpers. Handlebars is known for its simplicity and performance, making it a good choice for projects that require straightforward templating.

ejs

EJS (Embedded JavaScript) is a templating engine that lets you generate HTML with plain JavaScript. It supports features like partials and includes, and is known for its simplicity and ease of integration with Express.js. EJS is a good option for developers who prefer a more JavaScript-centric approach to templating.

README

liquidjs

A Liquid engine implementation for both Node.js and browsers, with all shopify/liquid features. Formerly known as shopify-liquid.

Live Demo: http://harttle.com/liquidjs/

The Liquid template engine is implemented in Ruby originally, which is used by Jekyll and Github Pages.

Features:

• A wide range of filters and tags
• Easy tag/filter registration, allows async tags
• any-promise

API Reference:

• Builtin Tags: https://github.com/harttle/liquidjs/wiki/Builtin-Tags
• Builtin Filters: https://github.com/harttle/liquidjs/wiki/Builtin-Filters
• Operators: https://github.com/harttle/liquidjs/wiki/Operators
• Whitespace Control: https://github.com/harttle/liquidjs/wiki/Whitespace-Control

Installation:

npm install --save liquidjs

Render from String

Parse and Render:

var Liquid = require('liquidjs');
var engine = Liquid();

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

Caching templates:

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

Render from File

var engine = Liquid({
    root: path.resolve(__dirname, 'views/'),  // dirs to lookup layouts/includes
    extname: '.liquid'          // the default extname used for layouts/includes
});
engine.renderFile("hello.liquid", {name: 'alice'})
    .then(function(html){
       // html === 'Alice'
    });
// equivalent to: 
engine.renderFile("hello", {name: 'alice'})
    .then(function(html){
       // html === 'Alice'
    });

Options

The full list of options for Liquid() is listed as following:

• 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. Defaults to ".liquid"

• cache indicates whether or not to cache resolved templates. Defaults to false.

• strict_filters 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.

• strict_variables 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.

• trim_right is used to strip blank characters (including , \t, and \r) from the right of tags ({% %}) until \n (inclusive). Defaults to false.

• trim_left is similiar to trim_right, whereas the \n is exclusive. Defaults to false. See Whitespace Control for details.

• greedy is used to specify whether trim_left/trim_right is greedy. When set to true, all successive blank characters including \n will be trimed regardless of line breaks. Defaults to false.

Use with Express.js

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

There's an Express demo here.

When using with Express.js, partials(includes and layouts) will be looked up in both Liquid root and Express views directories.

Use in Browser

Download the dist files and import into your HTML. And window.Liquid is what you want. There's also a demo.

<html lang="en">
<head>
  <script src="dist/liquid.min.js"></script>
</head>
<body>
  <script>
    var engine = window.Liquid();
    var src = '{{ name | capitalize}}';
    var ctx = {
      name: 'welcome to liquidjs'
    };
    engine.parseAndRender(src, ctx)
      .then(function(html) {
        // html === Welcome to liquidjs
      });
  </script>
</body>
</html>

Note: In IE and Android UC browser, you need a Promise implementation registered to any-promise.

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/liquidjs/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 Promise.resolve(str.toUpperCase()); // 'Alice'
    }
});

See existing tag implementations: https://github.com/harttle/liquidjs/blob/master/tags/

Contribution Guide

1. Write a test to define the feature you want.
2. File an issue, or optionally:
3. Get your test pass and make a pull request.