Criando Filtros, Tags e inclusion_tag Personalizados no Django

O Django oferece uma variedade de filtros e tags integrados em sua linguagem de template. No entanto, você também pode estender essa funcionalidade criando seus próprios filtros, tags e inclusion_tags personalizados. Este artigo explains como implementar esses recursos personalizados.

Preparação Inicial

Para criar recursos personalizados, siga estes três passos fundamentais:

1. Crie uma pasta denominada obrigatoriamente templatetags dentro do seu aplicativo Django.
2. Dentro dessa pasta, crie um arquivo Python com o nome que preferir, por exemplo: ferramentas.py.
3. No início desse arquivo, adicione as seguintes duas linhas obrigatórias:

# ferramentas.py
from django import template
register = template.Library()

Com esses passos realizados, você poderá criar filtros, tags e inclusion_tags personalizados no arquivo ferramentas.py. Para utilizar esses recursos em outros arquivos como views.py, basta importar o módulo correspondente.

Implementação de Filtros, Tags e inclusion_tag Personalizados

Filtro Personalizado

# Criando um filtro personalizado
@register.filter(name='concatenar')
def juncao_strings(valor1, valor2):
    return str(valor1) + str(valor2)

No template, utilize:

{% load ferramentas %}
<p>{{ texto|concatenar:sufixo }}</p>

Tag Pesronalizada

As tags simples funcionam como funções que aceitam múltiplos parâmetros:

# Criando uma tag simples
@register.simple_tag(name='formatar_data')
def formatar(data, formato, idioma):
    return data.strftime(formato)

No template, utilize:

{% formatar data_atual "%d/%m/%Y" "pt-BR" %}

inclusion_tag Personalizado

O inclusion_tag é particularmente útil quando você precisa renderizar um fragmento de HTML dinamicamente e reutilizá-lo em múltiplas páginas:

# Criando um inclusion_tag
@register.inclusion_tag('menu_navegacao.html')
def gerar_menu(itens):
    contexto = {
        'opcoes': ['Item {}'.format(i) for i in range(itens)],
        'titulo': 'Menu Principal'
    }
    return contexto

Modelo menu_navegacao.html:

<nav>
    <h3>{{ titulo }}</h3>
     {% for opcao in opcoes %} - {{ opcao }}
 {% endfor %} 
</nav>

No template principle:

{% gerar_menu 8 %}

Quando Utilizar inclusion_tag

A recomendação é utilizar inclusion_tag quando você possui uma seção de HTML que precisa receber parâmetros para renderização dinâmica e essa seção é utilizada em várias páginas diferentes do aplicativo. Essa abordagem promove reutilização de código e manutenção facilitada.