# Django 5.2.8 documentation

# Mallar

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.

Ett 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

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

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

Av historiska skäl finns både det generiska stödet för mallmotorer och implementeringen av Djangos mallspråk i namnrymden `django.template`.

Varning

Mallsystemet är inte säkert mot otillförlitliga mallförfattare. En webbplats bör till exempel inte tillåta sina användare att skapa egna mallar, eftersom mallförfattare kan utföra saker som XSS-attacker och komma åt egenskaper hos mallvariabler som kan innehålla känslig information.

## Djangos mallspråk

### Syntax

Om detta avsnitt

Detta är en översikt över Djangos mallspråks syntax. För detaljer se språksyntaxreferens.

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.

#### Variabler

En variabel matar ut ett värde från kontexten, som är ett diktatliknande objekt som mappar nycklar till värden.

Variabler omges av `{{` och `}}` så här:

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

Med en kontext av `{'first_name': 'John', 'last_name': 'Doe'}`, renderar denna mall till:

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

Dictionary lookup, attribute lookup och list-index lookup implementeras med en punktnotation:

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

Om en variabel motsvarar en anropsbar variabel kommer mallsystemet att anropa den utan argument och använda resultatet istället för den anropsbara variabeln.

#### Taggar

Taggar ger godtycklig logik i renderingsprocessen.

Denna definition är avsiktligt vag. En tagg kan t.ex. mata ut innehåll, fungera som en kontrollstruktur, t.ex. en ”if”-sats eller en ”for”-loop, hämta innehåll från en databas eller till och med ge åtkomst till andra malltaggar.

Taggar omges av `{%` och `%}` på det här sättet:

    {% csrf_token %}

De flesta taggar accepterar argument:

    {% cycle 'odd' 'even' %}

Vissa taggar kräver en start- och en sluttagg:

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

En referens av inbyggda taggar finns tillgänglig liksom instruktioner för att skriva egna taggar.

#### Filter

Filter omvandlar värdena för variabler och taggargument.

De ser ut så här:

    {{ django|title }}

Med en kontext av `{'django': 'webbramverket för perfektionister med deadlines'}`, renderar denna mall till:

    The Web Framework For Perfectionists With Deadlines

Vissa filter tar ett argument:

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

En referens av inbyggda filter finns tillgänglig liksom instruktioner för att skriva egna filter.

#### Kommentarer

Kommentarer ser ut så här:

    {# this won't be rendered #}

En `{% comment %}`-tagg ger kommentarer på flera rader.

### Komponenter

Om detta avsnitt

Detta är en översikt över Django mallspråkets API:er. För detaljer se API-referens.

#### Motor

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

#### Mall

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

#### Kontext

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

#### Lastare

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.

#### Processorer i sammanhanget

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

Django tillhandahåller många inbyggda kontextprocessorer, och du kan också implementera dina egna ytterligare kontextprocessorer.

## Stöd för mallmotorer

### Konfiguration

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

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

get_template(template_name, using=None)

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

  Partial loading:

  When using the `DjangoTemplates` backend, a specific fragment from a template can be loaded by name. This fragment should have been previously defined using the `partialdef` template tag:

      from django.template.loader import get_template

      # Load an entire template.
      template = get_template("template.html")

      # Load a specific fragment from a template.
      partial = get_template("template.html#partial_name")

  When loading a partial, the returned object behaves like a regular `Template` but contains only the partial’s content.

  See Template partials for more information about defining and using template fragments.

  Changed in Django 6.0:

  Support for loading template partials when using the `DjangoTemplates` backend was added.

select_template(template_name_list, using=None)

  `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)

  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)

  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)

  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.

Använd `django.template.loader.select_template()` för mer flexibilitet

You can use `select_template()` for flexible template loading. For example, if you’ve written a news story and want some stories to have custom templates, use something like `select_template(['story_%s_detail.html' % story.id, 'story_detail.html'])`. That’ll allow you to use a custom template for an individual story, with a fallback template for stories that don’t have custom templates.

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)

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

      from django.template.loader import render_to_string

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

See also the `render()` shortcut which calls `render_to_string()` and feeds the result into an `HttpResponse` suitable for returning from a view.

Slutligen kan du använda konfigurerade motorer direkt:

engines

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

      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 backends

class DjangoTemplates

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

  Varning

  Sätt den bara till `False` om du renderar icke-HTML-mallar!

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

      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:

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

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

class Jinja2

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.

  Det är inte lämpligt att använda kontextprocessorer med Jinja2-mallar.

  Kontextprocessorer är användbara med Django-mallar eftersom Django-mallar inte stöder anrop av funktioner med argument. Eftersom Jinja2 inte har den begränsningen rekommenderas det att du placerar den funktion som du vill använda som en kontextprocessor i de globala variabler som är tillgängliga för mallen med hjälp av `jinja2.Environment` enligt beskrivningen nedan. Du kan sedan anropa den funktionen i mallen:

      {{ function(request) }}

  Vissa Django-mallars kontextprocessorer returnerar ett fast värde. För Jinja2-mallar är detta lager av indirektion inte nödvändigt eftersom du kan lägga till konstanter direkt i `jinja2.Environment`.

  Det ursprungliga användningsfallet för att lägga till kontextprocessorer för Jinja2 innebar:

  - Utföra en dyr beräkning som beror på begäran.

  - Behöver resultatet i varje mall.

  - Använda resultatet flera gånger i varje mall.

  Om inte alla dessa villkor är uppfyllda är det mer i linje med designen av Jinja2 att skicka en funktion till mallen.

The default configuration is purposefully kept to a minimum. If a template is rendered with a request (e.g. when using `render()`), the `Jinja2` backend adds the globals `request`, `csrf_input`, and `csrf_token` to the context. Apart from that, this backend doesn’t create a Django-flavored environment. It doesn’t know about Django filters and tags. In order to use Django-specific APIs, you must configure them into the environment.

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.