Skip to main content

Flask Liquid

A Flask extension for Python Liquid.

Install

Install Flask Liquid using Pipenv:

$ pipenv install flask-liquid

Or pip:

$ python -m pip install -U flask-liquid

Getting Started

Flask Liquid provides render_template and render_template_string functions that behave much like the Flask equivalents of the same name. By default Flask Liquid will look for templates in app.template_folder. The same location Flask uses for Jinja templates.

app.py
from flask import Flask

from flask_liquid import Liquid
from flask_liquid import render_template

app = Flask(__name__)
liquid = Liquid(app)

@app.route("/hello/")
@app.route("/hello/<name>")
def index(name=None):
return render_template("index.html", name=name)

Set the LIQUID_TEMPLATE_FOLDER configuration value to change the Liquid template folder independently of app.template_folder.

app.py
app = Flask(__name__)
app.config.update(
LIQUID_TEMPLATE_FOLDER="/path/to/liquid/templates/",
)

liquid = Liquid(app)

Factories and Blueprints

When using the factory pattern, use Liquid.init_app(app) instead. Any LIQUID_* configuration values stored on the app will override Liquid constructor arguments when init_app is called.

app.py
from flask import Flask
from flask_liquid import Liquid

from yourapp.blueprints import some_blueprint

liquid = Liquid()

def create_app(config=None):
app = Flask(__name__)
app.register_blueprint(some_blueprint.bp)

liquid.init_app(app)

return app

Mixing Jinja and Liquid

If you want to use Jinja and Liquid templates side by side, import Liquid render functions using an alias.

from flask import render_template
from flask_liquid import render_template as render_liquid_template

Auto Escape

Unlike a standard liquid.Environment(), Flask Liquid enables HTML auto-escaping by default. You can disable auto-escaping by passing autoescape=False to flask_liquid.Liquid() or setting the LIQUID_AUTOESCAPE configuration value to False.

To render markup from a Liquid snippet inside a Jinja template (or vice versa), mark the string returned by render_liquid_template as safe using Markup, then include it in the Jinja template context. That is assuming you trust values in the Liquid render context or have HTML escaped them already.

app.py
from flask import Flask
from flask import Markup
from flask import render_template

from flask_liquid import Liquid
from flask_liquid import render_template as render_liquid_template

app = Flask(__name__)
liquid = Liquid(app)

@app.route("/hello")
def hello():
user_content = render_liquid_template("content.liquid")
return render_template("page.html", content=Markup(user_content))

Flask Standard Context

Flask has some standard context variables that are included in each Jinja template context automatically. Flask Liquid does not include these variables. If you need access to the Flask session or request, for example, you'll need to manually map session or request properties to Liquid context keys.

app.py
from flask import Flask
from flask import request

from flask_liquid import Liquid
from flask_liquid import render_template

app = Flask(__name__)
liquid = Liquid(app)

@app.route("/hello/")
@app.route("/hello/<name>")
def index(name=None):
return render_template("index.html", name=name, path=request.path)

Context Processors

When the LIQUID_FLASK_CONTEXT_PROCESSORS configuration value is set to True, Flask context processors will update Liquid template contexts too.

info

Remember that Python Liquid uses the Sequence and Mapping interfaces for resolving object properties. See Objects and Drops.

app.py
from flask import Flask
from flask import request

from flask_liquid import Liquid
from flask_liquid import render_template

app = Flask(__name__)
app.config.update(
LIQUID_FLASK_CONTEXT_PROCESSORS=True,
)

liquid = Liquid(app)

@app.context_processor
def extra_context():
return {"request_path": request.path}

@app.route("/hello/")
@app.route("/hello/<name>")
def index(name=None):
return render_template("index.html", name=name)

Signals

By default, when signals are available, Flask Liquid will send a before_render_template and template_rendered signal for each successful call to render_template and render_template_string.

You can disable these signals for Liquid templates by setting the LIQUID_FLASK_SIGNALS configuration value to False.

Async Support

Render templates asynchronously using flask_liquid.render_template_async() and flask_liquid.render_template_string_async().

app.py
from flask import Flask

from flask_liquid import Liquid
from flask_liquid import render_template_async

app = Flask(__name__)
liquid = Liquid(app)

@app.route("/render/<name>")
async def render_by_name(name=None):
return await render_template_async(name)

Configuration Values

The following configuration values can be used instead of passing arguments to flask_liquid.Liquid().

Configuration ValueLiquid ArgumentDefault
LIQUID_TAG_START_STRINGtag_start_string"{%"
LIQUID_TAG_END_STRINGtag_end_string"%}"
LIQUID_STATEMENT_START_STRINGstatement_start_string"{{"
LIQUID_STATEMENT_END_STRINGstatement_end_string"}}"
LIQUID_TEMPLATE_COMMENTStemplate_commentsFalse
LIQUID_COMMENT_START_STRINGstatement_start_string"{#"
LIQUID_COMMENT_END_STRINGstatement_end_string"#}"
LIQUID_TOLERANCEmodeliquid.Mode.STRICT
LIQUID_UNDEFINEDundefinedliquid.Undefined
LIQUID_STRICT_FILTERSstrict_filtersTrue
LIQUID_TEMPLATE_FOLDERapp.template_folder
loaderFileSystemLoader(app.template_folder)
LIQUID_AUTOESCAPEautoescapeTrue
LIQUID_AUTO_RELOADauto_reloadTrue
LIQUID_EXPRESSION_CACHE_SIZEexpression_cache_size0
LIQUID_FLASK_CONTEXT_PROCESSORSflask_context_processorsFalse
LIQUID_FLASK_SIGNALSflask_signalsTrue

Note that if you specify a loader with the loader argument to flask_liquid.Liquid(), Flask Liquid will use that instead of creating a FileSystemLoader pointing to LIQUID_TEMPLATE_FOLDER.