Skip to main content

Render Context

The result of rendering a template depends on the context in which it is rendered. That is, available variables and their values, and options set on the bound Environment.

Template global variables are those added to a render context by application developers. From a template author's perspective, globals are read-only and are available to all templates, including those rendered with the render tag.

Local variables are those defined by template authors using {% assign %} and {% capture %}. Local variables can mask names defined in the global namespace, but never change them.

Named counters created with {% increment %} and {% decrement %} have their own namespace. Outside of an increment or decrement tag, Liquid will look in the counters namespace last, after locals and globals.

Environment Globals​

You can add global variables to an Environment using the globals option. Environment globals are automatically added to the render context of every Template created from that environment.

import { Environment } from "liquidscript";

const env = new Environment({ globals: { site_name: "My Site" } });
const source = `
<html>
  <head>
    <title>{{ site_name }}</title>
  </head>
</html>
`;

const template = env.fromString(source);
console.log(template.renderSync());
output
<html>
  <head>
    <title>My Site</title>
  </head>
</html>

Template Globals​

Similar to Environment Globals, you can pin global template variables to a Template. Globals set on a template will be merged with any set on its environment and added to the render context automatically.

If environment and template globals have conflicting names, template variables will take priority over environment variables.

import { Environment } from "liquidscript";

const env = new Environment({ globals: { site_name: "My Site" } });
const source = `
<html>
  <head>
    <title>{{ site_name }} - {{ page.name }}</title>
  </head>
</html>
`;

const template = env.fromString(source, { page: { name: "Blog" } });
console.log(template.renderSync());
output
<html>
  <head>
    <title>My Site - Blog</title>
  </head>
</html>

Render Arguments​

Properties from the object passes to Template.render() and Template.renderSync() are also added to the global namespace, although, unlike environment and template globals, they do not persist between calls to render().

render() keyword arguments take priority over environment and template globals.

import { Environment } from "liquidscript";

const env = new Environment({ globals: { site_name: "My Site" } });
const source = `
<html>
  <head>
    <title>{{ site_name }} - {{ page.name }}</title>
  </head>
  <body>
    <p>Hello, {{ user.name }}</p>
  </body>
</html>
`;

const template = env.fromString(source, { page: { name: "Blog" } });
console.log(template.renderSync({ user: { name: "Sally" } }));
output
<html>
  <head>
    <title>My Site - Blog</title>
  </head>
  <body>
    <p>Hello, Sally</p>
  </body>
</html>

Matter​

Matter variables are those that are added to a template by a loader. They could be from a front matter loader or extra meta data from a database loader.

These, too, are merged into the global namespace, taking priority over template globals, but not render() keyword arguments.