Templates
=========
Flask leverages Jinja2 as its template engine. You are obviously free to use
a different template engine, but you still have to install Jinja2 to run
Flask itself. This requirement is necessary to enable rich extensions.
An extension can depend on Jinja2 being present.
This section only gives a very quick introduction into how Jinja2
is integrated into Flask. If you want information on the template
engine's syntax itself, head over to the official `Jinja2 Template
Documentation
autoescaping is disabled here
{{ will_not_be_escaped }} {% endautoescape %} Whenever you do this, please be very cautious about the variables you are using in this block. .. _registering-filters: Registering Filters ------------------- If you want to register your own filters in Jinja2 you have two ways to do that. You can either put them by hand into the :attr:`~flask.Flask.jinja_env` of the application or use the :meth:`~flask.Flask.template_filter` decorator. The two following examples work the same and both reverse an object:: @app.template_filter('reverse') def reverse_filter(s): return s[::-1] def reverse_filter(s): return s[::-1] app.jinja_env.filters['reverse'] = reverse_filter In case of the decorator the argument is optional if you want to use the function name as name of the filter. Once registered, you can use the filter in your templates in the same way as Jinja2's builtin filters, for example if you have a Python list in context called `mylist`:: {% for x in mylist | reverse %} {% endfor %} Context Processors ------------------ To inject new variables automatically into the context of a template, context processors exist in Flask. Context processors run before the template is rendered and have the ability to inject new values into the template context. A context processor is a function that returns a dictionary. The keys and values of this dictionary are then merged with the template context, for all templates in the app:: @app.context_processor def inject_user(): return dict(user=g.user) The context processor above makes a variable called `user` available in the template with the value of `g.user`. This example is not very interesting because `g` is available in templates anyways, but it gives an idea how this works. Variables are not limited to values; a context processor can also make functions available to templates (since Python allows passing around functions):: @app.context_processor def utility_processor(): def format_price(amount, currency="€"): return f"{amount:.2f}{currency}" return dict(format_price=format_price) The context processor above makes the `format_price` function available to all templates:: {{ format_price(0.33) }} You could also build `format_price` as a template filter (see :ref:`registering-filters`), but this demonstrates how to pass functions in a context processor. Streaming --------- It can be useful to not render the whole template as one complete string, instead render it as a stream, yielding smaller incremental strings. This can be used for streaming HTML in chunks to speed up initial page load, or to save memory when rendering a very large template. The Jinja2 template engine supports rendering a template piece by piece, returning an iterator of strings. Flask provides the :func:`~flask.stream_template` and :func:`~flask.stream_template_string` functions to make this easier to use. .. code-block:: python from flask import stream_template @app.get("/timeline") def timeline(): return stream_template("timeline.html") These functions automatically apply the :func:`~flask.stream_with_context` wrapper if a request is active, so that it remains available in the template.