LiquidJS

https://liquidjs.com/tutorials/
Admin
LiquidJS is a simple, expressive, and safe template engine written in pure JavaScript, compatible...
Tokens:20,713
Snippets:90
Trust Score:9.1
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install LiquidJS in Node.js

Source: https://liquidjs.com/tutorials/setup

Installs the LiquidJS package using npm. This is the first step for using LiquidJS in a Node.js environment.

```bash
npm install --save liquidjs
```

--------------------------------

### Jekyll Include Syntax Example in LiquidJS

Source: https://liquidjs.com/tutorials/options

Shows how to enable Jekyll-like include syntax in LiquidJS. This involves static filenames, using '=' for parameter separation, and accessing parameters under the 'include' variable.

```liquid
// entry template
{% include article.html header="HEADER" content="CONTENT" %}

// article.html
<article>
  <header>{{include.header}}</header>
  {{include.content}}
</article>
```

--------------------------------

### Async LiquidJS Drop with liquidMethodMissing

Source: https://liquidjs.com/tutorials/drops

Illustrates an asynchronous implementation of liquidMethodMissing in a LiquidJS Drop. This example shows fetching data dynamically from a database, demonstrating how Drops can handle async operations for property resolution.

```javascript
import { Liquid, Drop } from 'liquidjs'

class DBDrop extends Drop {
  async liquidMethodMissing(key) {
    const record = await db.getRecordByKey(key)
    return record.value
  }
}

const engine = new Liquid()
const context = { db: new DBDrop() }
engine.parseAndRender("{{db.coo}}", context).then(html => console.log(html))
```

--------------------------------

### LiquidJS RenderLimit Example

Source: https://liquidjs.com/tutorials/dos

Demonstrates a LiquidJS template with a large loop that could exceed the renderLimit. This example highlights how dynamic loops can consume significant rendering time, potentially triggering the renderLimit.

```liquid
{%- for i in (1..10000000) -%}
    order: {{i}}
{%- endfor -%}
```

--------------------------------

### Dynamic Partials Example in LiquidJS

Source: https://liquidjs.com/tutorials/options

Illustrates the 'dynamicPartials' option in LiquidJS. When true (default), it treats filename arguments in include/render/layout tags as variables. Setting it to false allows for static file inclusion.

```liquid
{% include file %}
```

```liquid
{% liquid foo.html %}
```

--------------------------------

### Render templates from an in-memory mapping with LiquidJS

Source: https://liquidjs.com/tutorials/render-file

This example demonstrates how to use the `templates` option in LiquidJS to render templates directly from an in-memory object, eliminating the need for physical files. It defines a mapping of template names to their content and then renders a template using `renderFileSync`.

```javascript
const engine = new Liquid({
  templates: {
    'views/entry': 'header {% include "../partials/footer" %}',
    'partials/footer': 'footer'
  }
})
engine.renderFileSync('views/entry'))
// Result: 'header footer'
```

--------------------------------

### Configure LiquidJS template lookup with multiple root directories (Node.js)

Source: https://liquidjs.com/tutorials/render-file

This example shows how to configure LiquidJS to look for template files in multiple directories. The `root` option is set to an array of paths, and templates will be searched in the order specified. The `extname` option is also set for template file extensions.

```javascript
var engine = new Liquid({
    root: ['views/', 'views/partials/'],
    extname: '.liquid'
});
```

--------------------------------

### Importing LiquidJS (JavaScript)

Source: https://liquidjs.com/tutorials/migrate-to-9

Demonstrates the correct way to import the LiquidJS class after version 9, as the default export has been removed. This ensures compatibility with the latest version.

```javascript
import { Liquid } from 'liquidjs';
```

--------------------------------

### LiquidJS: Example Usage of Repeat Tag

Source: https://liquidjs.com/tutorials/render-tag-content

This snippet shows the Liquid template syntax for using the custom 'repeat' tag. It includes an example of how to access a variable ('repeat.i') within the repeated content, demonstrating the context manipulation achieved by the 'repeat' tag implementation.

```liquid
{% repeat %}
  {{ repeat.i }}. {{ "hello world!" | capitalize }}
{% endrepeat %}
```

--------------------------------

### LiquidJS 'and' Operator Example

Source: https://liquidjs.com/tutorials/operators

Illustrates the 'and' operator in LiquidJS, which evaluates to true only if both conditions are met. This is commonly used for checking multiple criteria, like age and verification status for access.

```liquid
{% if user.age >= 18 and user.verified %}
  Access granted
{% endif %}
```

--------------------------------

