jinja2-simple-tags 0.5.0

Base classes for quick-and-easy template tag development

jinja2-simple-tags

jinja2-simple-tags is a library that provides a simple way to create custom template tags in Jinja2 templates.

Compatibility

• python >= 3.6
• Jinja2 >= 2.10

Installation

pip install jinja2-simple-tags

Usage

To use jinja2-simple-tags, you need to create a subclass of one of the provided tag types and implement the render method.

StandaloneTag

StandaloneTag is a tag that doesn't require a closing tag. It can be used like this:

from datetime import datetime
from jinja2_simple_tags import StandaloneTag


class NowExtension(StandaloneTag):
    tags = {"now"}

    def render(self, format="%Y-%m-%d %H:%I:%S"):
        return datetime.now().strftime(format)

{% now %}               {# 2023-04-27 20:08:03 #}
{% now '%m/%d/%Y' %}    {# 04/27/2023 #}

Escaping

By default, the output of StandaloneTag will be escaped. To disable escaping, set the safe_output property of your tag to True:

from jinja2_simple_tags import StandaloneTag


class AlertExtension(StandaloneTag):
    safe_output = True
    tags = {"alert"}

    def render(self, message):
        return "<script>alert('{}')</script>".format(message)

You can also return a jinja2.Markup object from the render() method to explicitly mark the output as safe.

ContainerTag

ContainerTag is a tag that requires a closing tag and can contain arbitrary content. It can be used like this:

import hmac
from jinja2_simple_tags import ContainerTag


class HMACExtension(ContainerTag):
    tags = {"hmac"}

    def render(self, secret, digest="sha256", caller=None):
        content = str(caller()).encode()

        if isinstance(secret, str):
            secret = secret.encode()

        signing = hmac.new(secret, content, digestmod=digest)
        return signing.hexdigest()

{% hmac 'SECRET', digest='sha1' %}Hello world!{% endhmac %}

{# e29371e24dc99c5641681728855a92e26829e288 #}

Context

Current context can be accessed using self.context attribute of the tag class:

from jinja2_simple_tags import StandaloneTag


class UserNameExtension(StandaloneTag):
    tags = {"username"}

    def render(self):
        return self.context["user"].username

Assignment

In addition to returning the rendered value, ContainerTag and StandaloneTag also supports assigning the output to a variable in the context. This can be done using the as keyword:

{% now '%m/%d/%Y' as today %}    
...
{{ today }}         {# 04/27/2023 #}

{% hmac 'SECRET', digest='sha1' as signature %}Hello world!{% endhmac %}
...
{{ signature }}     {# e29371e24dc99c5641681728855a92e26829e288 #}