{"title":"Så här skapar du anpassade malltaggar och filter","version":"5.2","locale":"sv","docname":"howto/custom-template-tags","url":"/sv/5.2/howto/custom-template-tags/","canonical":"https://djangodocs.dev/sv/5.2/howto/custom-template-tags/","summary":"Djangos mallspråk levereras med ett brett utbud av inbyggda taggar och filter som är utformade för att tillgodose presentationslogikbehoven i din applikation. Ändå…","html":"

Så här skapar du anpassade malltaggar och filterLink to this heading#

\n

Djangos mallspråk levereras med ett brett utbud av inbyggda taggar och filter som är utformade för att tillgodose presentationslogikbehoven i din applikation. Ändå kan det hända att du behöver funktionalitet som inte täcks av kärnuppsättningen av mallprimitiver. Du kan utöka mallmotorn genom att definiera anpassade taggar och filter med Python och sedan göra dem tillgängliga för dina mallar med hjälp av taggen {% load %}.

\n
\n

Layout för kodLink to this heading#

\n

Den vanligaste platsen för att ange anpassade malltaggar och filter är inuti en Django-app. Om de relaterar till en befintlig app är det vettigt att samla dem där; annars kan de läggas till i en ny app. När en Django-app läggs till i INSTALLED_APPS, görs alla taggar som den definierar på den konventionella plats som beskrivs nedan automatiskt tillgängliga för laddning i mallar.

\n

Appen bör innehålla en katalog med namnet templatetags, på samma nivå som models.py, views.py osv. Om den inte redan finns, skapa den - glöm inte filen __init__.py för att se till att katalogen behandlas som ett Python-paket.

\n\n

Dina anpassade taggar och filter kommer att finnas i en modul i katalogen templatetags. Namnet på modulfilen är det namn som du använder för att ladda taggarna senare, så var noga med att välja ett namn som inte krockar med anpassade taggar och filter i en annan app.

\n

Om dina anpassade taggar/filter till exempel finns i en fil som heter poll_extras.py, kan din applayout se ut så här:

\n
Text
polls/\n    __init__.py\n    models.py\n    templatetags/\n        __init__.py\n        poll_extras.py\n    views.py\n
\n

Och i din mall skulle du använda följande:

\n
Django template
{% load poll_extras %}\n
\n

Appen som innehåller de anpassade taggarna måste finnas i INSTALLED_APPS för att taggen {% load %} ska fungera. Detta är en säkerhetsfunktion: Det gör att du kan vara värd för Python-kod för många mallbibliotek på en enda värdmaskin utan att aktivera åtkomst till dem alla för varje Django-installation.

\n

Det finns ingen gräns för hur många moduler du lägger in i paketet templatetags. Tänk bara på att en {% load %}-sats kommer att ladda taggar/filter för det angivna Python-modulnamnet, inte namnet på appen.

\n

För att vara ett giltigt taggbibliotek måste modulen innehålla en variabel på modulnivå som heter register som är en template.Library-instans, där alla taggar och filter registreras. Så, nära toppen av din modul, lägg till följande:

\n
Code
from django import template\n\nregister = template.Library()\n
\n

Alternativt kan malltaggmoduler registreras via argumentet 'libraries' till DjangoTemplates. Detta är användbart om du vill använda en annan etikett än namnet på template-taggmodulen när du laddar template-taggar. Det gör det också möjligt för dig att registrera taggar utan att installera en applikation.

\n\n
\n
\n

Skriva anpassade mallfilterLink to this heading#

\n

Anpassade filter är Python-funktioner som tar ett eller två argument:

\n\n

I filtret {{ var|foo:"bar" }} får till exempel filtret foo variabeln var och argumentet "bar".

\n

Eftersom mallspråket inte tillhandahåller undantagshantering kommer alla undantag som skapas av ett mallfilter att exponeras som ett serverfel. Därför bör filterfunktioner undvika att skapa undantag om det finns ett rimligt fallback-värde att returnera. När det gäller indata som representerar en tydlig bugg i en mall kan det fortfarande vara bättre att skapa ett undantag än ett tyst misslyckande som döljer buggen.

\n

Här är ett exempel på en filterdefinition:

\n
Code
def cut(value, arg):\n    """Removes all values of arg from the given string"""\n    return value.replace(arg, "")\n
\n

Och här är ett exempel på hur det filtret skulle kunna användas:

\n
Django template
{{ somevariable|cut:"0" }}\n
\n

De flesta filter tar inte emot argument. I detta fall, lämna argumentet utanför din funktion:

\n
Code
def lower(value):  # Only one argument.\n    """Converts a string into all lowercase"""\n    return value.lower()\n
\n
\n

Registrering av anpassade filterLink to this heading#

\n
\n
\ndjango.template.Library.filter()Link to this definition#
\n
\n\n

När du har skrivit din filterdefinition måste du registrera den med din Library-instans för att göra den tillgänglig för Djangos mallspråk:

\n
Code
register.filter("cut", cut)\nregister.filter("lower", lower)\n
\n

Metoden Library.filter() tar två argument:

\n
    \n

  1. Filtrets namn - en sträng.

    2. \n

  2. Kompileringsfunktionen – en Python-funktion (inte namnet på funktionen som en sträng).

    3. \n
\n

Du kan använda register.filter() som en dekorator istället:

\n
Code
@register.filter(name="cut")\ndef cut(value, arg):\n    return value.replace(arg, "")\n\n\n@register.filter\ndef lower(value):\n    return value.lower()\n
\n

Om du utelämnar argumentet name, som i det andra exemplet ovan, kommer Django att använda funktionens namn som filternamn.

\n

Slutligen accepterar register.filter() också tre nyckelordsargument, is_safe, needs_autoescape och expects_localtime. Dessa argument beskrivs i filter och auto-escaping och filter och tidszoner nedan.

\n
\n
\n

Mallfilter som förväntar sig strängarLink to this heading#

\n
\n
\ndjango.template.defaultfilters.stringfilter()Link to this definition#
\n
\n\n

Om du skriver ett mallfilter som bara förväntar sig en sträng som första argument, bör du använda dekoratorn stringfilter. Detta kommer att konvertera ett objekt till dess strängvärde innan det skickas till din funktion:

\n
Code
from django import template\nfrom django.template.defaultfilters import stringfilter\n\nregister = template.Library()\n\n\n@register.filter\n@stringfilter\ndef lower(value):\n    return value.lower()\n
\n

På så sätt kan du skicka t.ex. ett heltal till detta filter utan att det orsakar ett AttributeError (eftersom heltal inte har lower()-metoder).

\n
\n
\n

Filter och automatisk särskrivningLink to this heading#

\n

När du skriver ett anpassat filter, tänk på hur filtret kommer att interagera med Djangos auto-escaping-beteende. Observera att två typer av strängar kan skickas runt inuti mallkoden:

\n\n

Mallfilterkod faller i en av två situationer:

\n
    \n

  1. Ditt filter introducerar inte några HTML-osäkra tecken (<, >, ', " eller &) i resultatet som inte redan fanns. I det här fallet kan du låta Django ta hand om all hantering av automatisk eskapning åt dig. Allt du behöver göra är att ställa in flaggan is_safe till True när du registrerar din filterfunktion, så här:

    \n
    Code
    @register.filter(is_safe=True)\ndef myfilter(value):\n    return value\n
    \n

    Denna flagga talar om för Django att om en ”säker” sträng skickas in i ditt filter, kommer resultatet fortfarande att vara ”säkert” och om en icke-säker sträng skickas in, kommer Django automatiskt att undkomma den, om det behövs.

    \n

    Du kan tänka dig att detta betyder ”det här filtret är säkert - det introducerar inte någon möjlighet till osäker HTML”

    \n

    Anledningen till att is_safe är nödvändig är att det finns gott om normala strängoperationer som kommer att göra ett SafeData-objekt tillbaka till ett normalt str-objekt och i stället för att försöka fånga dem alla, vilket skulle vara mycket svårt, reparerar Django skadan efter att filtret har slutförts.

    \n

    Anta till exempel att du har ett filter som lägger till strängen xx i slutet av alla inmatningar. Eftersom detta inte tillför några farliga HTML-tecken till resultatet (förutom de som redan fanns där), bör du markera ditt filter med is_safe:

    \n
    Code
    @register.filter(is_safe=True)\ndef add_xx(value):\n    return "%sxx" % value\n
    \n

    När detta filter används i en mall där automatisk escaping är aktiverad, kommer Django att escapa utdata när indata inte redan är markerad som ”säker”.

    \n

    Som standard är is_safe False, och du kan utelämna det från alla filter där det inte krävs.

    \n

    Var försiktig när du avgör om ditt filter verkligen lämnar säkra strängar som säkra. Om du tar bort tecken kan du oavsiktligt lämna obalanserade HTML-taggar eller enheter i resultatet. Om du till exempel tar bort en > från indata kan <a> bli <a, som måste escapas i utdata för att inte orsaka problem. På samma sätt kan borttagning av ett semikolon (;) förvandla &amp; till &amp;amp, som inte längre är en giltig enhet och därför behöver ytterligare escaping. De flesta fall kommer inte att vara så här knepiga, men håll utkik efter sådana problem när du granskar din kod.

    \n

    Om du markerar ett filter med is_safe kommer filtrets returvärde att tvingas till en sträng. Om ditt filter ska returnera ett booleskt värde eller ett annat värde som inte är en sträng, kommer markeringen is_safe förmodligen att få oavsiktliga konsekvenser (t.ex. konvertering av ett booleskt värde False till strängen ’False’).

    \n
    2. \n

  2. Alternativt kan din filterkod manuellt ta hand om all nödvändig escaping. Detta är nödvändigt när du introducerar ny HTML-markup i resultatet. Du vill markera utdata som säker från ytterligare escaping så att din HTML-markering inte escapas ytterligare, så du måste hantera inmatningen själv.

    \n

    För att markera utdata som en säker sträng, använd django.utils.safestring.mark_safe().

    \n

    Var dock försiktig. Du behöver göra mer än att bara markera utdata som säker. Du måste se till att det verkligen är säkert, och vad du gör beror på om auto-escaping är i kraft. Tanken är att skriva filter som kan fungera i mallar där auto-escaping är antingen på eller av för att göra saker enklare för dina mallförfattare.

    \n

    För att ditt filter ska känna till det aktuella auto-escaping-läget ska du ställa in flaggan needs_autoescape till True när du registrerar din filterfunktion. (Om du inte anger den här flaggan är standardvärdet False). Denna flagga talar om för Django att din filterfunktion vill få ett extra nyckelordsargument, kallat autoescape, som är True om auto-escaping är i kraft och False annars. Det rekommenderas att ställa in standardvärdet för parametern autoescape till True, så att om du anropar funktionen från Python-kod kommer den att ha escaping aktiverad som standard.

    \n

    Låt oss t.ex. skriva ett filter som betonar det första tecknet i en sträng:

    \n
    Code
    from django import template\nfrom django.utils.html import conditional_escape\nfrom django.utils.safestring import mark_safe\n\nregister = template.Library()\n\n\n@register.filter(needs_autoescape=True)\ndef initial_letter_filter(text, autoescape=True):\n    first, other = text[0], text[1:]\n    if autoescape:\n        esc = conditional_escape\n    else:\n        esc = lambda x: x\n    result = "<strong>%s</strong>%s" % (esc(first), esc(other))\n    return mark_safe(result)\n
    \n

    Flaggan needs_autoescape och nyckelordsargumentet autoescape innebär att vår funktion kommer att veta om automatisk escaping är i kraft när filtret anropas. Vi använder autoescape för att avgöra om indata behöver skickas genom django.utils.html.conditional_escape eller inte. (I det senare fallet använder vi identitetsfunktionen som ”escape”-funktion.) Funktionen conditional_escape() är som escape() förutom att den bara escaper indata som inte är en SafeData-instans. Om en SafeData-instans skickas till conditional_escape() returneras data oförändrat.

    \n

    Slutligen, i exemplet ovan, kommer vi ihåg att markera resultatet som säkert så att vår HTML infogas direkt i mallen utan ytterligare escaping.

    \n

    Det finns ingen anledning att oroa sig för flaggan is_safe i det här fallet (även om det inte skulle skada något att inkludera den). När du manuellt hanterar auto-escaping-problemen och returnerar en säker sträng, kommer is_safe-flaggan inte att ändra någonting på något sätt.

    \n
    3. \n
\n\n
\n
\n

Filter och tidszonerLink to this heading#

\n

Om du skriver ett anpassat filter som fungerar på datetime-objekt, registrerar du det vanligtvis med flaggan expects_localtime inställd på True:

\n
Code
@register.filter(expects_localtime=True)\ndef businesshours(value):\n    try:\n        return 9 <= value.hour < 17\n    except AttributeError:\n        return ""\n
\n

När denna flagga är inställd, om det första argumentet till ditt filter är en tidszonmedveten datatid, kommer Django att konvertera den till den aktuella tidszonen innan den skickas till ditt filter när det är lämpligt, enligt regler för tidszonkonverteringar i mallar.

\n
\n
\n
\n

Skriva anpassade malltaggarLink to this heading#

\n

Taggar är mer komplexa än filter, eftersom taggar kan göra vad som helst. Django tillhandahåller ett antal genvägar som gör det enklare att skriva de flesta typer av taggar. Först ska vi utforska dessa genvägar och sedan förklara hur man skriver en tagg från grunden för de fall då genvägarna inte är tillräckligt kraftfulla.

\n
\n

Enkla taggarLink to this heading#

\n
\n
\ndjango.template.Library.simple_tag()Link to this definition#
\n
\n\n

Många malltaggar tar emot ett antal argument - strängar eller mallvariabler - och returnerar ett resultat efter att ha gjort en viss bearbetning baserad enbart på inmatningsargumenten och viss extern information. Till exempel kan en current_time-tagg acceptera en formatsträng och returnera tiden som en sträng formaterad i enlighet med detta.

\n

För att underlätta skapandet av dessa typer av taggar tillhandahåller Django en hjälpfunktion, simple_tag. Denna funktion, som är en metod för django.template.Library, tar en funktion som accepterar valfritt antal argument, sveper in den i en render-funktion och de andra nödvändiga bitarna som nämns ovan och registrerar den med mallsystemet.

\n

Vår funktion current_time kan alltså skrivas så här:

\n
Code
import datetime\nfrom django import template\n\nregister = template.Library()\n\n\n@register.simple_tag\ndef current_time(format_string):\n    return datetime.datetime.now().strftime(format_string)\n
\n

Några saker att notera om hjälpfunktionen simple_tag:

\n\n

Till skillnad från andra taggverktyg skickar simple_tag sin utdata genom conditional_escape() om mallkontexten är i autoescape-läge, för att säkerställa korrekt HTML och skydda dig från XSS-sårbarheter.

\n

Om ytterligare escaping inte är önskvärt måste du använda mark_safe() om du är helt säker på att din kod inte innehåller XSS-sårbarheter. För att bygga små HTML-snuttar rekommenderas starkt att använda format_html() istället för mark_safe().

\n

Om din malltagg behöver komma åt den aktuella kontexten kan du använda argumentet takes_context när du registrerar din tagg:

\n
Code
@register.simple_tag(takes_context=True)\ndef current_time(context, format_string):\n    timezone = context["timezone"]\n    return your_get_current_time_method(timezone, format_string)\n
\n

Observera att det första argumentet måste heta context.

\n

För mer information om hur alternativet takes_context fungerar, se avsnittet om inclusion tags.

\n

Om du behöver byta namn på din tagg kan du ange ett eget namn för den:

\n
Code
register.simple_tag(lambda x: x - 1, name="minusone")\n\n\n@register.simple_tag(name="minustwo")\ndef some_function(value):\n    return value - 2\n
\n

simple_tag-funktioner kan acceptera valfritt antal positionella eller nyckelordsargument. Till exempel:

\n
Code
@register.simple_tag\ndef my_tag(a, b, *args, **kwargs):\n    warning = kwargs["warning"]\n    profile = kwargs["profile"]\n    ...\n    return ...\n
\n

I mallen kan sedan valfritt antal argument, åtskilda med mellanslag, skickas till malltaggen. Precis som i Python anges värdena för nyckelordsargument med hjälp av likhetstecknet (”=”) och måste anges efter de positionella argumenten. Till exempel:

\n
Django template
{% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %}\n
\n

Det är möjligt att lagra taggresultaten i en mallvariabel i stället för att skriva ut dem direkt. Detta görs genom att använda argumentet as följt av variabelnamnet. På så sätt kan du själv mata ut innehållet där du tycker att det passar:

\n
Django template
{% current_time "%Y-%m-%d %I:%M %p" as the_time %}\n<p>The time is {{ the_time }}.</p>\n
\n
\n
\n

Enkla block-taggarLink to this heading#

\n\n
\n
\ndjango.template.Library.simple_block_tag()Link to this definition#
\n
\n\n

När ett avsnitt av en renderad mall behöver skickas in i en anpassad tagg tillhandahåller Django hjälpfunktionen simple_block_tag för att åstadkomma detta. I likhet med simple_tag() accepterar den här funktionen en anpassad taggfunktion, men med det extra argumentet content, som innehåller det återgivna innehållet som definieras inuti taggen. Detta gör att dynamiska mallavsnitt enkelt kan införlivas i anpassade taggar.

\n

Till exempel kan en anpassad blocktagg som skapar ett diagram se ut så här:

\n
Code
from django import template\nfrom myapp.charts import render_chart\n\nregister = template.Library()\n\n\n@register.simple_block_tag\ndef chart(content):\n    return render_chart(source=content)\n
\n

Argumentet content innehåller allt mellan taggarna {% chart %} och {% endchart %}:

\n
Django template
{% chart %}\n  digraph G {\n      label = "Chart for {{ request.user }}"\n      A -> {B C}\n  }\n{% endchart %}\n
\n

Om det finns andra malltaggar eller variabler i content-blocket kommer de att renderas innan de skickas till taggfunktionen. I exemplet ovan kommer request.user att vara löst när render_chart anropas.

\n

Blocktaggar avslutas med end{name} (t.ex. endchart). Detta kan anpassas med parametern end_name:

\n
Code
@register.simple_block_tag(end_name="endofchart")\ndef chart(content):\n    return render_chart(source=content)\n
\n

Vilket skulle kräva en malldefinition som denna:

\n
Django template
{% chart %}\n  digraph G {\n      label = "Chart for {{ request.user }}"\n      A -> {B C}\n  }\n{% endofchart %}\n
\n

Några saker att notera om simple_block_tag:

\n\n

Precis som simple_tag, simple_block_tag:

\n\n\n
\n

Ett komplett exempelLink to this heading#

\n

Tänk dig en anpassad malltagg som genererar en meddelanderuta som stöder flera meddelandenivåer och innehåll utöver en enkel fras. Detta kan implementeras med hjälp av en simple_block_tag enligt följande:

\n
testapp/templatetags/testapptags.py
\n
Python
from django import template\nfrom django.utils.html import format_html\n\nregister = template.Library()\n\n\n@register.simple_block_tag(takes_context=True)\ndef msgbox(context, content, level):\n    format_kwargs = {\n        "level": level.lower(),\n        "level_title": level.capitalize(),\n        "content": content,\n        "open": " open" if level.lower() == "error" else "",\n        "site": context.get("site", "My Site"),\n    }\n    result = """\n    <div class="msgbox {level}">\n      <details{open}>\n        <summary>\n          <strong>{level_title}</strong>: Please read for <i>{site}</i>\n        </summary>\n        <p>\n          {content}\n        </p>\n      </details>\n    </div>\n    """\n    return format_html(result, **format_kwargs)\n
\n

I kombination med en minimal vy och motsvarande mall, som visas här:

\n
testapp/views.py
\n
Python
from django.shortcuts import render\n\n\ndef simpleblocktag_view(request):\n    return render(request, "test.html", context={"site": "Important Site"})\n
\n
testapp/templates/test.html testapp/templates/test.html
\n
Django template
{% extends "base.html" %}\n\n{% load testapptags %}\n\n{% block content %}\n\n  {% msgbox level="error" %}\n    Please fix all errors. Further documentation can be found at\n    <a href="http://example.com">Docs</a>.\n  {% endmsgbox %}\n\n  {% msgbox level="info" %}\n    More information at: <a href="http://othersite.com">Other Site</a>/\n  {% endmsgbox %}\n\n{% endblock %}\n
\n

Följande HTML visas som renderad utdata:

\n
Html
<div class="msgbox error">\n  <details open>\n    <summary>\n      <strong>Error</strong>: Please read for <i>Important Site</i>\n    </summary>\n    <p>\n      Please fix all errors. Further documentation can be found at\n      <a href="http://example.com">Docs</a>.\n    </p>\n  </details>\n</div>\n\n<div class="msgbox info">\n  <details>\n    <summary>\n      <strong>Info</strong>: Please read for <i>Important Site</i>\n    </summary>\n    <p>\n      More information at: <a href="http://othersite.com">Other Site</a>\n    </p>\n  </details>\n</div>\n
\n
\n
\n
\n

Taggar för inkluderingLink to this heading#

\n
\n
\ndjango.template.Library.inclusion_tag()Link to this definition#
\n
\n\n

En annan vanlig typ av malltagg är den typ som visar vissa data genom att rendera en annan mall. Till exempel använder Djangos admin-gränssnitt anpassade malltaggar för att visa knapparna längst ner på formulärsidorna för ”lägg till/ändra”. Dessa knappar ser alltid likadana ut, men länkmålen ändras beroende på vilket objekt som redigeras - så de är ett perfekt fall för att använda en liten mall som är fylld med detaljer från det aktuella objektet. (I administratörens fall är detta taggen submit_row)

\n

Den här typen av taggar kallas ”inclusion tags”.

\n

Att skriva inclusion-taggar demonstreras förmodligen bäst med ett exempel. Låt oss skriva en tagg som matar ut en lista med val för ett givet Poll-objekt, som skapades i tutorials. Vi kommer att använda taggen så här:

\n
Django template
{% show_results poll %}\n
\n

…och utdata blir ungefär så här:

\n
Html
<ul>\n  <li>First choice</li>\n  <li>Second choice</li>\n  <li>Third choice</li>\n</ul>\n
\n

Först definierar vi den funktion som tar argumentet och producerar en ordbok med data som resultat. Den viktiga punkten här är att vi bara behöver returnera en ordbok, inte något mer komplext. Detta kommer att användas som en mallkontext för mallfragmentet. Exempel:

\n
Code
def show_results(poll):\n    choices = poll.choice_set.all()\n    return {"choices": choices}\n
\n

Därefter skapar du den mall som används för att rendera taggens utdata. Denna mall är en fast egenskap hos taggen: taggskrivaren specificerar den, inte malldesignern. I vårt exempel är mallen mycket kort:

\n
Django template
<ul>\n{% for choice in choices %}\n    <li> {{ choice }} </li>\n{% endfor %}\n</ul>\n
\n

Nu skapar och registrerar du inclusion-taggen genom att anropa metoden inclusion_tag() på ett Library-objekt. Om vi följer vårt exempel och ovanstående mall finns i en fil som heter results.html i en katalog som malladdaren söker i, skulle vi registrera taggen så här:

\n
Code
# Here, register is a django.template.Library instance, as before\n@register.inclusion_tag("results.html")\ndef show_results(poll): ...\n
\n

Alternativt är det möjligt att registrera inkluderingstaggen med hjälp av en django.template.Template-instans:

\n
Code
from django.template.loader import get_template\n\nt = get_template("results.html")\nregister.inclusion_tag(t)(show_results)\n
\n

…när du först skapade funktionen.

\n

Ibland kan dina inkluderingstaggar kräva ett stort antal argument, vilket gör det till en smärta för mallförfattare att skicka in alla argument och komma ihåg deras ordning. För att lösa detta tillhandahåller Django ett takes_context-alternativ för inkluderingstaggar. Om du anger takes_context när du skapar en malltagg, kommer taggen inte att ha några nödvändiga argument, och den underliggande Python-funktionen kommer att ha ett argument - mallkontexten från och med när taggen anropades.

\n

Låt oss till exempel säga att du skriver en inclusion-tagg som alltid kommer att användas i ett sammanhang som innehåller variablerna home_link och home_title som pekar tillbaka till huvudsidan. Så här skulle Python-funktionen se ut:

\n
Code
@register.inclusion_tag("link.html", takes_context=True)\ndef jump_link(context):\n    return {\n        "link": context["home_link"],\n        "title": context["home_title"],\n    }\n
\n

Observera att den första parametern till funktionen måste heta context.

\n

I raden register.inclusion_tag() angav vi takes_context=True och namnet på mallen. Så här kan mallen link.html se ut:

\n
Django template
Jump directly to <a href="{{ link }}">{{ title }}</a>.\n
\n

När du sedan vill använda den anpassade taggen laddar du dess bibliotek och anropar den utan några argument, till exempel så här:

\n
Django template
{% jump_link %}\n
\n

Observera att när du använder takes_context=True behöver du inte skicka några argument till malltaggen. Den får automatiskt tillgång till kontexten.

\n

Parametern takes_context är som standard inställd på False. När den är inställd på True skickas taggen till kontextobjektet, som i det här exemplet. Det är den enda skillnaden mellan det här fallet och det tidigare exemplet med inclusion_tag.

\n

inclusion_tag-funktioner kan acceptera valfritt antal positionella argument eller nyckelord. Till exempel:

\n
Code
@register.inclusion_tag("my_template.html")\ndef my_tag(a, b, *args, **kwargs):\n    warning = kwargs["warning"]\n    profile = kwargs["profile"]\n    ...\n    return ...\n
\n

I mallen kan sedan valfritt antal argument, åtskilda med mellanslag, skickas till malltaggen. Precis som i Python anges värdena för nyckelordsargument med hjälp av likhetstecknet (”=”) och måste anges efter de positionella argumenten. Till exempel:

\n
Django template
{% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %}\n
\n
\n
\n

Avancerade anpassade malltaggarLink to this heading#

\n

Ibland räcker det inte med de grundläggande funktionerna för att skapa egna malltaggar. Oroa dig inte, Django ger dig fullständig tillgång till de interna funktioner som krävs för att bygga en malltagg från grunden.

\n
\n
\n

En snabb översiktLink to this heading#

\n

Mallsystemet fungerar i en tvåstegsprocess: kompilering och rendering. När du definierar en anpassad malltagg anger du hur kompileringen och renderingen ska gå till.

\n

När Django kompilerar en mall delar den upp den råa malltexten i ”noder”. Varje nod är en instans av django.template.Node och har en render() metod. En kompilerad mall är en lista med Node-objekt. När du anropar render() på ett kompilerat mallobjekt, anropar mallen render() på varje Node i dess nodlista, med det givna sammanhanget. Alla resultat sammankopplas för att bilda mallens utdata.

\n

För att definiera en anpassad malltagg anger du alltså hur den råa malltaggen konverteras till en Node (kompileringsfunktionen) och vad nodens render()-metod gör.

\n
\n
\n

Skriva sammanställningsfunktionenLink to this heading#

\n

För varje malltagg som mallparsern stöter på anropar den en Python-funktion med taggens innehåll och själva parserobjektet. Denna funktion är ansvarig för att returnera en Node-instans baserat på innehållet i taggen.

\n

Låt oss till exempel skriva en fullständig implementering av vår malltagg, {% current_time %}, som visar aktuellt datum/tid, formaterat enligt en parameter som anges i taggen, i strftime()-syntax. Det är en bra idé att bestämma taggens syntax före allt annat. I vårt fall kan vi säga att taggen ska användas så här:

\n
Django template
<p>The time is {% current_time "%Y-%m-%d %I:%M %p" %}.</p>\n
\n

Parsern för denna funktion ska ta parametern och skapa ett Node-objekt:

\n
Code
from django import template\n\n\ndef do_current_time(parser, token):\n    try:\n        # split_contents() knows not to split quoted strings.\n        tag_name, format_string = token.split_contents()\n    except ValueError:\n        raise template.TemplateSyntaxError(\n            "%r tag requires a single argument" % token.contents.split()[0]\n        )\n    if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")):\n        raise template.TemplateSyntaxError(\n            "%r tag's argument should be in quotes" % tag_name\n        )\n    return CurrentTimeNode(format_string[1:-1])\n
\n

Anteckningar:

\n\n
\n
\n

Skriva renderingsprogrammetLink to this heading#

\n

Det andra steget i att skriva egna taggar är att definiera en subklass av Node som har en render()-metod.

\n

Om vi fortsätter med exemplet ovan måste vi definiera CurrentTimeNode:

\n
Code
import datetime\nfrom django import template\n\n\nclass CurrentTimeNode(template.Node):\n    def __init__(self, format_string):\n        self.format_string = format_string\n\n    def render(self, context):\n        return datetime.datetime.now().strftime(self.format_string)\n
\n

Anteckningar:

\n\n

I slutändan resulterar denna frikoppling av kompilering och återgivning i ett effektivt mallsystem, eftersom en mall kan återge flera kontexter utan att behöva analyseras flera gånger.

\n
\n
\n

Överväganden om automatisk eskapningLink to this heading#

\n

Utdata från malltaggar körs inte automatiskt genom filtren för automatisk eskapning (med undantag för simple_tag() som beskrivs ovan). Det finns dock fortfarande ett par saker som du bör tänka på när du skriver en malltagg.

\n

Om render()-metoden i din malltagg lagrar resultatet i en kontextvariabel (i stället för att returnera resultatet i en sträng), bör den se till att anropa mark_safe() om så är lämpligt. När variabeln slutligen renderas kommer den att påverkas av den auto-escape-inställning som gäller vid den tidpunkten, så innehåll som bör vara säkert från ytterligare escaping måste markeras som sådant.

\n

Om din malltagg skapar en ny kontext för att utföra en underrendering, ska du också ställa in auto-escape-attributet till den aktuella kontextens värde. Metoden __init__ för klassen Context tar en parameter som heter autoescape som du kan använda för detta ändamål. Till exempel:

\n
Code
from django.template import Context\n\n\ndef render(self, context):\n    # ...\n    new_context = Context({"var": obj}, autoescape=context.autoescape)\n    # ... Do something with new_context ...\n
\n

Detta är inte en särskilt vanlig situation, men det är användbart om du renderar en mall själv. Till exempel:

\n
Code
def render(self, context):\n    t = context.template.engine.get_template("small_fragment.html")\n    return t.render(Context({"var": obj}, autoescape=context.autoescape))\n
\n

Om vi hade försummat att skicka in det aktuella värdet för context.autoescape till vår nya Context i det här exemplet skulle resultaten alltid ha escapats automatiskt, vilket kanske inte är det önskade beteendet om malltaggen används i ett {% autoescape off %}-block.

\n
\n
\n

Säkerhetsöverväganden för trådarLink to this heading#

\n

När en nod har parsats kan dess render-metod anropas ett obegränsat antal gånger. Eftersom Django ibland körs i flertrådade miljöer kan en enda nod samtidigt renderas med olika kontexter som svar på två separata förfrågningar. Därför är det viktigt att se till att dina malltaggar är trådsäkra.

\n

För att se till att dina malltaggar är trådsäkra bör du aldrig lagra tillståndsinformation på själva noden. Django tillhandahåller till exempel en inbyggd cycle malltagg som cyklar mellan en lista med givna strängar varje gång den återges:

\n
Django template
{% for o in some_list %}\n    <tr class="{% cycle 'row1' 'row2' %}">\n        ...\n    </tr>\n{% endfor %}\n
\n

En naiv implementation av CycleNode kan se ut ungefär så här:

\n
Code
import itertools\nfrom django import template\n\n\nclass CycleNode(template.Node):\n    def __init__(self, cyclevars):\n        self.cycle_iter = itertools.cycle(cyclevars)\n\n    def render(self, context):\n        return next(self.cycle_iter)\n
\n

Men anta att vi har två mallar som renderar mallutdraget från ovan samtidigt:

\n
    \n

  1. Tråd 1 utför sin första loopiteration, CycleNode.render() returnerar ’row1’

    2. \n

  2. Tråd 2 utför sin första loopiteration, CycleNode.render() returnerar ’row2’

    3. \n

  3. Tråd 1 utför sin andra loopiteration, CycleNode.render() returnerar ’row1’

    4. \n

  4. Tråd 2 utför sin andra loopiteration, CycleNode.render() returnerar ’row2’

    5. \n
\n

CycleNode itererar, men den itererar globalt. När det gäller tråd 1 och tråd 2 returnerar den alltid samma värde. Detta är inte vad vi vill!

\n

För att lösa detta problem tillhandahåller Django en render_context som är associerad med contexten för den mall som för närvarande renderas. render_context beter sig som en Python-dictionary och bör användas för att lagra Node-tillstånd mellan anrop av render-metoden.

\n

Låt oss omarbeta vår CycleNode-implementering för att använda render_context:

\n
Code
class CycleNode(template.Node):\n    def __init__(self, cyclevars):\n        self.cyclevars = cyclevars\n\n    def render(self, context):\n        if self not in context.render_context:\n            context.render_context[self] = itertools.cycle(self.cyclevars)\n        cycle_iter = context.render_context[self]\n        return next(cycle_iter)\n
\n

Observera att det är helt säkert att lagra global information som inte kommer att ändras under hela Node liv som ett attribut. I fallet med CycleNode, cyclevars argumentet ändras inte efter Node är instantiated, så vi behöver inte sätta det i render_context. Men tillståndsinformation som är specifik för den mall som för närvarande återges, som den aktuella iterationen av CycleNode, bör lagras i render_context.

\n\n
\n
\n

Registrering av taggenLink to this heading#

\n

Slutligen, registrera taggen med din moduls Library instans, som förklaras i skriva egna malltaggar ovan. Exempel:

\n
Code
register.tag("current_time", do_current_time)\n
\n

Metoden tag() tar två argument:

\n
    \n

  1. Namnet på malltaggen - en sträng. Om detta utelämnas kommer namnet på kompileringsfunktionen att användas.

    2. \n

  2. Kompileringsfunktionen – en Python-funktion (inte namnet på funktionen som en sträng).

    3. \n
\n

Precis som med filterregistrering är det också möjligt att använda detta som en dekorator:

\n
Code
@register.tag(name="current_time")\ndef do_current_time(parser, token): ...\n\n\n@register.tag\ndef shout(parser, token): ...\n
\n

Om du utelämnar argumentet name, som i det andra exemplet ovan, kommer Django att använda funktionens namn som taggnamn.

\n
\n
\n

Överföring av mallvariabler till taggenLink to this heading#

\n

Även om du kan skicka valfritt antal argument till en malltagg med hjälp av token.split_contents(), packas alla argument upp som stränglitteraler. Det krävs lite mer arbete för att skicka dynamiskt innehåll (en mallvariabel) till en malltagg som ett argument.

\n

Medan de tidigare exemplen har formaterat den aktuella tiden till en sträng och returnerat strängen, anta att du vill skicka in en DateTimeField från ett objekt och låta malltaggen formatera datumtiden:

\n
Django template
<p>This post was last updated at {% format_time blog_entry.date_updated "%Y-%m-%d %I:%M %p" %}.</p>\n
\n

Initialt kommer token.split_contents() att returnera tre värden:

\n
    \n

  1. Taggens namn format_time.

    2. \n

  2. Strängen 'blog_entry.date_updated' (utan omgivande citattecken).

    3. \n

  3. Formateringssträngen '"%Y-%m-%d %I:%M %p"'. Returvärdet från split_contents() kommer att inkludera inledande och avslutande citattecken för stränglitteraler som denna.

    4. \n
\n

Nu bör din tagg börja se ut så här:

\n
Code
from django import template\n\n\ndef do_format_time(parser, token):\n    try:\n        # split_contents() knows not to split quoted strings.\n        tag_name, date_to_be_formatted, format_string = token.split_contents()\n    except ValueError:\n        raise template.TemplateSyntaxError(\n            "%r tag requires exactly two arguments" % token.contents.split()[0]\n        )\n    if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")):\n        raise template.TemplateSyntaxError(\n            "%r tag's argument should be in quotes" % tag_name\n        )\n    return FormatTimeNode(date_to_be_formatted, format_string[1:-1])\n
\n

Du måste också ändra renderaren så att den hämtar det faktiska innehållet i egenskapen date_updated i objektet blog_entry. Detta kan åstadkommas genom att använda klassen Variable() i django.template.

\n

För att använda klassen Variable, instansiera den med namnet på den variabel som ska lösas och anropa sedan variable.resolve(context). Så här gör du till exempel:

\n
Code
class FormatTimeNode(template.Node):\n    def __init__(self, date_to_be_formatted, format_string):\n        self.date_to_be_formatted = template.Variable(date_to_be_formatted)\n        self.format_string = format_string\n\n    def render(self, context):\n        try:\n            actual_date = self.date_to_be_formatted.resolve(context)\n            return actual_date.strftime(self.format_string)\n        except template.VariableDoesNotExist:\n            return ""\n
\n

Variabelupplösning ger upphov till undantaget VariableDoesNotExist om den inte kan lösa upp den sträng som skickas till den i sidans aktuella kontext.

\n
\n
\n

Ställa in en variabel i kontextenLink to this heading#

\n

Exemplen ovan matar ut ett värde. I allmänhet är det mer flexibelt om dina malltaggar ställer in mallvariabler istället för att mata ut värden. På så sätt kan mallförfattare återanvända de värden som dina malltaggar skapar.

\n

Om du vill ställa in en variabel i kontexten använder du dictionary assignment på kontextobjektet i metoden render(). Här är en uppdaterad version av CurrentTimeNode som ställer in en mallvariabel current_time istället för att skriva ut den:

\n
Code
import datetime\nfrom django import template\n\n\nclass CurrentTimeNode2(template.Node):\n    def __init__(self, format_string):\n        self.format_string = format_string\n\n    def render(self, context):\n        context["current_time"] = datetime.datetime.now().strftime(self.format_string)\n        return ""\n
\n

Observera att render() returnerar en tom sträng. render() bör alltid returnera strängar. Om allt malltaggen gör är att ställa in en variabel, ska render() returnera den tomma strängen.

\n

Så här använder du den här nya versionen av taggen:

\n
Django template
{% current_time "%Y-%m-%d %I:%M %p" %}<p>The time is {{ current_time }}.</p>\n
\n\n

Men det finns ett problem med CurrentTimeNode2: Variabelnamnet current_time är hårdkodat. Detta innebär att du måste se till att din mall inte använder {{ current_time }} någon annanstans, eftersom {% current_time %} blint kommer att skriva över variabelns värde. En renare lösning är att låta malltaggen ange namnet på utdatavariabeln, så här:

\n
Django template
{% current_time "%Y-%m-%d %I:%M %p" as my_current_time %}\n<p>The current time is {{ my_current_time }}.</p>\n
\n

För att göra det måste du refaktorisera både kompileringsfunktionen och Node-klassen, så här:

\n
Code
import re\n\n\nclass CurrentTimeNode3(template.Node):\n    def __init__(self, format_string, var_name):\n        self.format_string = format_string\n        self.var_name = var_name\n\n    def render(self, context):\n        context[self.var_name] = datetime.datetime.now().strftime(self.format_string)\n        return ""\n\n\ndef do_current_time(parser, token):\n    # This version uses a regular expression to parse tag contents.\n    try:\n        # Splitting by None == splitting by spaces.\n        tag_name, arg = token.contents.split(None, 1)\n    except ValueError:\n        raise template.TemplateSyntaxError(\n            "%r tag requires arguments" % token.contents.split()[0]\n        )\n    m = re.search(r"(.*?) as (\\w+)", arg)\n    if not m:\n        raise template.TemplateSyntaxError("%r tag had invalid arguments" % tag_name)\n    format_string, var_name = m.groups()\n    if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")):\n        raise template.TemplateSyntaxError(\n            "%r tag's argument should be in quotes" % tag_name\n        )\n    return CurrentTimeNode3(format_string[1:-1], var_name)\n
\n

Skillnaden här är att do_current_time() hämtar formatsträngen och variabelnamnet och skickar båda till CurrentTimeNode3.

\n

Slutligen, om du bara behöver ha en enkel syntax för din anpassade kontextuppdaterande malltagg, kan du överväga att använda simple_tag()-genvägen, som stöder tilldelning av taggresultaten till en mallvariabel.

\n
\n
\n

Parsning tills en annan blocktaggLink to this heading#

\n

Malltaggar kan fungera tillsammans. Till exempel döljer standardtaggen {% comment %} allt fram till {% endcomment %}. För att skapa en malltagg som den här använder du parser.parse() i din kompileringsfunktion.

\n

Så här kan en förenklad {% comment %} tagg implementeras:

\n
Code
def do_comment(parser, token):\n    nodelist = parser.parse(("endcomment",))\n    parser.delete_first_token()\n    return CommentNode()\n\n\nclass CommentNode(template.Node):\n    def render(self, context):\n        return ""\n
\n\n

parser.parse() tar en tupel av namn på blocktaggar ’’att analysera fram till’’. Den returnerar en instans av django.template.NodeList, som är en lista över alla Node-objekt som parsern stötte på ’’innan’’ den stötte på någon av de taggar som anges i tupeln.

\n

I "nodelist = parser.parse(('endcomment',))" i exemplet ovan är nodelist en lista över alla noder mellan {% comment %} och {% endcomment %}, exklusive {% comment %} och {% endcomment %} själva.

\n

När parser.parse() har anropats har parsern ännu inte ”konsumerat” taggen {% endcomment %}, så koden måste uttryckligen anropa parser.delete_first_token().

\n

CommentNode.render() returnerar en tom sträng. Allt mellan {% comment %} och {% endcomment %} ignoreras.

\n
\n
\n

Parsning till en annan blocktagg och lagring av innehållLink to this heading#

\n

I det föregående exemplet kastade do_comment() bort allt mellan {% comment %} och {% endcomment %}. Istället för att göra det är det möjligt att göra något med koden mellan blocktaggar.

\n

Här är till exempel en anpassad malltagg, {% upper %}, som skriver allt mellan sig själv och {% endupper %} med stor bokstav.

\n

Användning:

\n
Django template
{% upper %}This will appear in uppercase, {{ your_name }}.{% endupper %}\n
\n

Precis som i det föregående exemplet använder vi parser.parse(). Men den här gången skickar vi den resulterande nodelist till Node:

\n
Code
def do_upper(parser, token):\n    nodelist = parser.parse(("endupper",))\n    parser.delete_first_token()\n    return UpperNode(nodelist)\n\n\nclass UpperNode(template.Node):\n    def __init__(self, nodelist):\n        self.nodelist = nodelist\n\n    def render(self, context):\n        output = self.nodelist.render(context)\n        return output.upper()\n
\n

Det enda nya konceptet här är self.nodelist.render(context) i UpperNode.render().

\n

För fler exempel på komplex rendering, se källkoden för {% for %} i django/template/defaulttags.py och {% if %} i django/template/smartif.py.

\n
\n
","rootId":"how-to-create-custom-template-tags-and-filters","toc":[{"title":"Layout för kod","anchor":"code-layout","children":[]},{"title":"Skriva anpassade mallfilter","anchor":"writing-custom-template-filters","children":[{"title":"Registrering av anpassade filter","anchor":"registering-custom-filters","children":[]},{"title":"Mallfilter som förväntar sig strängar","anchor":"template-filters-that-expect-strings","children":[]},{"title":"Filter och automatisk särskrivning","anchor":"filters-and-auto-escaping","children":[]},{"title":"Filter och tidszoner","anchor":"filters-and-time-zones","children":[]}]},{"title":"Skriva anpassade malltaggar","anchor":"writing-custom-template-tags","children":[{"title":"Enkla taggar","anchor":"simple-tags","children":[]},{"title":"Enkla block-taggar","anchor":"simple-block-tags","children":[{"title":"Ett komplett exempel","anchor":"a-complete-example","children":[]}]},{"title":"Taggar för inkludering","anchor":"inclusion-tags","children":[]},{"title":"Avancerade anpassade malltaggar","anchor":"advanced-custom-template-tags","children":[]},{"title":"En snabb översikt","anchor":"a-quick-overview","children":[]},{"title":"Skriva sammanställningsfunktionen","anchor":"writing-the-compilation-function","children":[]},{"title":"Skriva renderingsprogrammet","anchor":"writing-the-renderer","children":[]},{"title":"Överväganden om automatisk eskapning","anchor":"auto-escaping-considerations","children":[]},{"title":"Säkerhetsöverväganden för trådar","anchor":"thread-safety-considerations","children":[]},{"title":"Registrering av taggen","anchor":"registering-the-tag","children":[]},{"title":"Överföring av mallvariabler till taggen","anchor":"passing-template-variables-to-the-tag","children":[]},{"title":"Ställa in en variabel i kontexten","anchor":"setting-a-variable-in-the-context","children":[]},{"title":"Parsning tills en annan blocktagg","anchor":"parsing-until-another-block-tag","children":[]},{"title":"Parsning till en annan blocktagg och lagring av innehåll","anchor":"parsing-until-another-block-tag-and-saving-contents","children":[]}]}],"breadcrumbs":[{"docname":"howto/index","title":"Hur man gör-guider","url":"/sv/5.2/howto/"}],"prev":{"docname":"howto/custom-template-backend","title":"Hur man implementerar en anpassad mallbackend","url":"/sv/5.2/howto/custom-template-backend/"},"next":{"docname":"howto/static-files/index","title":"Hur man hanterar statiska filer (t.ex. bilder, JavaScript, CSS)","url":"/sv/5.2/howto/static-files/"},"formats":{"html":"/sv/5.2/howto/custom-template-tags/","markdown":"/sv/5.2/howto/custom-template-tags.md","json":"/sv/5.2/howto/custom-template-tags.json"},"source":"https://github.com/django/django/blob/stable/5.2.x/docs/howto/custom-template-tags.txt","official":"https://docs.djangoproject.com/sv/5.2/howto/custom-template-tags/","inVersions":["6.1","6.0","5.2"],"inLocales":["en","sv","zh-hans","ga","fr","ja","id","it","pt-br","ko","es","el","pl"]}