### LiquidJS MemoryLimit Example

Source: https://liquidjs.com/tutorials/dos

Illustrates a LiquidJS template that can lead to exponential memory growth through repeated array concatenation. This example shows how memory-sensitive filters can cause excessive memory allocation, which memoryLimit aims to prevent.

```liquid
{% assign array = "1,2,3" | split: "," %}
{% for i in (1..32) %}
    {% assign array = array | concat: array %}
{% endfor %}
```

--------------------------------

### LiquidJS 'or' Operator Example

Source: https://liquidjs.com/tutorials/operators

Shows the 'or' operator in LiquidJS, which returns true if at least one of the conditions is met. This is useful for granting privileges based on multiple roles, such as admin or moderator.

```liquid
{% if user.isAdmin or user.isModerator %}
  You have elevated privileges
{% endif %}
```

--------------------------------

### Register Filter with Arguments in LiquidJS

Source: https://liquidjs.com/tutorials/register-filters-tags

This example shows how to register a custom filter 'add' in LiquidJS that accepts multiple arguments. The filter takes an initial value and two additional arguments, summing them up. This demonstrates how to handle arguments passed to filters in LiquidJS.

```javascript
// Usage: {{ 1 | add: 2, 3 }}
engine.registerFilter('add', (initial, arg1, arg2) => initial + arg1 + arg2)
```

--------------------------------

### Synchronous Rendering with LiquidJS (JavaScript)

Source: https://liquidjs.com/tutorials/migrate-to-9

Illustrates how to use the new synchronous rendering methods introduced in LiquidJS 9. These methods, such as `renderSync`, `parseAndRenderSync`, and `renderFileSync`, allow for non-asynchronous template processing.

```javascript
const engine = new Liquid();
const output = engine.renderSync({ html: '{{ "Hello" }}' });
console.log(output); // "Hello"
```

--------------------------------

### Registering a Simple Filter in LiquidJS

Source: https://liquidjs.com/tutorials/access-scope-in-filters

Demonstrates how to register a basic filter in LiquidJS that accepts arguments. The filter 'add' takes an initial value and two additional arguments, returning their sum. This is a fundamental example of filter registration.

```javascript
// Usage: {{ 1 | add: 2, 3 }}
// Output: 6
engine.registerFilter('add', (initial, arg1, arg2) => initial + arg1 + arg2)
```

--------------------------------

### LiquidJS 'not' Operator Example

Source: https://liquidjs.com/tutorials/operators

Demonstrates the 'not' operator in LiquidJS, which negates a boolean condition. It returns true if the condition is false and vice versa. This is useful for checking inverse states, such as an inactive user.

```liquid
{% if not user.active %}
  User is inactive
{% endif %}
```

--------------------------------

### Liquid Escape with 'raw' tag in LiquidJS

Source: https://liquidjs.com/tutorials/escaping

