MallarLink to this heading#

SyntaxLink to this heading#

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.

En 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.

Syntaxen i Djangos mallspråk består av fyra konstruktioner.

My first name is {{ first_name }}. My last name is {{ last_name }}.

My first name is John. My last name is Doe.

{{ my_dict.key }}
{{ my_object.attribute }}
{{ my_list.0 }}

{% csrf_token %}

{% cycle 'odd' 'even' %}

{% if user.is_authenticated %}Hello, {{ user.username }}.{% endif %}

{{ django|title }}

The Web Framework For Perfectionists With Deadlines

{{ my_date|date:"Y-m-d" }}

{# this won't be rendered #}

KomponenterLink to this heading#

KonfigurationLink to this heading#

Mallmotorer 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 = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [],
        "APP_DIRS": True,
        "OPTIONS": {
            # ... some options here ...
        },
    },
]

BACKEND ä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:

• DIRS 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.

AnvändningLink to this heading#

Modulen django.template.loader definierar två funktioner för att ladda mallar.

get_template(template_name, using=None)Link to this definition#

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.

Om du vill begränsa sökningen till en viss mallmotor ska du ange motorns NAME i argumentet using.

select_template(template_name_list, using=None)Link to this definition#

select_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å:

exception TemplateDoesNotExist(msg, tried=None, backend=None, chain=None)Link to this definition#

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:

backend

Den backend-instans för mallen som undantaget härrörde från.

försökte

En 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.

kedja

En 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.

exception TemplateSyntaxError(msg)Link to this definition#

Detta undantag uppstår när en mall har hittats men innehåller fel.

Template-objekt som returneras av get_template() och select_template() måste tillhandahålla en render()-metod med följande signatur:

Template.render(context=None, request=None)Link to this definition#

Renderar denna mall med ett givet sammanhang.

Om 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 = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [
            "/home/html/example.com",
            "/home/html/default",
        ],
    },
    {
        "BACKEND": "django.template.backends.jinja2.Jinja2",
        "DIRS": [
            "/home/html/jinja2",
        ],
    },
]

Om 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.

Det ä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.

Gör detta för din egen skull. Att lagra alla mallar på rotnivån i en enda katalog blir rörigt.

Om du vill ladda en mall som finns i en underkatalog använder du ett snedstreck, så här:

get_template("news/story_detail.html")

Med 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.

render_to_string(template_name, context=None, request=None, using=None)Link to this definition#

render_to_string() laddar en mall som get_template() och anropar dess render()-metod omedelbart. Den tar följande argument.

template_name

Namnet 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.

kontext

En dict som ska användas som mallens kontext för rendering.

begäran

En valfri HttpRequest som kommer att vara tillgänglig under mallens renderingsprocess.

använder

En valfri mallmotor NAME. Sökningen efter mallen kommer att begränsas till denna motor.

Exempel på användning:

Code

from django.template.loader import render_to_string

rendered = render_to_string("my_template.html", {"foo": "bar"})

Se även genvägen render() som anropar render_to_string() och matar in resultatet i en HttpResponse som är lämplig att returnera från en vy.

Slutligen kan du använda konfigurerade motorer direkt:

enginesLink to this definition#

Mallmotorer finns tillgängliga i django.template.engines:

Code

from django.template import engines

django_engine = engines["django"]
template = django_engine.from_string("Hello {{ name }}!")

Uppslagsordet - 'django i det här exemplet - är motorns NAME.

Inbyggda backendsLink to this heading#

class DjangoTemplatesLink to this definition#

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.

  Se 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.

• '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.

  Se Hur ogiltiga variabler hanteras för mer information.

• '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:

  Code

  OPTIONS = {
      "libraries": {
          "myapp_tags": "path.to.myapp.tags",
          "admin.urls": "django.contrib.admin.templatetags.admin_urls",
      },
  }
  

  Bibliotek 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:

  Code

  OPTIONS = {
      "builtins": ["myapp.builtins"],
  }
  

  Taggar och filter från inbyggda bibliotek kan användas utan att först anropa {% load %} tagg.

class Jinja2Link to this definition#

Kräver att Jinja2 är installerat:

$ python -m pip install Jinja2

...\> py -m pip install Jinja2

Sä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

• 'loader': en laddare konfigurerad för DIRS och APP_DIRS

• '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.

Standardkonfigurationen hålls avsiktligt till ett minimum. Om en mall renderas med en begäran (t.ex. när du använder render()), lägger Jinja2-backend till globalerna request, csrf_input och csrf_token till kontexten. Bortsett från det skapar denna backend inte en Django-flavored miljö. Den känner inte till Django-filter och taggar. För att kunna använda Django-specifika API:er måste du konfigurera dem i miljön.

Du kan till exempel skapa myproject/jinja2.py med följande innehåll:

from django.templatetags.static import static
from django.urls import reverse

from jinja2 import Environment


def environment(**options):
    env = Environment(**options)
    env.globals.update(
        {
            "static": static,
            "url": reverse,
        }
    )
    return env

och ställa in alternativet 'environment' till 'myproject.jinja2.environment'.

Då kan du använda följande konstruktioner i Jinja2-mallar:

<img src="{{ static('path/to/company-logo.png') }}" alt="Company Logo">

<a href="{{ url('admin:index') }}">Administration</a>

Begreppen 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.