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.

Template 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 increment or decrement, 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 argument to the Environment constructor. globals should be a dictionary (or any Mapping) mapping strings to Python objects. Environment globals are automatically added to the render context of every Template created with Environment.from_string() and Environment.get_template(), including templates rendered with the render tag.

from liquid import Environment

env = Environment(globals={"site_name": "MySite"})

template = env.from_string("""\
<html>
<head>
    <title>{{ site_name }}</title>
</head>
</html>
""")

print(template.render())
output
<html>
<head>
    <title>MySite</title>
</head>
</html>

Template Globals​

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

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

from liquid import Environment

env = Environment(globals={"site_name": "MySite"})

source = """\
    <html>
    <head>
        <title>{{ site_name }} - {{ page.name }}</title>
    </head>
    </html>
"""

template = env.from_string(source, globals={"page": {"name": "Blog"}})
print(template.render())
output
<html>
<head>
    <title>MySite - Blog</title>
</head>
</html>

Render Arguments​

Keyword arguments passed to liquid.template.BoundTemplate.render() 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.

from liquid import Environment

env = Environment(globals={"site_name": "MySite"})

source = """\
    <html>
    <head>
        <title>{{ site_name }} - {{ page.name }}</title>
    </head>
    <body>
        <p>Hello, {{ user.name }}</p>
    </body>
    </html>
"""

template = env.from_string(source, globals={"page": {"name": "Blog"}})
print(template.render(user = {"name": "Sally"}))
output
<html>
<head>
    <title>MySite - 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 context namespace, taking priority over template globals, but not render() keyword arguments.