Customowe template tags w Django

Plusy i minusy - dobre praktyki

Podstawowe template tagi dostępne w Django to np. autoescape, który przeciwdziała traktowaniu wartości typu string jako elementów HTML, czy comment, który sprawia, że napisana część template'u jest ignorowana.  Mamy też takie funkcje jak lower, safe, if, for. Pierwsze co rzuca się w oczy to prostota tych funkcjonalności. I właśnie na to powinniśmy uważać. Zamysł template tagów zawiera w sobie prostotę działania - template nie powinien zawierać zbyt skomplikowanej logiki - za dostarczenie odpowiedniego kontekstu odpowiedzialny jest widok sam w sobie, template jest jedynie warstwą wizualną.

Po co nam customowe template tagi?

To akurat bardzo proste. Załóżmy że chcemy dokonać konkatenacji dwóch wartości w sposób, który będzie godny zaufania. Django posiada tag pod nazwą add, jednak używanie go w ten sposób jest ryzykowne, ponieważ framework NAJPIERW spróbuje potraktować wartości jako liczby (cast na int), a dopiero PÓŹNIEJ jako stringi. 

Deklaracja

Tagi definiujemy jako pythonowe funkcje z argumentami zależnymi od typu tagu. Rejestrujemy je odpowiednim dekoratorem zaimportowanym z Django, a następnie definiujemy co mają zwracać. Wszystko zachodzi w pliku o dowolnej nazwie zawartym w folderze templatetags naszej aplikacji. Generyczny przykład wygląda tak:

from django import template

register = template.Library()

@register.<typ tagu>(<...opcje>)
def <nazwa tagu>(<...argumenty>):
    <...operacje>
    return <zwracana wartosc>

Typy tagów

Mamy kilka typów tagów: filtry, simple tagi i inclusion tagi. Każdy z nich służy do czegoś innego.  Filtry służą do dokonywania operacji na wartościach, definiujemy je tak:

@register.filter
def example_filter(value):
	return f"{value} with filter applied"

Ten tag zwraca wartość z dopiskiem "with filter applied". Oczywiście tylko od nas zależy co taka funkcja zwróci. Wewnątrz template'u składnia będzie taka:

{% load <nazwa pliku z naszym tagiem> %}
{{ some_value|example_filter }}

Mamy też simple tag, który dokonuje operacji na wielu przekazanych wartościach i zwraca wynik, wygląda to tak:

@register.simple_tag(takes_context=<bool>)
def example_simple_tag(*args):
	return sum(args)

Opcja takes_context umożliwia przekazanie kontekstu template'u jako pierwszy argument. W tym przykładzie tag przyjmuje nieograniczoną ilość argumentów nienazwanych i zwraca ich sumę. Przykład użycia:

{% load <nazwa pliku z tagiem> %}
{% example_simple_tag 46 11 5 39 %}

Następnym typem tagu jest inclusion tag. Służy on do injectowania sub-template'ów z plików, przekazując im różne dane. Służy on do zbudowania struktury modułowej naszych widoków, aby uniknąć powtarzania kodu, w myśl zasady DRY.  Tworzymy go tak:

@register.inclusion_tag("<nazwa pliku>.html")
def example_inclusion_tag(data):
	return {
		"some_data": data
	}

W tym przypadku przyjmujemy jeden argument i przekazujemy go templateo'wi z podanego pliku w kontekście pod nazwą "some_data". Skutkiem tego w naszym template <nazwa pliku>.html jesteśmy w stanie dostać się do podanej wartości używając {{ some_data }}. Użycie tego tagu wygląda w ten sposób:

{% load <nazwa pliku z tagiem> %}
{% example_inclusion_tag data=5 %}

Podsumowanie

To są podstawy podstaw customowych template tagów w Django. Zawsze warto zajrzeć do dokumentacji frameworka aby uzyskać więcej informacji. Template tagi to świetne narzędzia, dające dużą wygodę developerom piszącym template'y.