Detta dokument förklarar språksyntaxen i Djangos mallsystem. Om du letar efter ett mer tekniskt perspektiv på hur det fungerar och hur du kan utöka det, se Djangos mallspråk: för Python-programmerare.
\nDjangos mallspråk är utformat för att hitta en balans mellan kraft och enkelhet. Det är utformat för att kännas bekvämt för dem som är vana vid att arbeta med HTML. Om du har någon erfarenhet av andra textbaserade mallspråk, som Smarty eller Jinja2, kommer du att känna dig som hemma med Djangos mallar.
\n\nEn mall är en textfil. Den kan generera vilket textbaserat format som helst (HTML, XML, CSV, etc.).
\nEn mall innehåller variabler, som ersätts med värden när mallen utvärderas, och taggar, som styr logiken i mallen.
\nNedan visas en minimal mall som illustrerar några grundläggande principer. Varje element kommer att förklaras senare i detta dokument.
\n{% extends "base_generic.html" %}\n\n{% block title %}{{ section.title }}{% endblock %}\n\n{% block content %}\n<h1>{{ section.title }}</h1>\n\n{% for story in story_list %}\n<h2>\n <a href="{{ story.get_absolute_url }}">\n {{ story.headline|upper }}\n </a>\n</h2>\n<p>{{ story.tease|truncatewords:"100" }}</p>\n{% endfor %}\n{% endblock %}\nVariabler ser ut på följande sätt: {{variabel }}. När mallmotorn stöter på en variabel utvärderar den variabeln och ersätter den med resultatet. Variabelnamn består av en kombination av alfanumeriska tecken och understreck ("_"), men får inte börja med ett understreck eller vara ett tal. Punkten (".") förekommer också i variabelavsnitt, men den har en speciell betydelse som beskrivs nedan. Det är viktigt att du inte kan ha mellanslag eller skiljetecken i variabelnamn.
Använd en punkt (.) för att komma åt attribut för en variabel.
I exemplet ovan kommer {{ section.title }} att ersättas med attributet title för objektet section.
Om du använder en variabel som inte finns kommer mallsystemet att infoga värdet för alternativet string_if_invalid, som är inställt på '' (den tomma strängen) som standard.
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.
Variabelattribut som börjar med en understrykning kan inte nås eftersom de i allmänhet anses vara privata.
\nDu kan ändra variabler som ska visas med hjälp av filter.
\nFilter ser ut så här: {{namn|lower }}. Här visas värdet för variabeln {{namn }} efter att ha filtrerats genom filtret lower, som omvandlar text till gemener. Använd ett rör (|) för att tillämpa ett filter.
Filter kan ”kedjas” Resultatet från ett filter tillämpas på nästa. {{ text|escape|linebreaks }} är ett vanligt idiom för att escapa textinnehåll och sedan konvertera radbrytningar till <p> taggar.
Vissa filter tar emot argument. Ett filterargument ser ut så här: {{ bio|truncatewords:30 }}. Detta visar de 30 första orden i variabeln bio.
Filterargument som innehåller mellanslag måste citeras; om du t.ex. vill sammanfoga en lista med kommatecken och mellanslag använder du {{ list|join:", " }}.
Django tillhandahåller ett sextiotal inbyggda mallfilter. Du kan läsa allt om dem i inbyggd filterreferens. För att ge dig en försmak av vad som finns tillgängligt, här är några av de vanligaste mallfiltren:
\ndefaultOm en variabel är falsk eller tom, använd angiven standard. I annat fall används variabelns värde. Till exempel:
\n{{ value|default:"nothing" }}\nOm value inte anges eller är tomt, kommer ovanstående att visa ”nothing”.
längdReturnerar längden på värdet. Detta fungerar för både strängar och listor. Till exempel:
\n{{ value|length }}\nOm värde är ['a', 'b', 'c', 'd'], blir utdata 4.
filstorleksformatFormaterar värdet som en ”mänskligt läsbar” filstorlek (dvs. '13 KB', '4,1 MB', '102 bytes', etc.). Till exempel:
{{ value|filesizeformat }}\nOm värde är 123456789, skulle utdata vara 117.7 MB.
Återigen, detta är bara några exempel; se inbyggt filter referens för den fullständiga listan.
\nDu kan också skapa dina egna anpassade mallfilter, se Så här skapar du anpassade malltaggar och filter.
\n\nOm du vill kommentera bort en del av en rad i en mall använder du kommentarsyntaxen: {# #}.
Till exempel: skulle den här mallen återges som 'hello':
{# greeting #}hello\nEn kommentar kan innehålla vilken mallkod som helst, oavsett om den är ogiltig eller inte. Till exempel:
\n{# {% if foo %}bar{% else %} #}\nDenna syntax kan endast användas för kommentarer på en rad (inga nya rader tillåts mellan {# och #} avgränsarna). Om du behöver kommentera ut en flerradig del av mallen, se taggen comment.
Den mest kraftfulla - och därmed den mest komplexa - delen av Djangos mallmotor är mallarv. Med mallarv kan du bygga en grundläggande ”skelettmall” som innehåller alla vanliga element på din webbplats och definierar block som barnmallar kan åsidosätta.
\nLåt oss titta på mallar som ärvs genom att börja med ett exempel:
\n<!DOCTYPE html>\n<html lang="en">\n<head>\n <link rel="stylesheet" href="style.css">\n <title>{% block title %}My amazing site{% endblock %}</title>\n</head>\n\n<body>\n <div id="sidebar">\n {% block sidebar %}\n <ul>\n <li><a href="/">Home</a></li>\n <li><a href="/blog/">Blog</a></li>\n </ul>\n {% endblock %}\n </div>\n\n <div id="content">\n {% block content %}{% endblock %}\n </div>\n</body>\n</html>\nDenna mall, som vi kallar base.html, definierar ett HTML-skelettdokument som du kan använda för en sida med två kolumner. Det är ”barn”-mallarnas uppgift att fylla de tomma blocken med innehåll.
I det här exemplet definierar taggen block tre block som underordnade mallar kan fylla i. Allt taggen block gör är att tala om för mallmotorn att en underordnad mall kan åsidosätta dessa delar av mallen.
En barnmall kan se ut så här:
\n{% extends "base.html" %}\n\n{% block title %}My amazing blog{% endblock %}\n\n{% block content %}\n{% for entry in blog_entries %}\n <h2>{{ entry.title }}</h2>\n <p>{{ entry.body }}</p>\n{% endfor %}\n{% endblock %}\nTaggen extends är nyckeln här. Den talar om för mallmotorn att den här mallen ”förlänger” en annan mall. När mallsystemet utvärderar den här mallen letar det först upp den överordnade mallen - i det här fallet ”base.html”.
Vid den tidpunkten kommer mallmotorn att märka de tre block-taggarna i base.html och ersätta dessa block med innehållet i barnmallen. Beroende på värdet på blog_entries kan utdata se ut som:
<!DOCTYPE html>\n<html lang="en">\n<head>\n <link rel="stylesheet" href="style.css">\n <title>My amazing blog</title>\n</head>\n\n<body>\n <div id="sidebar">\n <ul>\n <li><a href="/">Home</a></li>\n <li><a href="/blog/">Blog</a></li>\n </ul>\n </div>\n\n <div id="content">\n <h2>Entry one</h2>\n <p>This is my first entry.</p>\n\n <h2>Entry two</h2>\n <p>This is my second entry.</p>\n </div>\n</body>\n</html>\nObservera att eftersom barnmallen inte definierade blocket sidebar används värdet från den överordnade mallen i stället. Innehåll i en {% block %}-tagg i en överordnad mall används alltid som en fallback.
Du kan använda så många nivåer av arv som behövs. Ett vanligt sätt att använda arv är följande tre nivåer:
\nSkapa en mall, ”base.html”, som innehåller webbplatsens huvudsakliga utseende och känsla.
Skapa en mall base_SECTIONNAME.html för varje ”sektion” på din webbplats. Till exempel:, base_news.html, base_sports.html. Dessa mallar utökar alla base.html och inkluderar sektionsspecifika stilar/design.
Skapa individuella mallar för varje typ av sida, t.ex. en nyhetsartikel eller ett blogginlägg. Dessa mallar utökar den lämpliga sektionsmallen.
Detta tillvägagångssätt maximerar återanvändningen av kod och hjälper till att lägga till objekt i delade innehållsområden, t.ex. sektionsomfattande navigering.
\nHär är några tips för att arbeta med arv:
\nOm du använder {% extends %} i en mall, måste det vara den första malltaggen i den mallen. Mallarv fungerar inte annars.
Fler {% block %}-taggar i dina basmallar är bättre. Kom ihåg att barnmallar inte behöver definiera alla överordnade block, så du kan fylla i rimliga standardvärden i ett antal block och sedan bara definiera dem du behöver senare. Det är bättre att ha fler hooks än färre hooks.
Om du upptäcker att du duplicerar innehåll i ett antal mallar betyder det förmodligen att du bör flytta innehållet till ett {% block %} i en överordnad mall.
Om du behöver hämta innehållet i blocket från den överordnade mallen kan du använda variabeln {{ block.super }}. Detta är användbart om du vill lägga till innehållet i ett överordnat block i stället för att helt åsidosätta det. Data som infogas med hjälp av {{ block.super }} kommer inte att escapas automatiskt (se nästa avsnitt), eftersom de redan escapats, om nödvändigt, i den överordnade mallen.
Genom att använda samma mallnamn som du ärver från, kan {% extends %} användas för att ärva en mall samtidigt som du åsidosätter den. Kombinerat med {{ block.super }} kan detta vara ett kraftfullt sätt att göra små anpassningar. Se Utöka en åsidosatt mall i Overriding templates How-to för ett fullständigt exempel.
Variabler som skapas utanför en {% block %} med hjälp av malltaggen as syntax kan inte användas inuti blocket. Till exempel:, den här mallen renderar ingenting:
{% translate "Title" as title %}\n{% block content %}{{ title }}{% endblock %}\nFör extra läsbarhet kan du välja att ge ett namn till din tagg {% endblock %}. Till exempel:
{% block content %}\n...\n{% endblock content %}\nI större mallar hjälper den här tekniken dig att se vilka {% block %}-taggar som stängs.
{% block %}-taggar utvärderas först. Det är därför som innehållet i ett block alltid åsidosätts, oavsett sanningshalten i omgivande taggar. Till exempel: kommer den här mallen alltid att åsidosätta innehållet i blocket title:
{% if change_title %}\n {% block title %}Hello!{% endblock title %}\n{% endif %}\nSlutligen bör du notera att du inte kan definiera flera block-taggar med samma namn i samma mall. Denna begränsning finns eftersom en block-tagg fungerar i ”båda” riktningarna. Det vill säga, en block-tagg ger inte bara ett hål att fylla - den definierar också det innehåll som fyller hålet i föräldern. Om det fanns två block-taggar med liknande namn i en mall, skulle mallens förälder inte veta vilket av blockens innehåll som skulle användas.
Template partials define reusable template fragments within a template file.\nThey are self-contained components that can be rendered multiple times within\nthe same template, helping to avoid repetition and maintain consistent output.
\nA partial can be defined using the partialdef tag:
authors.html{% partialdef user-info %}\n <div id="user-info-{{ user.username }}">\n <h3>{{ user.name }}</h3>\n <p>{{ user.bio }}</p>\n </div>\n{% endpartialdef %}\nFor extra readability, the name can be included in the {% endpartialdef %}\nclosing tag:
{% partialdef user-info %}\n {# ... #}\n{% endpartialdef user-info %}\nThe template fragment can be rendered using the partial tag:
{% partial user-info %}\nA template fragment can be reused multiple times:
\nauthors.html{% block content %}\n <h2>Authors</h2>\n {% for user in authors %}\n {% partial user-info %}\n {% endfor %}\n\n <h2>Editors</h2>\n {% for user in editors %}\n {% partial user-info %}\n {% endfor %}\n{% endblock %}\nThe partial content is rendered each time the named partial is used, with the\ncurrent template context.
\nA template fragment can be defined and rendered in-place using the inline\nargument. This defines the partial for later reuse while also rendering it\nimmediately at its definition:
{# Define and render immediately. #}\n{% partialdef user-info inline %}\n <div id="user-info-{{ user.username }}">\n <h3>{{ user.name }}</h3>\n <p>{{ user.bio }}</p>\n </div>\n{% endpartialdef %}\n\n{# Other page content here. #}\n\n{# Reuse later elsewhere in the template. #}\n<section class="featured-authors">\n <h2>Featured Authors</h2>\n {% for user in featured %}\n {% partial user-info %}\n {% endfor %}\n</section>\nTemplate fragments defined with partialdef can be accessed directly via\ntemplate loading or inclusion using the template.html#partial_name syntax.
For example, using the render() shortcut, the following\ncode renders only the partial named user-info defined in the\nauthors.html template:
from django.contrib.auth.models import User\nfrom django.shortcuts import get_object_or_404, render\n\n\ndef user_info_partial(request, user_id):\n user = get_object_or_404(User, id=user_id)\n return render(request, "authors.html#user-info", {"user": user})\nThis approach is particularly useful for AJAX-style requests that update only\nspecific portions of a page with the rendered template fragment.
\nTemplate partials can also be included using the include template tag\nwith the same # directive:
{% include "authors.html#user-info" %}\nTemplate partials are rendered with the current template context. They work as\nexpected in loops and with context variables:
\n{% for user in users %}\n {% partial user-info %}\n{% endfor %}\nContext variables can be adjusted using the with tag:
{% with user=featured_author %}\n <h2>Featured Author of the Month</h2>\n {% partial user-info %}\n{% endwith %}\nNär HTML genereras från mallar finns det alltid en risk att en variabel innehåller tecken som påverkar den resulterande HTML:en. Tänk till exempel på detta mallfragment:
\nHello, {{ name }}\nTill en början verkar detta vara ett harmlöst sätt att visa en användares namn, men tänk på vad som skulle hända om användaren skrev in sitt namn så här:
\n<script>alert('hello')</script>\nMed detta namnvärde skulle mallen återges som:
\nHello, <script>alert('hello')</script>\n…vilket innebär att webbläsaren skulle visa en JavaScript-varningsruta!
\nOch om namnet innehåller symbolen '<', så här?
<b>username\nDet skulle resultera i en renderad mall som denna:
\nHello, <b>username\n…vilket i sin tur skulle leda till att resten av webbsidan skulle vara i fetstil!
\nDet är uppenbart att man inte ska lita blint på data som skickas in av användare och infoga dem direkt i webbsidorna, eftersom en illvillig användare kan använda den här typen av hål för att göra potentiellt dåliga saker. Den här typen av säkerhetsbrist kallas för en XSS-attack (Cross Site Scripting).
\nFör att undvika detta problem har du två alternativ:
\nEtt, du kan se till att köra varje opålitlig variabel genom escape-filtret (dokumenterat nedan), som konverterar potentiellt skadliga HTML-tecken till oskadliga. Detta var standardlösningen i Django under de första åren, men problemet är att det lägger ansvaret på * dig*, utvecklaren / mallförfattaren, att se till att du escapar allt. Det är lätt att glömma att undkomma data.
För det andra kan du dra nytta av Djangos automatiska HTML-escaping. Resten av detta avsnitt beskriver hur automatisk eskapning fungerar.
Som standard i Django escapar varje mall automatiskt utdata från varje variabel tagg. Specifikt är dessa fem tecken escapade:
\n< konverteras till <
> konverteras till >
' (enkelt citattecken) konverteras till '
" (dubbelcitat) konverteras till "
& konverteras till &
Återigen betonar vi att detta beteende är aktiverat som standard. Om du använder Djangos mallsystem är du skyddad.
\nOm du inte vill att data ska förslutas automatiskt, per webbplats, per mall eller per variabel, kan du stänga av det på flera olika sätt.
\nVarför skulle du vilja stänga av det? För att mallvariabler ibland innehåller data som du menar ska återges som rå HTML, och då vill du inte att deras innehåll ska escapas. Du kanske till exempel lagrar en HTML-blobb i din databas och vill bädda in den direkt i din mall. Eller så kanske du använder Djangos mallsystem för att producera text som inte är HTML - som ett e-postmeddelande, till exempel.
\nOm du vill inaktivera automatisk eskapning för en enskild variabel använder du filtret safe:
This will be escaped: {{ data }}\nThis will not be escaped: {{ data|safe }}\nTänk på safe som en förkortning för safe from further escaping eller can be safely interpreted as HTML. I detta exempel, om data innehåller '<b>', kommer utdata att vara:
This will be escaped: <b>\nThis will not be escaped: <b>\nFör att styra automatisk avstavning för en mall, linda in mallen (eller en viss del av mallen) i autoescape taggen, så här:
{% autoescape off %}\n Hello {{ name }}\n{% endautoescape %}\nTaggen autoescape tar antingen on eller off som sitt argument. Ibland kanske du vill tvinga fram automatisk eskapning när den annars skulle vara inaktiverad. Här är ett exempel på en mall:
Auto-escaping is on by default. Hello {{ name }}\n\n{% autoescape off %}\n This will not be auto-escaped: {{ data }}.\n\n Nor this: {{ other_data }}\n {% autoescape on %}\n Auto-escaping applies again: {{ name }}\n {% endautoescape %}\n{% endautoescape %}\nAuto-escaping-taggen överför sin effekt till mallar som utökar den aktuella samt mallar som inkluderas via taggen include, precis som alla blocktaggar. Till exempel:
bas.html{% autoescape off %}\n<h1>{% block title %}{% endblock %}</h1>\n{% block content %}\n{% endblock %}\n{% endautoescape %}\nchild.html{% extends "base.html" %}\n{% block title %}This & that{% endblock %}\n{% block content %}{{ greeting }}{% endblock %}\nEftersom auto-escaping är avstängt i basmallen kommer det också att vara avstängt i underordnad mall, vilket resulterar i följande renderade HTML när variabeln greeting innehåller strängen Hello<b>!</b>:
<h1>This & that</h1>\n<b>Hello!</b>\nGenerellt sett behöver mallförfattare inte oroa sig för automatisk escaping särskilt mycket. Utvecklare på Python-sidan (personer som skriver vyer och anpassade filter) måste tänka på de fall där data inte ska escapas och markera data på lämpligt sätt, så att saker och ting bara fungerar i mallen.
\nOm du skapar en mall som kan användas i situationer där du inte är säker på om automatisk eskapning är aktiverad, lägg då till ett escape-filter till alla variabler som behöver eskapas. När automatisk eskapning är aktiverad finns det ingen risk för att filtret escape dubbel-eskapar data - filtret escape påverkar inte variabler med automatisk eskapning.
Som vi nämnde tidigare kan filterargument vara strängar:
\n{{ data|default:"This is a string literal." }}\nAlla stränglitteraler infogas utan någon automatisk escaping i mallen - de fungerar som om de alla hade passerat genom filtret safe. Anledningen till detta är att mallförfattaren har kontroll över vad som läggs in i stränglitalen, så att de kan se till att texten är korrekt escapad när mallen skrivs.
Detta innebär att du skulle skriva :
\n{{ data|default:"3 < 2" }}\n…snarare än:
\n{{ data|default:"3 < 2" }} {# Bad! Don't do this. #}\nDetta påverkar inte vad som händer med data som kommer från själva variabeln. Variabelns innehåll escapas fortfarande automatiskt, om det behövs, eftersom det ligger utanför mallförfattarens kontroll.
\nDe flesta metodanrop som är kopplade till objekt är också tillgängliga från mallar. Detta innebär att mallar har tillgång till mycket mer än bara klassattribut (som fältnamn) och variabler som skickas in från vyer. Till exempel: tillhandahåller Django ORM ”entry_set” syntax för att hitta en samling objekt som är relaterade till en främmande nyckel. Därför kan du, med en modell som heter ”comment” med en främmande nyckelrelation till en modell som heter ”task”, slingra dig genom alla kommentarer som är kopplade till en viss uppgift så här:
\n{% for comment in task.comment_set.all %}\n {{ comment }}\n{% endfor %}\nPå samma sätt tillhandahåller QuerySets en count()-metod för att räkna antalet objekt som de innehåller. Därför kan du få en räkning av alla kommentarer som är relaterade till den aktuella uppgiften med:
{{ task.comment_set.all.count }}\nDu kan också få tillgång till metoder som du uttryckligen har definierat i dina egna modeller:
\nmodeller.pyclass Task(models.Model):\n def foo(self):\n return "bar"\nmall.html{{ task.foo }}\nEftersom Django avsiktligt begränsar mängden logisk bearbetning som är tillgänglig i mallspråket är det inte möjligt att skicka argument till metodanrop som nås från mallar. Data bör beräknas i vyer och sedan skickas till mallar för visning.
\nVissa applikationer tillhandahåller anpassade tagg- och filterbibliotek. För att komma åt dem i en mall, se till att applikationen finns i INSTALLED_APPS (vi lägger till 'django.contrib.humanize' i det här exemplet), och använd sedan load-taggen i en mall:
{% load humanize %}\n\n{{ 45000|intcomma }}\nI ovanstående laddar load taggen taggbiblioteket humanize, som sedan gör filtret intcomma tillgängligt för användning. Om du har aktiverat django.contrib.admindocs kan du läsa dokumentationsområdet i din admin för att hitta listan över anpassade bibliotek i din installation.
Taggen load kan innehålla flera biblioteksnamn, åtskilda med mellanslag. Exempel på detta:
{% load humanize i18n %}\nSe Så här skapar du anpassade malltaggar och filter för information om hur du skriver dina egna anpassade mallbibliotek.
\nNär du laddar ett anpassat tagg- eller filterbibliotek görs taggarna/filtren endast tillgängliga för den aktuella mallen - inte för eventuella överordnade eller underordnade mallar längs mallens arvsstig.
\nOm t.ex. en mall foo.html har {% load humanize %}, kommer en underordnad mall (t.ex. en som har {% extends "foo.html" %}) inte att ha tillgång till humanize-mallens taggar och filter. Den underordnade mallen är ansvarig för sin egen {% load humanize %}.
Detta är en funktion för underhållbarhetens och sanitetens skull.
\n\n