dldevinc / jinja2-simple-tags

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 #}

InclusionTag

InclusionTag is a tag that can be used for including other templates. It allows you to specify a template name or implement the get_template_names() method for dynamic template selection. Here's an example:

from jinja2_simple_tags import InclusionTag

class IncludeHeader(InclusionTag):
    tags = {"include_header"}
    template_name = "header.html"

    def get_context(self, logo):
        return {
            "logo": logo
        }

{% include_header logo="/static/logo.png" %}

Context Inheritance

InclusionTag inherits the current context from the parent template, which allows you to access and use variables from the parent context within the included template. Any additional context variables returned by the get_context() method are merged with the inherited context.

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, StandaloneTag and InclusionTag 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 #}