Basics
Mode of a template
liquidpy
supports 4 modes:
- standard
- try to be compatible with standard liquid template engine
- See: https://shopify.github.io/liquid/
- jekyll
- try to be compatible with jekyll liquid template engine
- See: https://jekyllrb.com/docs/liquid/
- shopify
- try to be compatible with shopify-extended liquid template engine
- See: https://shopify.dev/api/liquid
- wild
- With some wild features supported (i.e. executing python code inside the template)
- See: https://pwwang.github.io/liquidpy/wild
See also an introduction about liquid template engine variants:
By default, liquidpy
uses the standard
mode. But you can specify a mode using the mode
argument of Liquid
constructor or Liquid.from_env()
method.
You can changed the default by:
from liquid import defaults
defaults.MODE = 'wild'
Liquid
object.
Preset globals and filters
If you want to send a set of global variables and filters to the templates:
from liquid import Liquid, defaults
defaults.FROM_FILE = False
a = 1
b = 2
Liquid("{{a | plus: b}}", globals=globals()).render()
# '3'
Specify predefined filters:
import os
from liquid import Liquid, defaults
defaults.FROM_FILE = False
Liquid("{{'/a' | path_join: 'b'}}", filters={'path_join': os.path.join}).render()
# '/a/b'
Relationship with Jinja2/3
Most features here are implemented by jinja extensions. Some of them, however, are impossible to implement via extensions. So we monkey-patched jinja to be better compatible with liquid syntax.
Note
If you want jinja to work as its original way, remember to unpatch it before you parse and render your template:
from jinja2 import Template
from liquid import Liquid, patch_jinja, unpatch_jinja
liq_tpl = Liquid(...)
liq_tpl.render(...) # works
jinja_tpl = Template(...) # error may happen
jinja_tpl.render(...) # error may happen
unpatch_jinja() # restore jinja
jinja_tpl = Template(...) # works
jinja_tpl.render(...) # works
liq_tpl.render(...) # error may happen
patch_jinja() # patch jinja again
liq_tpl.render(...) # works
Most jinja features are supported unless the filters/tags are overriden. For example, the round()
filter acts differently then the one in jinja
.
We could say that the implementations of liquid
and its variants are super sets of them themselves, with some slight compatibility issues (See Compatilities
below.)
Whitespace control
The whitespace control behaves the same as it describes here:
Compatibilies
See the compatiblity issues for truthy/falsy, tags, and other aspects on pages:
- Standard: https://pwwang.github.com/liquidpy/standard
- Jekyll: https://pwwang.github.com/liquidpy/jekyll
- Shopify: https://pwwang.github.com/liquidpy/shopify
Wild mode
You can do arbitrary things with the wild mode, like executing python code and adding custom filters inside the template.
See details on:
*
modifier for {{
to keep initial indention along multiple lines
tpl = """\
if True:
{{* body }}
"""
body = """\
print('hello')
print('world')
"""
print(Liquid(tpl, from_file=False).render(body=body))
if True:
print('hello')
print('world')