Eftersom Django är ett webbramverk behöver det ett bekvämt sätt att generera HTML dynamiskt. Det vanligaste tillvägagångssättet bygger på mallar. En mall innehåller de statiska delarna av den önskade HTML-utskriften samt en speciell syntax som beskriver hur dynamiskt innehåll ska infogas. För ett praktiskt exempel på hur man skapar HTML-sidor med mallar, se Tutorial 3.
\nEtt Django-projekt kan konfigureras med en eller flera mallmotorer (eller till och med noll om du inte använder mallar). Django levererar inbyggda backends för sitt eget mallsystem, kreativt kallat Django template language (DTL), och för det populära alternativet Jinja2. Backends för andra mallspråk kan vara tillgängliga från tredje part. Du kan också skriva din egen anpassade backend, se Custom template backend
\nDjango definierar ett standard-API för laddning och rendering av mallar oavsett backend. Laddning består av att hitta mallen för en given identifierare och förbehandla den, vanligtvis kompilera den till en representation i minnet. Rendering innebär att mallen interpoleras med kontextdata och att den resulterande strängen returneras.
\nDjango mallspråk är Djangos eget mallsystem. Fram till Django 1.8 var det det enda inbyggda alternativet som fanns tillgängligt. Det är ett bra mallbibliotek även om det är ganska egensinnigt och har några idiosynkrasier. Om du inte har en tvingande anledning att välja en annan backend bör du använda DTL, särskilt om du skriver en pluggbar applikation och du tänker distribuera mallar. Djangos contrib-appar som innehåller mallar, som django.contrib.admin, använder DTL.
\nAv historiska skäl finns både det generiska stödet för mallmotorer och implementeringen av Djangos mallspråk i namnrymden django.template.
En Django-mall är ett textdokument eller en Python-sträng som märks upp med hjälp av Djangos mallspråk. Vissa konstruktioner känns igen och tolkas av mallmotorn. De viktigaste av dessa är variabler och taggar.
\nEn mall renderas med en kontext. Renderingen ersätter variabler med deras värden, som söks upp i kontexten, och kör taggar. Allt annat skrivs ut som det är.
\nSyntaxen i Djangos mallspråk består av fyra konstruktioner.
\nEn variabel matar ut ett värde från kontexten, som är ett diktatliknande objekt som mappar nycklar till värden.
\nVariabler omges av {{ och }} så här:
My first name is {{ first_name }}. My last name is {{ last_name }}.\nMed en kontext av {'first_name': 'John', 'last_name': 'Doe'}, renderar denna mall till:
My first name is John. My last name is Doe.\nDictionary lookup, attribute lookup och list-index lookup implementeras med en punktnotation:
\n{{ my_dict.key }}\n{{ my_object.attribute }}\n{{ my_list.0 }}\nOm en variabel motsvarar en anropsbar variabel kommer mallsystemet att anropa den utan argument och använda resultatet istället för den anropsbara variabeln.
\nFilter omvandlar värdena för variabler och taggargument.
\nDe ser ut så här:
\n{{ django|title }}\nMed en kontext av {'django': 'webbramverket för perfektionister med deadlines'}, renderar denna mall till:
The Web Framework For Perfectionists With Deadlines\nVissa filter tar ett argument:
\n{{ my_date|date:"Y-m-d" }}\nEn referens av inbyggda filter finns tillgänglig liksom instruktioner för att skriva egna filter.
\nKommentarer ser ut så här:
\n{# this won't be rendered #}\nEn {% comment %}-tagg ger kommentarer på flera rader.
django.template.Engine kapslar in en instans av Djangos mallsystem. Huvudskälet till att instansiera en Engine direkt är att använda Djangos mallspråk utanför ett Django-projekt.
django.template.backends.django.DjangoTemplates är ett tunt omslag som anpassar django.template.Engine till Djangos API för mallbackends.
django.template.Template representerar en kompilerad mall. Mallar erhålls med Engine.get_template() eller Engine.from_string().
På samma sätt är django.template.backends.django.Template en tunn omslag som anpassar django.template.Template till det vanliga mall-API:et.
django.template.Context innehåller vissa metadata utöver kontextdata. Den skickas till Template.render() för rendering av en mall.
django.template.RequestContext är en underklass till Context som lagrar den aktuella HttpRequest och kör mallkontextprocessorer.
Det vanliga API:et har inte något motsvarande koncept. Kontextdata skickas i en vanlig dict och den aktuella HttpRequest skickas separat om det behövs.
Template loaders är ansvariga för att hitta mallar, ladda dem och returnera Template-objekt.
Django tillhandahåller flera inbyggda mallladdare och stöder skräddarsydda mallladdare.
\nKontextprocessorer är funktioner som tar emot den aktuella HttpRequest som ett argument och returnerar en dict med data som ska läggas till i renderingskontexten.
Deras främsta användningsområde är att lägga till gemensamma data som delas av alla mallar i kontexten utan att upprepa kod i varje vy.
\nDjango tillhandahåller många inbyggda kontextprocessorer, och du kan också implementera dina egna ytterligare kontextprocessorer.
\nMallmotorer konfigureras med inställningen TEMPLATES. Det är en lista med konfigurationer, en för varje motor. Standardvärdet är tomt. I settings.py som genereras av kommandot startproject definieras ett mer användbart värde:
TEMPLATES = [\n {\n "BACKEND": "django.template.backends.django.DjangoTemplates",\n "DIRS": [],\n "APP_DIRS": True,\n "OPTIONS": {\n # ... some options here ...\n },\n },\n]\nBACKEND är en prickad Python-sökväg till en mallmotorklass som implementerar Djangos mallbackend API. De inbyggda backends är django.template.backends.django.DjangoTemplates och django.template.backends.jinja2.Jinja2.
Eftersom de flesta motorer laddar mallar från filer innehåller toppnivåkonfigurationen för varje motor två gemensamma inställningar:
\nDIRS definierar en lista över kataloger där sökmotorn ska leta efter mallkällfiler, i sökordning.
APP_DIRS anger om motorn ska leta efter mallar i installerade program. Varje backend definierar ett konventionellt namn för den underkatalog i programmen där dess mallar ska lagras.
Även om det är ovanligt är det möjligt att konfigurera flera instanser av samma backend med olika alternativ. I så fall bör du definiera en unik NAME för varje motor.
OPTIONS innehåller backend-specifika inställningar.
Modulen django.template.loader definierar två funktioner för att ladda mallar.
Denna funktion laddar mallen med det angivna namnet och returnerar ett Template-objekt.
Den exakta typen av returvärde beror på vilken backend som laddade mallen. Varje backend har sin egen Template-klass.
get_template() försöker varje mallmotor i ordning tills en lyckas. Om mallen inte kan hittas, ger det TemplateDoesNotExist. Om mallen hittas men innehåller ogiltig syntax, ger den upphov till TemplateSyntaxError.
Hur mallar söks och laddas beror på varje motors backend och konfiguration.
\nOm du vill begränsa sökningen till en viss mallmotor ska du ange motorns NAME i argumentet using.
Partial loading:
\nWhen using the DjangoTemplates\nbackend, a specific fragment from a template can be loaded by name. This\nfragment should have been previously defined using the partialdef\ntemplate tag:
from django.template.loader import get_template\n\n# Load an entire template.\ntemplate = get_template("template.html")\n\n# Load a specific fragment from a template.\npartial = get_template("template.html#partial_name")\nWhen loading a partial, the returned object behaves like a regular\nTemplate but contains only the partial’s content.
See Template partials for more information about defining and using\ntemplate fragments.
\n\nselect_template() är precis som get_template(), förutom att den tar en lista med mallnamn. Den prövar varje namn i ordning och returnerar den första mallen som finns.
Om inläsningen av en mall misslyckas kan följande två undantag, definierade i django.template, uppstå:
Detta undantag uppstår när en mall inte kan hittas. Det accepterar följande valfria argument för att fylla i mall postmortem <template-postmortem>` på felsökningssidan:
\nbackendDen backend-instans för mallen som undantaget härrörde från.
\nförsökteEn lista över källor som provades när mallen hittades. Detta är formaterat som en lista med tupler som innehåller (origin, status), där origin är ett ursprungsliknande-objekt och status är en sträng med anledningen till att mallen inte hittades.
kedjaEn lista över mellanliggande TemplateDoesNotExist-undantag som uppstår när man försöker ladda en mall. Detta används av funktioner, såsom get_template(), som försöker ladda en viss mall från flera motorer.
Detta undantag uppstår när en mall har hittats men innehåller fel.
\nTemplate-objekt som returneras av get_template() och select_template() måste tillhandahålla en render()-metod med följande signatur:
Renderar denna mall med ett givet sammanhang.
\nOm context anges måste det vara en dict. Om det inte anges kommer mallen att renderas med en tom kontext.
Om request anges måste det vara en HttpRequest. Sedan måste motorn göra den, liksom CSRF-token, tillgänglig i mallen. Hur detta uppnås är upp till varje backend.
Här är ett exempel på sökalgoritmen. I det här exemplet är TEMPLATES inställningen:
TEMPLATES = [\n {\n "BACKEND": "django.template.backends.django.DjangoTemplates",\n "DIRS": [\n "/home/html/example.com",\n "/home/html/default",\n ],\n },\n {\n "BACKEND": "django.template.backends.jinja2.Jinja2",\n "DIRS": [\n "/home/html/jinja2",\n ],\n },\n]\nOm du anropar get_template('story_detail.html'), här är filerna som Django kommer att leta efter, i ordning:
/home/html/example.com/story_detail.html ('django' motor)
/home/html/default/story_detail.html ('django' motor)
/home/html/jinja2/story_detail.html ('jinja2' motor)
Om du kallar select_template(['story_253_detail.html', 'story_detail.html']), här är vad Django kommer att leta efter:
/home/html/example.com/story_253_detail.html ('django' motor)
/home/html/default/story_253_detail.html ('django' motor)
/home/html/jinja2/story_253_detail.html ('jinja2' motor)
/home/html/example.com/story_detail.html ('django' motor)
/home/html/default/story_detail.html ('django' motor)
/home/html/jinja2/story_detail.html ('jinja2' motor)
När Django hittar en mall som redan finns, slutar den att leta.
\n\nDet är möjligt - och att föredra - att organisera mallar i underkataloger inuti varje katalog som innehåller mallar. Konventionen är att skapa en underkatalog för varje Django-app, med underkataloger inom dessa underkataloger efter behov.
\nGör detta för din egen skull. Att lagra alla mallar på rotnivån i en enda katalog blir rörigt.
\nOm du vill ladda en mall som finns i en underkatalog använder du ett snedstreck, så här:
\nget_template("news/story_detail.html")\nMed samma TEMPLATES-alternativ som ovan, kommer detta att försöka ladda följande mallar:
/home/html/example.com/news/story_detail.html ('django' motor)
/home/html/default/news/story_detail.html ('django' motor)
/home/html/jinja2/news/story_detail.html ('jinja2' motor)
För att minska den repetitiva karaktären av laddning och rendering av mallar tillhandahåller Django dessutom en genvägsfunktion som automatiserar processen.
\nrender_to_string() laddar en mall som get_template() och anropar dess render()-metod omedelbart. Den tar följande argument.
template_nameNamnet på den mall som ska laddas och renderas. Om det är en lista med mallnamn använder Django select_template() istället för get_template() för att hitta mallen.
kontextEn dict som ska användas som mallens kontext för rendering.
begäranEn valfri HttpRequest som kommer att vara tillgänglig under mallens renderingsprocess.
använderEn valfri mallmotor NAME. Sökningen efter mallen kommer att begränsas till denna motor.
Exempel på användning:
\nfrom django.template.loader import render_to_string\n\nrendered = render_to_string("my_template.html", {"foo": "bar"})\nSee also the render() shortcut which calls\nrender_to_string() and feeds the result into an\nHttpResponse suitable for returning from a view.
Slutligen kan du använda konfigurerade motorer direkt:
\nMallmotorer finns tillgängliga i django.template.engines:
from django.template import engines\n\ndjango_engine = engines["django"]\ntemplate = django_engine.from_string("Hello {{ name }}!")\nUppslagsordet - 'django i det här exemplet - är motorns NAME.
Ställ in BACKEND till 'django.template.backends.django.DjangoTemplates' för att konfigurera en Django-mallmotor.
När APP_DIRS är True, letar DjangoTemplates motorer efter mallar i templates underkatalogen för installerade applikationer. Detta generiska namn behölls för bakåtkompatibilitet.
DjangoTemplates motorer accepterar följande OPTIONS:
'autoescape': ett boolean som kontrollerar om HTML autoescaping är aktiverat.
Standardvärdet är True.
'context_processors': 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': ett boolean som aktiverar/avaktiverar mallens felsökningsläge. Om det är True kommer den snygga felsidan att visa en detaljerad rapport för alla undantag som uppstår under mallrenderingen. Denna rapport innehåller det relevanta utdraget av mallen med lämplig rad markerad.
Standardvärdet är värdet för inställningen DEBUG.
'loaders': en lista med prickade Python-sökvägar till klasser för mallinläsare. Varje Loader-klass vet hur man importerar mallar från en viss källa. Alternativt kan en tupel användas istället för en sträng. Det första objektet i tupeln bör vara Loader-klassens namn, och efterföljande objekt skickas till Loader under initialiseringen.
Standardvärdet beror på värdena i DIRS och APP_DIRS.
Se Typer av lastare för mer information.
\n'string_if_invalid': utdata, i form av en sträng, som mallsystemet ska använda för ogiltiga (t.ex. felstavade) variabler.
Standardvärdet är en tom sträng.
\nSe Hur ogiltiga variabler hanteras för mer information.
\n'file_charset': 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 kan användas för att lägga till nya bibliotek eller tillhandahålla alternativa etiketter för befintliga bibliotek. Till exempel:
OPTIONS = {\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:
OPTIONS = {\n "builtins": ["myapp.builtins"],\n}\nTaggar och filter från inbyggda bibliotek kan användas utan att först anropa {% load %} tagg.
Kräver att Jinja2 är installerat:
\nLinux / macOS
$ python -m pip install Jinja2\nWindows
...\\> py -m pip install Jinja2\nSätt BACKEND till 'django.template.backends.jinja2.Jinja2' för att konfigurera en Jinja2-motor.
När APP_DIRS är True letar Jinja2-motorerna efter mallar i underkatalogen jinja2 för installerade program.
Den viktigaste posten i OPTIONS är 'environment'. Det är en prickad Python-sökväg till en anropsbar som returnerar en Jinja2-miljö. Standardvärdet är 'jinja2.Environment'. Django anropar den anropsbara och skickar andra alternativ som nyckelordsargument. Dessutom lägger Django till standardvärden som skiljer sig från Jinja2:s för några alternativ:
'autoescape': True
'auto_reload': settings.DEBUG
'undefined': DebugUndefined if settings.DEBUG else Undefined
Jinja2 motorer accepterar också följande OPTIONS:
'context_processors': 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.
\n\nThe default configuration is purposefully kept to a minimum. If a template is\nrendered with a request (e.g. when using render()),\nthe Jinja2 backend adds the globals request, csrf_input, and\ncsrf_token to the context. Apart from that, this backend doesn’t create a\nDjango-flavored environment. It doesn’t know about Django filters and tags.\nIn order to use Django-specific APIs, you must configure them into the\nenvironment.
Du kan till exempel skapa myproject/jinja2.py med följande innehåll:
from django.templatetags.static import static\nfrom django.urls import reverse\n\nfrom jinja2 import Environment\n\n\ndef environment(**options):\n env = Environment(**options)\n env.globals.update(\n {\n "static": static,\n "url": reverse,\n }\n )\n return env\noch ställa in alternativet 'environment' till 'myproject.jinja2.environment'.
Då kan du använda följande konstruktioner i Jinja2-mallar:
\n<img src="{{ static('path/to/company-logo.png') }}" alt="Company Logo">\n\n<a href="{{ url('admin:index') }}">Administration</a>\nBegreppen taggar och filter finns både i Djangos mallspråk och i Jinja2, men de används på olika sätt. Eftersom Jinja2 stöder att skicka argument till anropsbara funktioner i mallar, kan många funktioner som kräver en malltagg eller ett filter i Django-mallar uppnås genom att anropa en funktion i Jinja2-mallar, som visas i exemplet ovan. Jinja2:s globala namnrymd tar bort behovet av mallkontextprocessorer. Djangos mallspråk har inte någon motsvarighet till Jinja2-tester.
\n