Detta dokument förklarar Djangos mallsystem ur ett tekniskt perspektiv - hur det fungerar och hur man utökar det. Om du letar efter en referens om språkets syntax, se Djangos mallspråk.
\nDet förutsätter en förståelse för mallar, kontexter, variabler, taggar och rendering. Börja med introduktion till Djangos mallspråk om du inte är bekant med dessa begrepp.
\nAtt använda mallsystemet i Python är en process i tre steg:
\nDu konfigurerar en Engine.
Du sammanställer mallkod till en Template.
Du renderar mallen med en Context.
Djangoprojekt förlitar sig i allmänhet på :ref: hög nivå, backend agnostiska API:er <template-engines> för vart och ett av dessa steg istället för mallsystemets API:er på lägre nivå:
\nFör varje DjangoTemplates backend i TEMPLATES inställningen, instansierar Django en Engine. DjangoTemplates omsluter Engine och anpassar den till det gemensamma mall backend API.
Modulen django.template.loader tillhandahåller funktioner som get_template() för att ladda mallar. De returnerar en django.template.backends.django.Template som omsluter den faktiska django.template.Template.
Den Template som erhölls i föregående steg har en render()-metod som samlar en kontext och eventuellt en begäran i en Context och delegerar renderingen till den underliggande Template.
Om du använder DjangoTemplates backend, är detta förmodligen inte den dokumentation du letar efter. En instans av klassen Engine som beskrivs nedan är tillgänglig med hjälp av attributet engine för den backend och alla attributstandarder som nämns nedan åsidosätts av det som skickas av DjangoTemplates.
Vid instansiering av en Engine måste alla argument skickas som nyckelordsargument:
dirs är en lista över kataloger där motorn ska leta efter mallkällfiler. Den används för att konfigurera filesystem.Loader.
Standardvärdet är en tom lista.
\napp_dirs påverkar endast standardvärdet för loaders. Se nedan.
Standardvärdet är False.
autoescape kontrollerar om HTML autoescaping är aktiverat.
Standardvärdet är True.
context_processors är en lista med prickade Python-sökvägar till anropsbara filer som används för att fylla i kontexten när en mall renderas med en begäran. Dessa callables tar ett request-objekt som sitt argument och returnerar en dict av objekt som ska sammanfogas i kontexten.
Standardvärdet är en tom lista.
\nSe RequestContext för mer information.
debug är en boolean som aktiverar/avaktiverar mallens felsökningsläge. Om det är True kommer mallmotorn att lagra ytterligare felsökningsinformation som kan användas för att visa en detaljerad rapport för alla undantag som uppstår under mallrenderingen.
Standardvärdet är False.
loaders är en lista över mallinläsningsklasser, specificerade som strängar. Varje Loader-klass vet hur man importerar mallar från en viss källa. Alternativt kan en tupel användas i stället för en sträng. Det första objektet i tupeln bör vara klassnamnet för Loader, efterföljande objekt skickas till Loader under initialiseringen.
Den innehåller som standard en lista:
\n'django.template.loaders.filesystem.Loader'
'django.template.loaders.app_directories.Loader' om och endast om app_dirs är True.
Dessa laddare är sedan inkapslade i django.template.loaders.cached.Loader.
Se Typer av lastare för mer information.
\nstring_if_invalid är utdata i form av en sträng som mallsystemet ska använda för ogiltiga (t.ex. felstavade) variabler.
Standardvärdet är den tomma strängen.
\nSe Hur ogiltiga variabler hanteras för mer information.
\nfile_charset är det teckensnitt som används för att läsa mallfiler på disken.
Standardvärdet är 'utf-8'.
'bibliotek': En ordbok med etiketter och prickade Python-sökvägar för malltaggmoduler som ska registreras med mallmotorn. Detta används för att lägga till nya bibliotek eller tillhandahålla alternativa etiketter för befintliga bibliotek. Till exempel:
Engine(\n libraries={\n "myapp_tags": "path.to.myapp.tags",\n "admin.urls": "django.contrib.admin.templatetags.admin_urls",\n },\n)\nBibliotek kan laddas genom att skicka motsvarande ordboksnyckel till taggen {% load %}.
'builtins': En lista med prickade Python-sökvägar för malltaggmoduler som ska läggas till i built-ins. Till exempel:
Engine(\n builtins=["myapp.builtins"],\n)\nTaggar och filter från inbyggda bibliotek kan användas utan att först anropa taggen {% load %}.
Returnerar den underliggande Engine från den första konfigurerade DjangoTemplates-motorn. Utlöser ImproperlyConfigured om inga motorer är konfigurerade.
Det krävs för att bevara API:er som förlitar sig på en globalt tillgänglig, implicit konfigurerad motor. All annan användning är starkt avrådd.
\nKompilerar den angivna mallkoden och returnerar ett Template-objekt.
Läser in en mall med det angivna namnet, kompilerar den och returnerar ett Template-objekt.
Som get_template(), förutom att den tar en lista med namn och returnerar den första mallen som hittades.
Det rekommenderade sättet att skapa en Template är att anropa fabriksmetoderna i Engine: get_template(), select_template() och from_string().
I ett Django-projekt där inställningen TEMPLATES definierar en DjangoTemplates-motor, är det möjligt att instansiera en Template direkt. Om mer än en DjangoTemplates-motor är definierad, kommer den första att användas.
Denna klass lever på django.template.Template. Konstruktören tar ett argument - den råa mallkoden:
from django.template import Template\n\ntemplate = Template("My name is {{ my_name }}.")\nNär du har ett kompilerat Template-objekt kan du rendera en kontext med det. Du kan återanvända samma mall för att rendera den flera gånger med olika kontexter.
Konstruktören för django.template.Context tar ett valfritt argument - en ordbok som mappar variabelnamn till variabelvärden.
Tre valfria nyckelordsargument kan också anges:
\nautoescape kontrollerar om HTML autoescaping är aktiverat.
Standardvärdet är True.
use_l10n åsidosätter om värden ska lokaliseras som standard. Om inställningen är True kommer siffror och datum att formateras baserat på lokal.
Standardvärdet är None.
Se Styrning av lokalisering i mallar för detaljer.
\nuse_tz åsidosätter om datum konverteras till lokal tid när de återges i en mall. Om inställningen är True kommer alla datum att återges med den lokala tidszonen. Detta har företräde framför USE_TZ.
Standardvärdet är None.
Se tidszoner-i-mallar för mer information.
\nFör exempel på användning, se Leka med Context-objekt nedan.
\nAnropa Template-objektets render()-metod med en Context för att ”fylla” mallen:
>>> from django.template import Context, Template\n>>> template = Template("My name is {{ my_name }}.")\n\n>>> context = Context({"my_name": "Adrian"})\n>>> template.render(context)\n"My name is Adrian."\n\n>>> context = Context({"my_name": "Dolores"})\n>>> template.render(context)\n"My name is Dolores."\nVariabelnamn får bestå av valfri bokstav (A-Z), valfri siffra (0-9), en understrykning (men de får inte börja med en understrykning) eller en punkt.
\nPrickar har en speciell betydelse i mallrendering. En punkt i ett variabelnamn betyder en uppslagning. När mallsystemet stöter på en punkt i ett variabelnamn försöker det med följande uppslagningar, i den här ordningen:
\nUppslagning i ordbok. Exempel: foo["bar"]
Uppslagning av attribut. Exempel: foo.bar
Uppslagning i listindex. Exempel: foo[bar]
Observera att ”bar” i ett malluttryck som {{ foo.bar }} kommer att tolkas som en bokstavlig sträng och inte som värdet på variabeln ”bar”, om en sådan finns i mallkontexten.
Mallsystemet använder den första uppslagstypen som fungerar. Det är kortslutningslogik. Här är några exempel:
\n>>> from django.template import Context, Template\n>>> t = Template("My name is {{ person.first_name }}.")\n>>> d = {"person": {"first_name": "Joe", "last_name": "Johnson"}}\n>>> t.render(Context(d))\n"My name is Joe."\n\n>>> class PersonClass:\n... pass\n...\n>>> p = PersonClass()\n>>> p.first_name = "Ron"\n>>> p.last_name = "Nasty"\n>>> t.render(Context({"person": p}))\n"My name is Ron."\n\n>>> t = Template("The first stooge in the list is {{ stooges.0 }}.")\n>>> c = Context({"stooges": ["Larry", "Curly", "Moe"]})\n>>> t.render(c)\n"The first stooge in the list is Larry."\nOm någon del av variabeln är anropsbar kommer mallsystemet att försöka anropa den. Exempel på detta:
\n>>> class PersonClass2:\n... def name(self):\n... return "Samantha"\n...\n>>> t = Template("My name is {{ person.name }}.")\n>>> t.render(Context({"person": PersonClass2}))\n"My name is Samantha."\nKallbara variabler är något mer komplexa än variabler som bara kräver direkta uppslagningar. Här är några saker att tänka på:
\nOm variabeln ger upphov till ett undantag när den anropas kommer undantaget att spridas, såvida inte undantaget har ett attribut silent_variable_failure vars värde är True. Om undantaget har ett attribut silent_variable_failure vars värde är True, kommer variabeln att återges som värdet av motorns konfigurationsalternativ string_if_invalid (en tom sträng som standard). Exempel på detta:
>>> t = Template("My name is {{ person.first_name }}.")\n>>> class PersonClass3:\n... def first_name(self):\n... raise AssertionError("foo")\n...\n>>> p = PersonClass3()\n>>> t.render(Context({"person": p}))\nTraceback (most recent call last):\n...\nAssertionError: foo\n\n>>> class SilentAssertionError(Exception):\n... silent_variable_failure = True\n...\n>>> class PersonClass4:\n... def first_name(self):\n... raise SilentAssertionError\n...\n>>> p = PersonClass4()\n>>> t.render(Context({"person": p}))\n"My name is ."\nObservera att django.core.exceptions.ObjectDoesNotExist, som är basklassen för alla Django databas API DoesNotExist undantag, har silent_variable_failure = True. Så om du använder Django-mallar med Django-modellobjekt, kommer alla DoesNotExist-undantag att misslyckas tyst.
En variabel kan bara anropas om den inte har några nödvändiga argument. I annat fall returnerar systemet värdet på motorns alternativ string_if_invalid.
Det kan finnas bieffekter när man anropar vissa variabler, och det skulle vara antingen dumt eller ett säkerhetshål att låta mallsystemet komma åt dem.
\nEtt bra exempel är delete()-metoden på varje Django-modellobjekt. Mallsystemet bör inte tillåtas att göra något liknande:
I will now delete this valuable data. {{ data.delete }}\nFör att förhindra detta ska du ange attributet alters_data för den anropbara variabeln. Mallsystemet kommer inte att anropa en variabel om den har alters_data=True inställd, och kommer istället att ersätta variabeln med string_if_invalid, ovillkorligen. De dynamiskt genererade delete() och save() metoderna på Django modellobjekt får alters_data=True automatiskt. Exempel:
def sensitive_function(self):\n self.database_record.delete()\n\n\nsensitive_function.alters_data = True\nIbland kanske du vill stänga av den här funktionen av andra skäl och tala om för mallsystemet att en variabel ska lämnas oanropad oavsett vad som händer. För att göra det, ställ in ett do_not_call_in_templates-attribut på den anropbara variabeln med värdet True. Mallsystemet kommer då att agera som om din variabel inte är anropsbar (så att du till exempel kan komma åt attribut för den anropsbara variabeln).
Om en variabel inte finns infogar mallsystemet i allmänhet värdet för motorns konfigurationsalternativ string_if_invalid, som är inställt på '' (den tomma strängen) som standard.
Filter som tillämpas på en ogiltig variabel tillämpas endast om string_if_invalid är inställd på '' (den tomma strängen). Om string_if_invalid är satt till något annat värde ignoreras variabelfiltren.
Detta beteende är något annorlunda för malltaggarna if, for och regroup. Om en ogiltig variabel anges i en av dessa malltaggar tolkas variabeln som None. Filter tillämpas alltid på ogiltiga variabler inom dessa malltaggar.
Om string_if_invalid innehåller en '%s' ersätts formatmarkören med namnet på den ogiltiga variabeln.
Varje kontext innehåller True, False och None. Som du kan förvänta dig löses dessa variabler upp till motsvarande Python-objekt.
Djangos mallspråk har inget sätt att undkomma de tecken som används för dess egen syntax. Till exempel: krävs taggen templatetag om du behöver skriva ut teckensekvenser som {% och %}.
Ett liknande problem finns om du vill inkludera dessa sekvenser i mallfilter eller taggargument. Till exempel:, när man analyserar en block-tagg, letar Djangos mallanalysator efter den första förekomsten av %} efter en {%. Detta förhindrar användningen av "%}" som en bokstavlig sträng. Till exempel: kommer ett TemplateSyntaxError att uppstå för följande uttryck:
{% include "template.html" tvar="Some string literal with %} in it." %}\n\n{% with tvar="Some string literal with %} in it." %}{% endwith %}\nSamma problem kan uppstå om man använder en reserverad sekvens i filterargument:
\n{{ some.variable|default:"}}" }}\nOm du behöver använda strängar med dessa sekvenser kan du lagra dem i mallvariabler eller använda en anpassad malltagg eller ett filter för att kringgå begränsningen.
\nContext-objektLink to this heading#För det mesta instansierar du Context-objekt genom att skicka in en fullständigt fylld ordbok till Context(). Men du kan också lägga till och ta bort objekt från ett Context-objekt när det har instantierats, med hjälp av standardordbokssyntax:
>>> from django.template import Context\n>>> c = Context({"foo": "bar"})\n>>> c["foo"]\n'bar'\n>>> del c["foo"]\n>>> c["foo"]\nTraceback (most recent call last):\n...\nKeyError: 'foo'\n>>> c["newvariable"] = "hello"\n>>> c["newvariable"]\n'hello'\nReturnerar värdet för key om key finns i kontexten, annars returneras annat.
Om key finns i kontexten returneras dess värde. Annars infogar key med värdet default och returnerar default.
Ett Context-objekt är en stack. Det vill säga, du kan push() och pop() det. Om du pop() för mycket, kommer det att ge upphov till django.template.ContextPopException:
>>> c = Context()\n>>> c["foo"] = "first level"\n>>> c.push()\n{}\n>>> c["foo"] = "second level"\n>>> c["foo"]\n'second level'\n>>> c.pop()\n{'foo': 'second level'}\n>>> c["foo"]\n'first level'\n>>> c["foo"] = "overwritten"\n>>> c["foo"]\n'overwritten'\n>>> c.pop()\nTraceback (most recent call last):\n...\nContextPopException\nDu kan också använda push() som en kontexthanterare för att säkerställa att en matchande pop() anropas.
>>> c = Context()\n>>> c["foo"] = "first level"\n>>> with c.push():\n... c["foo"] = "second level"\n... c["foo"]\n...\n'second level'\n>>> c["foo"]\n'first level'\nAlla argument som skickas till push() kommer att skickas till dict-konstruktören som används för att bygga den nya kontextnivån.
>>> c = Context()\n>>> c["foo"] = "first level"\n>>> with c.push(foo="second level"):\n... c["foo"]\n...\n'second level'\n>>> c["foo"]\n'first level'\nFörutom push() och pop() definierar objektet Context också en metod för update(). Denna fungerar som push() men tar en ordbok som argument och skjuter den ordboken på stacken istället för en tom.
>>> c = Context()\n>>> c["foo"] = "first level"\n>>> c.update({"foo": "updated"})\n{'foo': 'updated'}\n>>> c["foo"]\n'updated'\n>>> c.pop()\n{'foo': 'updated'}\n>>> c["foo"]\n'first level'\nPrecis som push() kan du använda update() som en kontexthanterare för att säkerställa att en matchande pop() anropas.
>>> c = Context()\n>>> c["foo"] = "first level"\n>>> with c.update({"foo": "second level"}):\n... c["foo"]\n...\n'second level'\n>>> c["foo"]\n'first level'\nAtt använda en Context som en stack är praktiskt i några anpassade malltaggar.
Med hjälp av metoden flatten() kan du få hela Context-stacken som en ordbok inklusive inbyggda variabler.
>>> c = Context()\n>>> c["foo"] = "first level"\n>>> c.update({"bar": "second level"})\n{'bar': 'second level'}\n>>> c.flatten()\n{'True': True, 'None': None, 'foo': 'first level', 'False': False, 'bar': 'second level'}\nEn flatten()-metod används också internt för att göra Context-objekt jämförbara.
>>> c1 = Context()\n>>> c1["foo"] = "first level"\n>>> c1["bar"] = "second level"\n>>> c2 = Context()\n>>> c2.update({"bar": "second level", "foo": "first level"})\n{'foo': 'first level', 'bar': 'second level'}\n>>> c1 == c2\nTrue\nResultatet från flatten() kan vara användbart i enhetstester för att jämföra Context mot dict:
class ContextTest(unittest.TestCase):\n def test_against_dictionary(self):\n c1 = Context()\n c1["update"] = "value"\n self.assertEqual(\n c1.flatten(),\n {\n "True": True,\n "None": None,\n "False": False,\n "update": "value",\n },\n )\nRequestContextLink to this heading#Django kommer med en speciell Context-klass, django.template.RequestContext, som fungerar något annorlunda än den normala django.template.Context. Den första skillnaden är att den tar en HttpRequest som sitt första argument. Till exempel:
c = RequestContext(\n request,\n {\n "foo": "bar",\n },\n)\nDen andra skillnaden är att den automatiskt fyller i kontexten med några variabler, enligt motorns konfigurationsalternativ context_processors.
Alternativet context_processors är en lista över anropbara objekt - kallade kontextprocessorer - som tar ett request-objekt som argument och returnerar en ordbok med objekt som ska sammanfogas i kontexten. I den standardgenererade inställningsfilen innehåller standardmallmotorn följande kontextprocessorer:
[\n "django.template.context_processors.request",\n "django.contrib.auth.context_processors.auth",\n "django.contrib.messages.context_processors.messages",\n]\nUtöver dessa aktiverar RequestContext alltid 'django.template.context_processors.csrf'. Detta är en säkerhetsrelaterad kontextprocessor som krävs av admin och andra contrib-appar, och i händelse av oavsiktlig felkonfiguration är den avsiktligt hårdkodad och kan inte stängas av i alternativet context_processors.
Varje processor tillämpas i tur och ordning. Det innebär att om en processor lägger till en variabel i sammanhanget och en andra processor lägger till en variabel med samma namn, kommer den andra processorn att åsidosätta den första. Standardprocessorerna förklaras nedan.
\n\nDu kan också ge RequestContext en lista över ytterligare processorer genom att använda det valfria, tredje positionsargumentet, processors. I detta exempel får RequestContext-instansen en ip_address-variabel:
from django.http import HttpResponse\nfrom django.template import RequestContext, Template\n\n\ndef ip_address_processor(request):\n return {"ip_address": request.META["REMOTE_ADDR"]}\n\n\ndef client_ip_view(request):\n template = Template("{{ title }}: {{ ip_address }}")\n context = RequestContext(\n request,\n {\n "title": "Your IP Address",\n },\n [ip_address_processor],\n )\n return HttpResponse(template.render(context))\nHär är vad var och en av de inbyggda processorerna gör:
\ndjango.contrib.auth.context_processors.authLink to this heading#Om denna processor är aktiverad kommer varje RequestContext att innehålla dessa variabler:
user – En auth.User-instans som representerar den användare som för närvarande är inloggad (eller en AnonymousUser-instans om klienten inte är inloggad).
perms – En instans av django.contrib.auth.context_processors.PermWrapper, som representerar de behörigheter som den för närvarande inloggade användaren har.
django.template.context_processors.debugLink to this heading#Om den här processorn är aktiverad kommer varje RequestContext att innehålla dessa två variabler - men bara om inställningen DEBUG` är satt till True och begärans IP-adress (request.META['REMOTE_ADDR']) finns i inställningen INTERNAL_IPS`:
debug – True. Du kan använda detta i mallar för att testa om du är i DEBUG-läge.
sql_queries – En lista med {'sql': ..., 'time': ...} dictionaries, som representerar varje SQL-fråga som har skett hittills under begäran och hur lång tid det tog. Listan är ordnad efter databasalias och sedan efter fråga. Den genereras lättsamt vid åtkomst.
django.template.context_processors.i18nLink to this heading#Om denna processor är aktiverad kommer varje RequestContext att innehålla dessa variabler:
LANGUAGES – Värdet på inställningen LANGUAGES.
LANGUAGE_BIDI – True om det aktuella språket är ett höger-till-vänster-språk, t.ex. hebreiska, arabiska. False om det är ett vänster till höger-språk, t.ex. engelska, franska, tyska.
LANGUAGE_CODE – request.LANGUAGE_CODE, om det finns. Annars värdet av inställningen LANGUAGE_CODE.
Se i18n malltaggar för malltaggar som genererar samma värden.
\ndjango.template.context_processors.mediaLink to this heading#Om denna processor är aktiverad kommer varje RequestContext att innehålla en variabel MEDIA_URL, som anger värdet på inställningen MEDIA_URL.
django.template.context_processors.staticLink to this heading#Om denna processor är aktiverad kommer varje RequestContext att innehålla en variabel STATIC_URL som anger värdet på inställningen STATIC_URL.
django.template.context_processors.csrfLink to this heading#Denna processor lägger till en token som behövs av malltaggen csrf_token för skydd mot Cross Site Request Forgeries.
django.template.context_processors.requestLink to this heading#Om denna processor är aktiverad kommer varje RequestContext att innehålla en variabel request, som är den aktuella HttpRequest.
django.template.context_processors.tzLink to this heading#Om denna processor är aktiverad kommer varje RequestContext att innehålla en variabel TIME_ZONE, som anger namnet på den aktuella aktiva tidszonen.
django.contrib.messages.context_processors.messagesLink to this heading#Om denna processor är aktiverad kommer varje RequestContext att innehålla dessa två variabler:
messages – En lista över meddelanden (som strängar) som har ställts in via messages framework.
DEFAULT_MESSAGE_LEVELS – En mappning av meddelandenivåernas namn till deras numeriska värde.
En kontextprocessor har ett enkelt gränssnitt: Det är en Python-funktion som tar ett argument, ett HttpRequest-objekt, och returnerar en ordbok som läggs till i mallkontexten.
Till exempel:, för att lägga till inställningen DEFAULT_FROM_EMAIL i varje kontext:
from django.conf import settings\n\n\ndef from_email(request):\n return {\n "DEFAULT_FROM_EMAIL": settings.DEFAULT_FROM_EMAIL,\n }\nAnpassade kontextprocessorer kan finnas var som helst i din kodbas. Allt Django bryr sig om är att dina anpassade kontextprocessorer pekas ut av alternativet 'context_processors' i din inställning TEMPLATES - eller argumentet context_processors i Engine om du använder det direkt.
Generellt sett lagrar du mallar i filer på ditt filsystem snarare än att använda lågnivå Template API själv. Spara mallar i en katalog som anges som en mallkatalog.
Django söker efter mallkataloger på ett antal ställen, beroende på dina inställningar för mallladdning (se ”Laddningstyper” nedan), men det mest grundläggande sättet att ange mallkataloger är genom att använda alternativet DIRS.
DIRSLink to this heading#Berätta för Django vilka dina mallkataloger är genom att använda alternativet DIRS i inställningen TEMPLATES i din inställningsfil - eller argumentet dirs i Engine. Detta bör ställas in på en lista med strängar som innehåller fullständiga sökvägar till dina mallkataloger:
TEMPLATES = [\n {\n "BACKEND": "django.template.backends.django.DjangoTemplates",\n "DIRS": [\n "/home/html/templates/lawrence.com",\n "/home/html/templates/default",\n ],\n },\n]\nDina mallar kan placeras var du vill, så länge katalogerna och mallarna kan läsas av webbservern. De kan ha vilket tillägg du vill, t.ex. .html eller .txt, eller inget tillägg alls.
Observera att dessa sökvägar ska använda snedstreck i Unix-stil, även under Windows.
\nSom standard använder Django en filsystembaserad mallladdare, men Django levereras med några andra mallladdare, som vet hur man laddar mallar från andra källor.
\nNågra av dessa andra laddare är inaktiverade som standard, men du kan aktivera dem genom att lägga till ett 'loaders' alternativ till din DjangoTemplates backend i TEMPLATES inställningen eller skicka ett loaders argument till Engine. loaders bör vara en lista med strängar eller tupler, där var och en representerar en mallinläsningsklass. Här är de mallinläsare som följer med Django:
django.template.loaders.filesystem.Loader
Läser in mallar från filsystemet enligt DIRS.
Den här laddaren är aktiverad som standard. Den kommer dock inte att hitta några mallar förrän du ställer in DIRS till en icke-tom lista:
TEMPLATES = [\n {\n "BACKEND": "django.template.backends.django.DjangoTemplates",\n "DIRS": [BASE_DIR / "templates"],\n }\n]\nDu kan också åsidosätta 'DIRS' och ange specifika kataloger för en viss filsystemladdare:
TEMPLATES = [\n {\n "BACKEND": "django.template.backends.django.DjangoTemplates",\n "OPTIONS": {\n "loaders": [\n (\n "django.template.loaders.filesystem.Loader",\n [BASE_DIR / "templates"],\n ),\n ],\n },\n }\n]\ndjango.template.loaders.app_directories.Loader
Laddar mallar från Django-appar på filsystemet. För varje app i INSTALLED_APPS letar laddaren efter en underkatalog med namnet templates. Om katalogen finns letar Django efter mallar i den.
Detta innebär att du kan lagra mallar med dina enskilda appar. Detta hjälper också till att distribuera Django-appar med standardmallar.
\nTill exempel:, för denna inställning:
\nINSTALLED_APPS = ["myproject.polls", "myproject.music"]\n…då kommer get_template('foo.html') att leta efter foo.html i dessa kataloger, i denna ordning:
/path/to/myproject/polls/templates/
/path/to/myproject/music/templates/
… och kommer att använda den som den hittar först.
\nOrdningen på INSTALLED_APPS är viktig! Om du till exempel vill anpassa Django-adminen kan du välja att åsidosätta standardmallen admin/base_site.html från django.contrib.admin med din egen admin/base_site.html i myproject.polls. Du måste då se till att din myproject.polls kommer före django.contrib.admin i INSTALLED_APPS, annars kommer django.contrib.admin att laddas först och din kommer att ignoreras.
Observera att laddaren utför en optimering när den körs första gången: den cachar en lista över vilka INSTALLED_APPS-paket som har en templates-underkatalog.
Du kan aktivera den här laddaren genom att ställa in APP_DIRS till True:
TEMPLATES = [\n {\n "BACKEND": "django.template.backends.django.DjangoTemplates",\n "APP_DIRS": True,\n }\n]\ndjango.template.loaders.cached.Loader
Djangos mallsystem är visserligen ganska snabbt, men om det behöver läsa och kompilera dina mallar varje gång de renderas kan omkostnaderna för detta bli höga.
\nDu konfigurerar den cachade mallladdaren med en lista över andra laddare som den ska omsluta. De omslutna laddarna används för att lokalisera okända mallar när de först påträffas. Den cachade laddaren lagrar sedan den kompilerade Template i minnet. Den cachade Template-instansen returneras för efterföljande förfrågningar om att ladda samma mall.
Den här laddaren aktiveras automatiskt om OPTIONS['loaders'] inte har angetts.
Du kan manuellt ange cachning av mallar med vissa anpassade mallladdare med inställningar som denna:
\nTEMPLATES = [\n {\n "BACKEND": "django.template.backends.django.DjangoTemplates",\n "DIRS": [BASE_DIR / "templates"],\n "OPTIONS": {\n "loaders": [\n (\n "django.template.loaders.cached.Loader",\n [\n "django.template.loaders.filesystem.Loader",\n "django.template.loaders.app_directories.Loader",\n "path.to.custom.Loader",\n ],\n ),\n ],\n },\n }\n]\ndjango.template.loaders.locmem.Loader
Läser in mallar från en Python-ordbok. Detta är användbart för testning.
\nDenna laddare tar en ordlista med mallar som sitt första argument:
\nTEMPLATES = [\n {\n "BACKEND": "django.template.backends.django.DjangoTemplates",\n "OPTIONS": {\n "loaders": [\n (\n "django.template.loaders.locmem.Loader",\n {\n "index.html": "content here",\n },\n ),\n ],\n },\n }\n]\nDenna laddare är avaktiverad som standard.
\nDjango använder mallladdarna i ordning enligt alternativet 'loaders. Den använder varje laddare tills en laddare hittar en matchning.
Det är möjligt att ladda mallar från ytterligare källor med hjälp av anpassade mallladdare. Anpassade Loader-klasser bör ärva från django.template.loaders.base.Loader och definiera metoderna get_contents() och get_template_sources().
Läser in mallar från en viss källa, t.ex. filsystemet eller en databas.
\nEn metod som tar ett template_name och ger Origin-instanser för varje möjlig källa.
Filsystemladdaren kan till exempel ta emot 'index.html som ett template_name-argument. Denna metod skulle ge ursprung för den fullständiga sökvägen till index.html som den visas i varje mallkatalog som laddaren tittar på.
Metoden behöver inte verifiera att mallen finns på en given sökväg, men den bör säkerställa att sökvägen är giltig. Filsystemladdaren ser t.ex. till att sökvägen ligger under en giltig mallkatalog.
\nReturnerar innehållet för en mall som ges en Origin-instans.
Det är här en filsystemladdare skulle läsa innehåll från filsystemet, eller en databasladdare skulle läsa från databasen. Om en matchande mall inte finns, bör detta ge upphov till ett TemplateDoesNotExist-fel.
Returnerar ett Template-objekt för ett givet template_name genom att loopa genom resultaten från get_template_sources() och anropa get_contents(). Detta returnerar den första matchande mallen. Om ingen mall hittas, TemplateDoesNotExist tas upp.
Det valfria argumentet skip är en lista över ursprung som ska ignoreras när mallar utökas. Detta gör det möjligt för mallar att utöka andra mallar med samma namn. Det används också för att undvika rekursionsfel.
I allmänhet räcker det med att definiera get_template_sources() och get_contents() för anpassade mallladdare. get_template() behöver vanligtvis inte åsidosättas.
Mallar har ett origin som innehåller attribut beroende på vilken källa de laddas från.
Sökvägen till mallen som returneras av mallladdaren. För laddare som läser från filsystemet är detta den fullständiga sökvägen till mallen.
\nOm mallen instansieras direkt i stället för via en mallladdare är detta ett strängvärde av <unknown_source>.
Den relativa sökvägen till mallen som skickas till mallladdaren.
\nOm mallen instansieras direkt i stället för via en mallladdare är detta None.
Den instans av mallladdaren som skapade denna Origin.
Om mallen instansieras direkt i stället för via en mallladdare är detta None.
django.template.loaders.cached.Loader kräver att alla dess omslutna laddare ställer in detta attribut, vanligtvis genom att instansiera Origin med loader=self.