Explains how to use the 'raw' tag in LiquidJS to disable Liquid syntax processing within a block. This is useful for displaying Liquid code examples or strings that contain Liquid delimiters like {{ and {% without them being interpreted by the engine.

```liquid
{% raw %}
  In LiquidJS, {{ this | escape }} will be HTML-escaped, but
  {{{ that }}} will not.
{% endraw %}
```

--------------------------------

### Register Advanced Tag Class in LiquidJS

Source: https://liquidjs.com/tutorials/register-filters-tags

This example demonstrates registering a custom tag 'upper' using a class-based approach in LiquidJS. This method is suitable for more complex tags, allowing for constructor-based initialization and a cleaner separation of concerns. The tag processes named arguments.

```typescript
// Usage: {% upper name:"alice" %}
import { Hash, Tag, TagToken, Context, Emitter, TopLevelToken, Liquid } from 'liquidjs'

engine.registerTag('upper', class UpperTag extends Tag {
    private hash: Hash
    constructor(tagToken: TagToken, remainTokens: TopLevelToken[], liquid: Liquid) {
        super(tagToken, remainTokens, liquid)
        this.hash = new Hash(tagToken.args)
    }
    * render(ctx: Context) {
        const hash = yield this.hash.render();
        return hash.name.toUpperCase() // 'ALICE'
    }
});
```

--------------------------------

### Render Template from CLI with LiquidJS

Source: https://liquidjs.com/tutorials/setup

Demonstrates rendering a LiquidJS template directly from the command line using npx. Templates can be provided inline or read from files.

```bash
npx liquidjs --template '{{"hello" | capitalize}}'
```

```bash
npx liquidjs --template @./some-template.liquid
```

```bash
echo '{{"hello" | capitalize}}' | npx liquidjs --template @-
```

--------------------------------

### Layout Templates (Extends) in LiquidJS

Source: https://liquidjs.com/tutorials/partials-and-layouts

Explains how to use layout templates in LiquidJS to create reusable page structures. It demonstrates the `layout` tag and `block` tag for defining and overriding content sections. The '.liquid' extension can be omitted if configured.

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

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

--------------------------------

### Render Partials in LiquidJS

Source: https://liquidjs.com/tutorials/partials-and-layouts

Demonstrates how to render partial template files in LiquidJS. It shows different ways to pass variables to partials, including default values and explicit variable assignments. The '.liquid' extension can be omitted if configured.

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

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

--------------------------------

### Basic Output with Whitespace in LiquidJS

Source: https://liquidjs.com/tutorials/whitespace-control

Demonstrates how default LiquidJS tags and output markups generate newlines and indentation, resulting in blank lines in the output.

```liquid
{%  author = "harttle" %}
{{ author }}
```

--------------------------------

### Basic LiquidJS Drop Implementation

Source: https://liquidjs.com/tutorials/drops

Demonstrates the basic usage of LiquidJS Drops by creating a custom SettingsDrop class that extends the Drop interface. This allows accessing properties and calling methods directly from the template context.

```javascript
import { Liquid, Drop } from 'liquidjs'

class SettingsDrop extends Drop {
  constructor() {
    super()
    this.foo = 'FOO'
  }
  bar() {
    return 'BAR'
  }
}

const engine = new Liquid()
const template = `foo: {{settings.foo}}, bar: {{settings.bar}}`
const context = { settings: new SettingsDrop() }
// Outputs: "foo: FOO, bar: BAR"
engine.parseAndRender(template, context).then(html => console.log(html))
```

--------------------------------

### Get Variable Segments (LiquidJS)

Source: https://liquidjs.com/tutorials/static-analysis

Retrieves an array of arrays, where each inner array contains the strings and numbers that form the path of a variable in a LiquidJS template. This provides a structured representation of variable access.

```javascript
// continued from above
engine.variableSegments(template).then(console.log)
```

--------------------------------

### Specify Output File from CLI with LiquidJS

Source: https://liquidjs.com/tutorials/setup

Illustrates how to direct the rendered output of a LiquidJS template to a specified file when using the CLI. If the file exists, it will be overwritten.

```bash
npx liquidjs --template '{{"hello" | capitalize}}' --output ./hello.txt
```

--------------------------------

### Use Custom Plugin in LiquidJS Rendering

Source: https://liquidjs.com/tutorials/plugins

This JavaScript code demonstrates how to use a custom LiquidJS plugin. It initializes a new Liquid engine, loads the plugin using `engine.plugin()`, and then renders a template that utilizes the custom 'upup' filter. The output will be the result of the filter applied to the input string.

```javascript
const Liquid = require('liquidjs');
const engine = new Liquid();

engine.plugin(require('./upup.js'));

engine
    .parseAndRender('{{ "foo" | upup }}')
    .then(console.log)  // outputs "FOO"
```

--------------------------------

### Get Variables from Template (LiquidJS)

Source: https://liquidjs.com/tutorials/static-analysis

Retrieves an array of distinct variable names used in a LiquidJS template. This method includes variables from tags and filters, and nested variables. It does not include properties of variables.

```javascript
import { Liquid } from 'liquidjs'

const engine = new Liquid()

const template = engine.parse(`
<p>
  {% assign title = user.title | capitalize %}
  {{ title }} {{ user.first_name | default: user.name }} {{ user.last_name }}
  {% if user.address %}
    {{ user.address.line1 }}
  {% else %}
    {{ user.email_addresses[0] }}
    {% for email in user.email_addresses %}
       - {{ email }}
    {% endfor %}
  {% endif %}
  {{ a[b.c].d }}
<p>
`)

console.log(engine.variablesSync(template))
```

--------------------------------

### Render a LiquidJS file with a specified root directory (Node.js)

Source: https://liquidjs.com/tutorials/render-file

This snippet demonstrates how to configure LiquidJS to render a template file by setting the `root` option to the directory containing the templates and specifying the `extname`. The `renderFile` method is used to process a template named 'hello' with provided data.

```javascript
var engine = new Liquid({
    root: path.resolve(__dirname, 'views/'),  // root for layouts/includes lookup
    extname: '.liquid'          // used for layouts/includes, defaults ""
});
engine
    .renderFile("hello", {name: 'alice'})   // will read and render `views/hello.liquid`
    .then(console.log)  // outputs "name: alice"
```

--------------------------------

### LiquidJS 'contains' Operator Example

Source: https://liquidjs.com/tutorials/operators

Explains the 'contains' operator in LiquidJS, used to check for the presence of a substring within a string or an element within an array. It's helpful for filtering or conditional logic based on content.

```liquid
{% if product.title contains "Pack" %}
  This is a pack
{% endif %}
```

--------------------------------

### Render Template in TypeScript with LiquidJS

Source: https://liquidjs.com/tutorials/setup

Shows how to use LiquidJS in a TypeScript project. It utilizes type definitions for a more robust development experience.

```typescript
import { Liquid } from 'liquidjs';
const engine = new Liquid();

engine
    .parseAndRender('{{name | capitalize}}', {name: 'alice'})
    .then(console.log);     // outputs 'Alice'
```

--------------------------------

### JavaScript Truthiness in LiquidJS

Source: https://liquidjs.com/tutorials/options

Explains the 'jsTruthy' option in LiquidJS. When true, it uses standard JavaScript truthiness rules. For example, a blank string evaluates to false with jsTruthy, unlike Shopify's default where it's true.

```javascript
// Example demonstrating jsTruthy behavior (conceptual)
// With jsTruthy: false (default), '' is true
// With jsTruthy: true, '' is false
```

--------------------------------

### LiquidJS Drop with liquidMethodMissing

Source: https://liquidjs.com/tutorials/drops

Shows how to use the liquidMethodMissing method in a LiquidJS Drop to dynamically resolve variable values. This is useful when the set of properties is not fixed, allowing for on-the-fly value generation.

```javascript
import { Liquid, Drop } from 'liquidjs'

class SettingsDrop extends Drop {
  liquidMethodMissing(key) {
    return key.toUpperCase()
  }
}

const engine = new Liquid()
// Outputs: "COO"
engine.parseAndRender("{{settings.coo}}", { settings: new SettingsDrop() })
  .then(html => console.log(html))
```

--------------------------------

### Using Instance Method evalValue in LiquidJS (JavaScript)

Source: https://liquidjs.com/tutorials/migrate-to-9

Shows the usage of the `evalValue` instance method in LiquidJS, replacing the deprecated static method `Liquid.evalValue`. This method is used for evaluating Liquid expressions within templates.

```javascript
const engine = new Liquid();
const context = { name: 'World' };
const value = engine.evalValue('name', context);
console.log(value); // "World"
```

--------------------------------

### Implement a custom abstract file system for LiquidJS (Node.js)

Source: https://liquidjs.com/tutorials/render-file

This snippet illustrates how to provide a custom file system implementation to LiquidJS using the `fs` option. It defines methods like `readFileSync`, `readFile`, `existsSync`, `exists`, `contains`, and `resolve` to handle template fetching logic, in this case, from a database.

```javascript
var engine = new Liquid({
    fs: {
        readFileSync (file) {
            return db.model('Template').findByIdSync(file).text
        },
        async readFile (file) {
            const template = await db.model('Template').findById(file)
            return template.text
        },
        existsSync () {
            return true
        },
        async exists () {
            return true
        },
        contains () {
            return true
        },
        resolve(root, file, ext) {
            return file
        }
    }
});
```

--------------------------------

### Get Global Variables (LiquidJS)

Source: https://liquidjs.com/tutorials/static-analysis

Retrieves an array of variable names that are expected to be provided by application developers, excluding those defined within the template itself (e.g., via `assign` or `for` tags). This helps in identifying externally provided data.

```javascript
// continued from above
engine.globalVariableSegments(template).then(console.log)
```

--------------------------------

### Include LiquidJS in Browsers

Source: https://liquidjs.com/tutorials/setup

Provides script tags for including LiquidJS in web pages for browser-based rendering. It offers both production and development UMD bundles.

```html
<!--for production-->
<script src="https://cdn.jsdelivr.net/npm/liquidjs/dist/liquid.browser.min.js"></script>
<!--for development-->
<script src="https://cdn.jsdelivr.net/npm/liquidjs/dist/liquid.browser.umd.js"></script>
```

--------------------------------

### Get Full Variable Paths (LiquidJS)

Source: https://liquidjs.com/tutorials/static-analysis

Retrieves an array of strings representing the full paths of variables used in a LiquidJS template, including their properties. This method is useful for understanding the complete structure of variable access within a template.

```javascript
// continued from above
engine.fullVariables(template).then(console.log)
```

--------------------------------

### Parse Parameters as Values in LiquidJS

Source: https://liquidjs.com/tutorials/parse-parameters

Shows how to parse tag parameters as literal values or context variables using LiquidJS's Tokenizer. It handles string literals, identifiers, and property access sequences. Requires LiquidJS, Tokenizer, and evalToken.

```javascript
const { Liquid, Tokenizer, evalToken } = require('liquidjs')
const engine = new Liquid()

// {% random "foo" bar obj.coo %}
engine.registerTag('random', {
  parse(tagToken) {
    const tokenizer = new Tokenizer(tagToken.args)
    this.items = []
    while (!tokenizer.end()) {
      // here readValue() returns a LiteralToken or PropertyAccessToken
      this.items.push(tokenizer.readValue())
    }
  },
  * render(context, emitter) {
    const index = Math.floor(this.items.length * Math.random())
    const token = this.items[index]
    // in LiquidJS, we use yield to wait for async call
    const value = yield evalToken(token, context)
    emitter.write(value)
  }
})
```

--------------------------------

### Convert LiquidJS Generator to Promise

Source: https://liquidjs.com/tutorials/sync-and-async

Illustrates how to convert a LiquidJS generator-based tag implementation into a Promise using the `toPromise` utility. This allows the tag to be used in an `async` context and handle asynchronous operations with `await`.

```typescript
import { TagToken, Context, Emitter, TopLevelToken, Value, Tag, Liquid, toPromise } from 'liquidjs'

// Usage: {% upper "alice" %}
// Output: ALICE
engine.registerTag('upper', class UpperTag extends Tag {
  private value: Value
  constructor (token: TagToken, remainTokens: TopLevelToken[], liquid: Liquid) {
    super(token, remainTokens, liquid)
    this.value = new Value(token.args, liquid)
  }
  async render (ctx: Context, emitter: Emitter) {
    const title = await toPromise(this.value.value(ctx))
    emitter.write(title.toUpperCase())
  }
})
```

--------------------------------

### Pass Context from CLI with LiquidJS

Source: https://liquidjs.com/tutorials/setup

Shows how to pass context data to LiquidJS templates when rendering from the CLI. Context can be provided inline, from a JSON file, or via stdin.

```bash
npx liquidjs --template 'Hello, {{ name }}!' --context '{"name": "Snake"}'
```

```bash
npx liquidjs --template 'Hello, {{ name }}!' --context @./some-context.json
```

```bash
echo '{"name": "Snake"}' | npx liquidjs --template 'Hello, {{ name }}!' --context @-
```

--------------------------------

### Setting Default File Extension with extname

Source: https://liquidjs.com/tutorials/options

Demonstrates the 'extname' option in LiquidJS, which defines a default extension for filenames lacking one. If set to '.liquid', 'foo' will be treated as 'foo.liquid'.

```liquid
{% render "foo" %}  there's no extname, adds `.liquid` and loads foo.liquid
{% render "foo.html" %}  there is an extname already, loads foo.html directly
```

--------------------------------

### Render Template in Node.js with LiquidJS

Source: https://liquidjs.com/tutorials/setup

Demonstrates basic template rendering in Node.js using LiquidJS. It parses a template string with a filter and renders it with provided context.

```javascript
var { Liquid } = require('liquidjs');
var engine = new Liquid();

engine
    .parseAndRender('{{name | capitalize}}', {name: 'alice'})
    .then(console.log);     // outputs 'Alice'
```

--------------------------------

### Access Raw Tag Parameters in LiquidJS

Source: https://liquidjs.com/tutorials/parse-parameters

Demonstrates how to access raw tag parameters as a string using `tagToken.args`. This is useful for simple tags where parameters can be split directly. It requires the LiquidJS engine.

```javascript
const { Liquid } = require('liquidjs')
const engine = new Liquid()

// Usage: {% random foo bar coo %}
// Output: "foo", "bar" or "coo"
engine.registerTag('random', {
  parse(tagToken) {
    // tagToken.args === "foo bar coo"
    this.items = tagToken.args.split(' ')
  },
  render(context, emitter) {
    // get a random index
    const index = Math.floor(this.items.length * Math.random())
    // output that item
    emitter.write(this.items[index])
  }
})
```

--------------------------------

### Parse and Render Template from File - LiquidJS

Source: https://liquidjs.com/tutorials/caching

Shows how to parse a template file once and render it multiple times with varying contexts using LiquidJS. This improves performance by caching the parsed template from the file.

```javascript
var { Liquid } = require('liquidjs');
var engine = new Liquid();

// Assuming 'hello.liquid' contains '{{name}}'
var tpl = engine.parseFileSync('hello');

console.log(engine.renderSync(tpl, {name: 'alice'})); // 'Alice'
console.log(engine.renderSync(tpl, {name: 'bob'}));   // 'Bob'
```

--------------------------------

### Parse Key-Value Pairs as Named Parameters in LiquidJS

Source: https://liquidjs.com/tutorials/parse-parameters

Illustrates parsing named parameters using the Hash class in LiquidJS. This is ideal for optional or numerous parameters where order doesn't matter. Requires LiquidJS and Hash.

```javascript
const { Liquid, Hash } = require('liquidjs')
const engine = new Liquid()

// {% random from:2, to:max %}
engine.registerTag('random', {
  parse(tagToken) {
    // parse the parameters structure into `this.args`
    this.args = new Hash(tagToken.args)
  },
  * render(context, emitter) {
    // evaluate the parameters in `context`
    const {from, to} = yield this.args.render(context)
    const length = to - from + 1
    const value = from + Math.floor(length * Math.random())
    emitter.write(value)
  }
})
```

--------------------------------

### Conditional Logic with Tags in LiquidJS

Source: https://liquidjs.com/tutorials/intro-to-liquid

Demonstrates using `if`, `else`, and `endif` tags for conditional rendering in LiquidJS. This enables dynamic content display based on variable conditions.

```liquid
{% if foo == "FOO" %}
    Variable `foo` equals "FOO"
{% else %}
    Variable `foo` not equals "FOO"
{% endif %}
```

--------------------------------

### Configure LiquidJS with Cache Option

Source: https://liquidjs.com/tutorials/options

Demonstrates how to initialize LiquidJS with the 'cache' option enabled for performance improvement. This option caches previously parsed template structures, especially useful for repeated parsing or rendering.

```javascript
const { Liquid } = require('liquidjs')
const engine = new Liquid({
    cache: true
})
```

--------------------------------

### Basic LiquidJS Template Rendering (JavaScript)

Source: https://liquidjs.com/tutorials/index

This snippet demonstrates the fundamental usage of LiquidJS to parse a template string and render it with provided data. It initializes the Liquid engine, parses a simple template with a variable, and then renders it, outputting the result to the console. No external dependencies beyond the 'liquidjs' library are required.

```javascript
import { Liquid } from 'liquidjs'  
const engine = new Liquid()  
const tpl = engine.parse('Welcome to {{v}}!')  
engine.render(tpl, {v: "Liquid"}).then(console.log)  
// Outputs "Welcome to Liquid!"  
```

--------------------------------

### LiquidJS Drop with toLiquid Returning a Drop

Source: https://liquidjs.com/tutorials/drops

Illustrates a scenario where the toLiquid method within an object returns an instance of a custom Drop. This allows for more complex object structures to be managed and rendered effectively within LiquidJS templates.

```javascript
import { Liquid, Drop } from 'liquidjs'

class PersonDrop extends Drop {
  constructor(person) {
    super()
    this.person = person
  }
  name() {
    return this.person.lastName + ", " + this.person.firstName
  }
}

const context = {
  person: {
    firstName: "Jun",
    lastName: "Yang",
    name: "Jun Yang",
    toLiquid: function () { return new PersonDrop(this) }
  }
}

const engine = new Liquid()
// Outputs: "Yang, Jun"
engine.parseAndRender("{{person.name}}", context).then(html => console.log(html))
```

--------------------------------

### LiquidJS Drop with valueOf Method

Source: https://liquidjs.com/tutorials/drops

Demonstrates how to use the valueOf method within a LiquidJS Drop. The return value of valueOf() replaces the Drop instance itself during rendering, allowing for custom string representations.

```javascript
import { Liquid, Drop } from 'liquidjs'

class ColorDrop extends Drop {
  valueOf() {
    return 'red'
  }
}

const engine = new Liquid()
const context = { color: new ColorDrop() }
// Outputs: "red"
engine.parseAndRender("{{color}}", context).then(html => console.log(html))
```

--------------------------------

### Outputting Variables in LiquidJS

Source: https://liquidjs.com/tutorials/intro-to-liquid

Demonstrates how to output variable values into HTML using LiquidJS. This is a fundamental operation for inserting dynamic content into templates.

```html
<input type="text" name="user" value="{{username}}">
```

--------------------------------

### LiquidJS Object with toLiquid Method

Source: https://liquidjs.com/tutorials/drops

Shows how an object can implement a toLiquid method to control how it's rendered or accessed within a LiquidJS template. The toLiquid method returns a new scope object that LiquidJS will use instead of the original object.

```javascript
import { Liquid, Drop } from 'liquidjs'

const context = {
  person: {
    firstName: "Jun",
    lastName: "Yang",
    name: "Jun Yang",
    toLiquid: () => ({
      firstName: this.firstName,
      lastName: this.lastName,
      // use a different `name`
      name: "Yang, Jun"
    })
  }
}

const engine = new Liquid()
// Outputs: "Yang, Jun"
engine.parseAndRender("{{person.name}}", context).then(html => console.log(html))
```

--------------------------------

### Assigning Variables with Tags in LiquidJS

Source: https://liquidjs.com/tutorials/intro-to-liquid

Illustrates how to declare and assign values to variables using the `assign` tag in LiquidJS. This allows for storing and reusing data within templates.

```liquid
{% assign foo = "FOO" %}
```

--------------------------------

### Stripping Whitespace with Hyphens in LiquidJS

Source: https://liquidjs.com/tutorials/whitespace-control

Shows how to use hyphens within LiquidJS tag syntax (e.g., `-%}`) to strip whitespace from the right side of the tag, producing cleaner output.

```liquid
{% assign author = "harttle" -%}
{{ author }}
```

--------------------------------

### Implement Async-Only Tag in LiquidJS

Source: https://liquidjs.com/tutorials/sync-and-async

Demonstrates how to create a tag that is exclusively intended for asynchronous use. By declaring the `render` function as `async`, developers can directly use the `await` keyword for handling Promises within the tag implementation.

```typescript
import { toPromise, TagToken, Context, Emitter, TopLevelToken, Value, Tag, Liquid } from 'liquidjs'

// Usage: {% upper "alice" %}
// Output: ALICE
engine.registerTag('upper', class UpperTag extends Tag {
  private value: Value
  constructor (token: TagToken, remainTokens: TopLevelToken[], liquid: Liquid) {
    super(token, remainTokens, liquid)
    this.value = new Value(token.args, liquid)
  }
  async render (ctx: Context, emitter: Emitter) {
    const title = await toPromise(this.value.value(ctx))
    emitter.write(`<h1>${title}</h1>`)
  }
})
```

--------------------------------

### Parse and Render Template from String - LiquidJS

Source: https://liquidjs.com/tutorials/caching

Demonstrates parsing a template string once and rendering it multiple times with different contexts using LiquidJS. This method is useful for dynamic templates or when templates are not stored in files.

```javascript
var { Liquid } = require('liquidjs');
var engine = new Liquid();

var tpl = engine.parse('{{name | capitalize}}');

console.log(engine.renderSync(tpl, {name: 'alice'})); // 'Alice'
console.log(engine.renderSync(tpl, {name: 'bob'}));   // 'Bob'
```

--------------------------------

### Default HTML Escaping and 'raw' filter in LiquidJS

Source: https://liquidjs.com/tutorials/escaping

Shows how to configure LiquidJS to escape all output by default using 'outputEscape: "escape"'. It also illustrates the use of the 'raw' filter to prevent specific outputs from being escaped, allowing literal rendering of HTML or other special content.

```liquid
{{ "1 < 2" }}
{{ "<button>OK</button>" | raw }}
```

--------------------------------

### Configure Template Lookup with Root and Views Options

Source: https://liquidjs.com/tutorials/use-in-expressjs

Demonstrates how LiquidJS handles template lookup when both the `root` option for LiquidJS and the `views` option for Express.js are specified. This allows templates to be resolved from multiple directories.

```javascript
var { Liquid } = require('liquidjs');
var engine = new Liquid({
    root: './views1/'
});

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

// Both of these templates can be resolved and rendered:
// res.render('hello')
// res.render('world')
```

--------------------------------

### Applying Filters to Outputs in LiquidJS

Source: https://liquidjs.com/tutorials/intro-to-liquid

Shows how to transform output variables using filters in LiquidJS. Filters modify the variable's value before it's rendered, such as appending text or capitalizing.

```liquid
{{ username | append: ", welcome to LiquidJS!" }}
```

```liquid
{{ username | append: ", welcome to LiquidJS!" | capitalize }}
```

--------------------------------

### Register Sync-Compatible Tag in LiquidJS

Source: https://liquidjs.com/tutorials/sync-and-async

Demonstrates how to register a custom tag ('upper') that is compatible with both synchronous and asynchronous rendering in LiquidJS. This tag converts its input argument to uppercase. It utilizes a generator-based `render` function for sync-compatibility.

```typescript
import { TagToken, Context, Emitter, TopLevelToken, Value, Tag, Liquid } from 'liquidjs'

// Usage: {% upper "alice" %}
// Output: ALICE
engine.registerTag('upper', class UpperTag extends Tag {
  private value: Value
  constructor (token: TagToken, remainTokens: TopLevelToken[], liquid: Liquid) {
    super(token, remainTokens, liquid)
    this.value = new Value(token.args, liquid)
  }
  * render (ctx: Context, emitter: Emitter) {
    const title = yield this.value.value(ctx)
    emitter.write(title.toUpperCase())
  }
})
```

--------------------------------

### Enable JavaScript Truthiness from CLI with LiquidJS

Source: https://liquidjs.com/tutorials/setup

Demonstrates enabling JavaScript truthiness for template rendering via the CLI using the `--js-truthy` option. This affects how values are evaluated in conditions.

```bash
npx liquidjs --template @./some-template.liquid --js-truthy
```

--------------------------------

### Custom Block Tag Implementation in Liquid.js (JavaScript)

Source: https://liquidjs.com/tutorials/static-analysis

This JavaScript code demonstrates how to create a custom block tag in Liquid.js. It implements methods required for static analysis, including children() to define nested content, arguments() to parse tag arguments, and blockScope() to declare variables within the tag's scope. This allows custom tags to be analyzed by Liquid.js.

```javascript
import { Liquid, Tag, Hash } from 'liquidjs'

class ExampleTag extends Tag {
  args
  templates

  constructor (token, remainTokens, liquid, parser) {
    super(token, remainTokens, liquid)
    this.args = new Hash(token.tokenizer)
    this.templates = []

    const stream = parser.parseStream(remainTokens)
      .on('tag:endexample', () => { stream.stop() })
      .on('template', (tpl) => this.templates.push(tpl))
      .on('end', () => { throw new Error(`tag ${token.getText()} not closed`) })

    stream.start()
  }

  * render (ctx, emitter) {
    const scope = (yield this.args.render(ctx))
    ctx.push(scope)
    yield this.liquid.renderer.renderTemplates(this.templates, ctx, emitter)
    ctx.pop()
  }

  * children () {
    return this.templates
  }

  * arguments () {
    yield * Object.values(this.args.hash).filter((el) => el !== undefined)
  }

  blockScope () {
    return Object.keys(this.args.hash)
  }
}
```

--------------------------------

### Handle Promises within LiquidJS Sync-Compatible Tags

Source: https://liquidjs.com/tutorials/sync-and-async

Shows how to call asynchronous functions (like `fs.readFile`) that return Promises within a sync-compatible LiquidJS tag. The `yield` keyword is used to pause the generator and wait for the Promise to resolve, making the tag non-sync-compatible but functional for async operations.

```typescript
* render (ctx: Context, emitter: Emitter) {
  const file = yield this.value.value(ctx)
  const title = yield fs.readFile(file, 'utf8')
  emitter.write(title.toUpperCase())
}
```

--------------------------------

### Register Uppercase Filter Plugin for LiquidJS

Source: https://liquidjs.com/tutorials/plugins

This JavaScript code defines a LiquidJS plugin that registers a new filter named 'upup'. This filter takes a string as input and returns its uppercase version. The plugin function receives the Liquid class and uses `this.registerFilter` to add the new filter to the Liquid instance.

```javascript
/**
 * Inside the plugin function, `this` refers to the Liquid instance.
 *
 * @param Liquid: provides facilities to implement tags and filters.
 */
module.exports = function (Liquid) {
    this.registerFilter('upup', x => x.toUpperCase());
}
```

--------------------------------

### Enable Template Caching with 'cache' Option - LiquidJS

Source: https://liquidjs.com/tutorials/caching

Illustrates how to enable automatic template caching in LiquidJS using the 'cache' option. When enabled, LiquidJS caches parsed templates for subsequent calls to renderFile or renderFileSync, improving performance.

```javascript
var { Liquid } = require('liquidjs');
var engine = new Liquid({
    cache: true
});

// First render: liquidjs parses 'hello.liquid' and caches it.
engine.renderFileSync('hello', {name: 'alice'});

// Second render: liquidjs uses the cached template for 'hello.liquid'.
engine.renderFileSync('hello', {name: 'bob'});
```

--------------------------------

### Check for Blank Strings in LiquidJS

Source: https://liquidjs.com/tutorials/drops

The `blank` tag checks if a string variable is false, null, undefined, an empty string, or a string containing only whitespace. It's useful for validating user input or default values.

```liquid
{% unless author == blank %}
    {{author}}
{% endif %}
```
Tokens:
Raw