Templates

    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 for more information.

    Unless customized, Jinja2 is configured by Flask as follows:

    • autoescaping is enabled for all templates ending in , .htm, .xml as well as .xhtml when using render_template().

    • autoescaping is enabled for all strings when using render_template_string().

    • Flask inserts a couple of global functions and helpers into the Jinja2 context, additionally to the values that are present by default.

    The following global variables are available within Jinja2 templates by default:

    config

    The current configuration object (flask.config)

    Changelog

    Changed in version 0.10: This is now always available, even in imported templates.

    New in version 0.6.

    request

    The current request object (). This variable is unavailable if the template was rendered without an active request context.

    The current session object (flask.session). This variable is unavailable if the template was rendered without an active request context.

    g

    The request-bound object for global variables (). This variable is unavailable if the template was rendered without an active request context.

    url_for()

    The function.

    get_flashed_messages()

    The function.

    The Jinja Context Behavior

    These variables are added to the context of variables, they are not global variables. The difference is that by default these will not show up in the context of imported templates. This is partially caused by performance considerations, partially to keep things explicit.

    What does this mean for you? If you have a macro you want to import, that needs to access the request object you have two possibilities:

    1. you explicitly pass the request to the macro as parameter, or the attribute of the request object you are interested in.

    2. you import the macro “with context”.

    Importing with context looks like this:

    Autoescaping is the concept of automatically escaping special characters for you. Special characters in the sense of HTML (or XML, and thus XHTML) are &, >, <, " as well as '. Because these characters carry specific meanings in documents on their own you have to replace them by so called “entities” if you want to use them for text. Not doing so would not only cause user frustration by the inability to use these characters in text, but can also lead to security problems. (see Cross-Site Scripting (XSS))

    There are three ways to accomplish that:

    • In the Python code, wrap the HTML string in a object before passing it to the template. This is in general the recommended way.

    • Inside the template, use the |safe filter to explicitly mark a string as safe HTML ({{ myvariable|safe }})

    • Temporarily disable the autoescape system altogether.

    To disable the autoescape system in templates, you can use the {% autoescape %} block:

    2.     <p>{{ will_not_be_escaped }}
    3. {% endautoescape %}

    Whenever you do this, please be very cautious about the variables you are using in this block.

    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 jinja_env of the application or use the decorator.

    The two following examples work the same and both reverse an object:

    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:

    1. {% for x in mylist | reverse %}
    2. {% endfor %}

    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:

    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):

    1. @app.context_processor
    2. def utility_processor():
    3.     def format_price(amount, currency="€"):
    4.     return dict(format_price=format_price)

    The context processor above makes the format_price function available to all templates:

    You could also build format_price as a template filter (see Registering Filters), but this demonstrates how to pass functions in a context processor.