Le langage de gabarit de Django : pour les programmeurs Python¶

Variables et sous-éléments¶

Les noms de variables peuvent contenir des lettres (A-Z), des chiffres (0-9), des soulignements et des points (mais elles ne peuvent pas commencer par un soulignement).

Les points ont une signification particulière dans le rendu des gabarits. Un point dans un nom de variable indique l’accès à un sous-élément. Plus précisément, lorsque le système de gabarit voit un point dans un nom de variable, il recherche des sous-éléments dans cet ordre :

• Accès dictionnaire. Exemple : foo["bar"]
• Accès attribut. Exemple : foo.bar
• Accès par index de liste. Exemple : foo[bar]

Notez que « bar » dans une expression de gabarit comme {{ foo.bar }} est interprété comme une chaîne littérale et même si une variable « bar » existe dans le contexte du gabarit, elle ne sera pas appelée.

Le système de gabarits utilise le premier accès qui fonctionne. C’est une logique de court-circuit. Voici quelques exemples :

>>> from django.template import Context, Template
>>> t = Template("My name is {{ person.first_name }}.")
>>> d = {"person": {"first_name": "Joe", "last_name": "Johnson"}}
>>> t.render(Context(d))
"My name is Joe."

>>> class PersonClass:
...     pass
...
>>> p = PersonClass()
>>> p.first_name = "Ron"
>>> p.last_name = "Nasty"
>>> t.render(Context({"person": p}))
"My name is Ron."

>>> t = Template("The first stooge in the list is {{ stooges.0 }}.")
>>> c = Context({"stooges": ["Larry", "Curly", "Moe"]})
>>> t.render(c)
"The first stooge in the list is Larry."

Si un élément de la variable est un objet exécutable, le système de gabarits essaye de l’appeler. Exemple :

>>> class PersonClass2:
...     def name(self):
...         return "Samantha"
...
>>> t = Template("My name is {{ person.name }}.")
>>> t.render(Context({"person": PersonClass2}))
"My name is Samantha."

Les variables exécutables sont légèrement plus complexes que les variables qui ne demandent que des accès directs. Voici quelques éléments à garder en tête :

• Si la variable génère une exception quand elle est appelée, celle-ci est propagée, sauf si l’exception possède un attribut silent_variable_failure valant True. Dans ce dernier cas, la variable produira une chaîne équivalente au contenu de l’option de configuration string_if_invalid du moteur (chaîne vide par défaut). Exemple :

  >>> t = Template("My name is {{ person.first_name }}.")
  >>> class PersonClass3:
  ...     def first_name(self):
  ...         raise AssertionError("foo")
  ...
  >>> p = PersonClass3()
  >>> t.render(Context({"person": p}))
  Traceback (most recent call last):
  ...
  AssertionError: foo
  
  >>> class SilentAssertionError(Exception):
  ...     silent_variable_failure = True
  ...
  >>> class PersonClass4:
  ...     def first_name(self):
  ...         raise SilentAssertionError
  ...
  >>> p = PersonClass4()
  >>> t.render(Context({"person": p}))
  "My name is ."
  

  Notez que django.core.exceptions.ObjectDoesNotExist, qui est la classe de base de toutes les exceptions DoesNotExist de l’API de base de données de Django, contient silent_variable_failure = True. Ainsi, si vous utilisez les gabarits de Django avec des objets modèles de Django, toute exception DoesNotExist échoue silencieusement.

• Une variable ne peut être appelée que si elle ne demande pas de paramètre. Sinon le système renvoie la valeur de l’option string_if_invalid du moteur.

• Des effets de bord peuvent se produire lors de l’appel à certaines variables et il serait insensé ou sécuritairement désastreux de permettre au système de gabarits d’y accéder.

  Un bon exemple est la méthode delete() de chaque objet modèle de Django. Le système de gabarits ne devrait pas permettre de faire quelque chose comme :

  I will now delete this valuable data. {{ data.delete }}
  

  Pour empêcher cela, définissez un attribut alters_data sur la variable exécutable. Le système de gabarits n’appellera pas une variable si elle contient alters_data=True et la remplace plutôt par le contenu de string_if_invalid, sans conditions. Les méthodes générées dynamiquement delete() et save() sur les objets modèles de Django reçoivent automatiquement alters_data=True. Exemple :

  def sensitive_function(self):
      self.database_record.delete()
  
  
  sensitive_function.alters_data = True
  

• Vous pouvez parfois avoir envie de désactiver cette fonctionnalité pour d’autres raisons, et dire au système de gabarits de ne pas interpréter une variable, peu importe le contexte. Pour ce faire, il faut définir un attribut do_not_call_in_templates sur la variable exécutable, avec la valeur True. Le système de gabarits va alors considérer que la variable ne peut pas être appelée (ce qui permet par exemple d’accéder aux attributs de l’objet exécutable).

Traitement des variables non valides¶

Généralement, si une variable n’existe pas, le système des gabarits insère la valeur de l’option de configuration string_if_invalid du moteur, qui vaut '' (chaîne vide) par défaut.

Les filtres appliqués à une variable non valide ne seront appliqués que si string_if_invalid est défini à '' (la chaîne vide). Si string_if_invalid est défini à une autre valeur, les filtres de variable seront ignorés.

Ce comportement est légèrement différent pour les balises de gabarit if, for et regroup. Si une variable non valide est fournie à l’une de ces balises de gabarit, la variable sera interprétée comme None. Les filtres sont toujours appliqués aux variables non valides dans ces balises de gabarit.

Si string_if_invalid contient un substituant '%s', ce dernier sera remplacé par le nom de la variable non valide.

Variables intégrées¶

Tous les contextes contiennent True, False et None. Comme on peut s’y attendre, ces variables correspondent aux objets Python équivalents.

Restrictions avec les chaînes littérales¶

Le langage de gabarit de Django ne possède pas de moyen pour échapper les caractères utilisés pour sa propre syntaxe. Par exemple, la balise templatetag est indispensable pour afficher des séquences de caractères comme {% ou %}.

Un problème similaire survient lorsqu’il s’agit d’inclure ces séquences dans les paramètres d’un filtre ou d’une balise. Par exemple, lors de l’analyse d’un bloc de balise, l’analyseur de gabarit de Django cherche la première occurrence de %} après un {%. Cela empêche de pouvoir utiliser "%}" dans une chaîne littérale. Par exemple, une exception TemplateSyntaxError est générée pour les expressions suivantes :

{% include "template.html" tvar="Some string literal with %} in it." %}

{% with tvar="Some string literal with %} in it." %}{% endwith %}

La même problématique est révélée quand on utilise une séquence réservée dans les paramètres d’un filtre :

{{ some.variable|default:"}}" }}

Si vous avez besoin d’utiliser des chaînes qui contiennent ces séquences, vous devez les stocker dans des variables de gabarit ou utiliser une balise ou un filtre personnalisé pour détourner cette restriction.

Utilisation de RequestContext¶

class RequestContext(request, dict_=None, processors=None)¶

Django contient une classe Context spéciale, django.template.RequestContext, qui se comporte légèrement différemment de l’objet django.template.Context normal. La première différence est qu’elle demande un objet HttpRequest comme premier paramètre. Par exemple :

c = RequestContext(
    request,
    {
        "foo": "bar",
    },
)

La seconde différence est qu’elle remplit automatiquement le contexte avec quelques variables, en fonction de l’option de configuration context_processors du moteur.

L’option context_processors est une liste d’objets exécutables appelés processeurs de contexte qui acceptent un objet requête en paramètre et renvoient un dictionnaire d’éléments à fusionner dans le contexte. Dans le fichier de réglages généré par défaut, le moteur de gabarit par défaut contient les processeurs de contexte suivants :

[
    "django.template.context_processors.debug",
    "django.template.context_processors.request",
    "django.contrib.auth.context_processors.auth",
    "django.contrib.messages.context_processors.messages",
]

En plus de ce contenu, RequestContext active toujours 'django.template.context_processors.csrf'. Il s’agit d’un processeur de contexte lié à la sécurité exigé par l’application d’administration ainsi que d’autres applications contribuées. Il est volontairement ajouté de force pour qu’il ne puisse pas être enlevé par une erreur de configuration dans l’option context_processors.

Chaque processeur est appliqué successivement. Cela signifie que si un processeur ajoute une variable au contexte et que le processeur suivant ajoute une variable de même nom, la seconde écrase la première. Les processeurs par défaut sont présentés ci-dessous.

from django.template import RequestContext

request_context = RequestContext(request)
request_context.push({"my_name": "Adrian"})

Il est également possible de donner à RequestContext une liste de processeurs supplémentaires en utilisant le troisième paramètre positionnel facultatif, processors. Dans cet exemple, l’instance RequestContext reçoit une variable ip_address:

from django.http import HttpResponse
from django.template import RequestContext, Template


def ip_address_processor(request):
    return {"ip_address": request.META["REMOTE_ADDR"]}


def client_ip_view(request):
    template = Template("{{ title }}: {{ ip_address }}")
    context = RequestContext(
        request,
        {
            "title": "Your IP Address",
        },
        [ip_address_processor],
    )
    return HttpResponse(template.render(context))

Processeurs de contexte de gabarit intégrés¶

Voici ce que font chacun des processeurs de contexte intégrés :

Écriture de son propre processeur de contexte¶

Un processeur de contexte possède une interface simple : il s’agit d’une fonction Python acceptant un paramètre, un objet HttpRequest, et renvoyant un dictionnaire qui est ensuite ajouté au contexte de gabarit.

Par exemple, pour ajouter le réglage DEFAULT_FROM_EMAIL à tous les contextes

from django.conf import settings


def from_email(request):
    return {
        "DEFAULT_FROM_EMAIL": settings.DEFAULT_FROM_EMAIL,
    }

Les processeurs de contexte personnalisés peuvent se trouver n’importe où dans le code. Tout ce que Django demande, c’est que l’option 'context_processors' du réglage TEMPLATES (ou le paramètre context_processors d’un moteur Engine si vous l’utilisez directement) contienne le chemin vers le processeur personnalisé.

L’option DIRS¶

Indiquez à Django quels sont vos répertoires de gabarits en utilisant l’option DIRS du réglage TEMPLATES dans votre fichier de réglages, ou le paramètre dirs de Engine. Il devrait contenir une liste de chaînes contenant les chemins complets vers les répertoires de gabarits :

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [
            "/home/html/templates/lawrence.com",
            "/home/html/templates/default",
        ],
    },
]

Les gabarits peuvent se trouver n’importe où, pour autant que leur emplacement soit lisible par le serveur web. Leur extension est également à votre bon plaisir, .html, .txt, ou même sans extension du tout.

Notez que ces chemins doivent utiliser les barres obliques de style Unix, même avec Windows.

Types de chargeurs¶

Par défaut, Django utilise un chargeur de gabarit basé sur le système de fichiers, mais il existe également quelques autres chargeurs de gabarit, qui savent comment charger des gabarits à partir d’autres sources.

Certains de ces autres chargeurs sont désactivés par défaut, mais vous pouvez les activer en ajoutant une option 'loaders' à votre moteur DjangoTemplates dans le réglage TEMPLATES ou en transmettant un paramètre loaders à Engine. loaders doit contenir une liste de chaînes ou de tuples, où chaque élément représente une classe de chargeur de gabarit. Voici les chargeurs de gabarit que Django propose :

django.template.loaders.filesystem.Loader

class filesystem.Loader¶

Charge les gabarits à partir du système de fichiers, en fonction de DIRS.

Ce chargeur est actif par défaut. Cependant, il ne trouvera aucun gabarit tant que vous n’aurez pas défini DIRS à une liste non vide :

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
    }
]

Il est aussi possible de surcharger 'DIRS' et de définir des répertoires spécifiques à un chargeur basé sur le système de fichiers :

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "OPTIONS": {
            "loaders": [
                (
                    "django.template.loaders.filesystem.Loader",
                    [BASE_DIR / "templates"],
                ),
            ],
        },
    }
]

django.template.loaders.app_directories.Loader

class app_directories.Loader¶

Charge les gabarits à partir des dossiers d’applications Django sur le système de fichiers. Pour chaque application dans INSTALLED_APPS, le chargeur cherche un sous-répertoire nommé templates. S’il le trouve, Django recherche les gabarits dans ce répertoire.

Cela signifie que vous pouvez stocker les gabarits à l’intérieur des différentes applications. Cela facilite également la distribution des applications Django dotées de gabarits par défaut.

Par exemple, avec ce réglage :

INSTALLED_APPS = ["myproject.polls", "myproject.music"]

…get_template('foo.html') recherche foo.html dans ces répertoires, dans l’ordre :

• /chemin/vers/myproject/polls/templates/
• /chemin/vers/myproject/music/templates/

… et utilise le premier qu’il trouve.

L’ordre de INSTALLED_APPS est important ! Par exemple, si vous souhaitez personnaliser l’administration de Django, il peut être utile de surcharger le gabarit admin/base_site.html standard de django.contrib.admin par votre propre admin/base_site.html dans myproject.polls. Vous devez alors vous assurer que myproject.polls apparaisse avant django.contrib.admin dans INSTALLED_APPS, sinon django.contrib.admin sera chargé en premier et votre gabarit sera ignoré.

Notez que le chargeur effectue une optimisation lors de son premier lancement : il place en cache une liste des paquets INSTALLED_APPS qui possèdent un sous-répertoire templates.

Vous pouvez activer ce chargeur en définissant APP_DIRS à True:

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "APP_DIRS": True,
    }
]

django.template.loaders.cached.Loader

class cached.Loader¶

Même si le système des gabarits de Django est plutôt rapide, s’il doit lire et compiler vos gabarits lors de chaque rendu, la surcharge occasionnée peut être conséquente.

Le chargeur de gabarits « en cache » est configuré en lui donnant une liste d’autres chargeurs qu’il va encapsuler. Les chargeurs encapsulés sont utilisés pour retrouver les gabarits inconnus la première fois qu’ils sont référencés. Le chargeur « en cache » stocke ensuite l’objet Template compilé en mémoire. Cette instance mise en cache est renvoyée lors de chaque nouvelle requête de chargement de ce même gabarit.

Ce chargeur est automatiquement activé quand OPTIONS['loaders'] n’est pas défini.

Il est possible d’activer manuellement le cache de gabarits avec des chargeurs de gabarit personnalisés en utilisant des réglages comme ceci :

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "OPTIONS": {
            "loaders": [
                (
                    "django.template.loaders.cached.Loader",
                    [
                        "django.template.loaders.filesystem.Loader",
                        "django.template.loaders.app_directories.Loader",
                        "path.to.custom.Loader",
                    ],
                ),
            ],
        },
    }
]

Note

Toutes les balises de gabarit intégrées à Django peuvent être utilisées sans problème avec le chargeur « en cache », mais si vous utilisez des balises de gabarit personnalisées provenant de paquets externes ou que vous avez écrites vous-même, il est nécessaire de vérifier que l’implémentation des objets Node de chaque balise respecte la concurrence (« thread-safe »). Pour plus d’informations, consultez les indications sur la concurrence entre fils d’exécution dans les balises de gabarit.

django.template.loaders.locmem.Loader

class locmem.Loader¶

Charge des gabarits à partir d’un dictionnaire Python. Utile pour les tests.

Ce chargeur prend un dictionnaire de gabarits comme premier paramètre :

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "OPTIONS": {
            "loaders": [
                (
                    "django.template.loaders.locmem.Loader",
                    {
                        "index.html": "content here",
                    },
                ),
            ],
        },
    }
]

Ce chargeur est désactivé par défaut.

Django utilise les chargeurs de gabarit dans l’ordre de leur apparition dans l’option 'loaders'. Il utilise chaque chargeur jusqu’à ce qu’il trouve une correspondance.

Méthodes des chargeurs¶

class Loader¶

Charge des gabarits à partir d’une source donnée, telle que le système de fichier ou une base de données.

get_template_sources(template_name)¶

Une méthode acceptant un nom de gabarit template_name et renvoyant une à une des instances Origin pour chaque source possible.

Par exemple, le chargeur système de fichiers pourrait recevoir 'index.html' comme paramètre template_name. Cette méthode produirait des origines pour le chemin complet de index.html tel qu’il devrait apparaître dans chaque répertoire de gabarits que le chargeur inspecte.

La méthode n’a pas besoin de vérifier que le gabarit existe pour un chemin donné, mais elle doit s’assurer que le chemin est valide. Par exemple, le chargeur système de fichiers doit s’assurer que le chemin se trouve bien dans un répertoire de gabarits valide.

get_contents(origin)¶

Renvoie le contenu d’un gabarit en fonction d’une instance Origin donnée.

C’est ici qu’un chargeur système de fichiers lit le contenu à partir du système de fichiers, ou qu’un chargeur base de données lit à partir de la base de données. Si aucun gabarit existant ne correspond, une erreur TemplateDoesNotExist doit être générée.

get_template(template_name, skip=None)¶

Renvoie un objet Template correspondant à template_name en passant en boucle ce que get_template_sources() renvoie et en appelant get_contents(). Le premier gabarit trouvé est renvoyé. Si aucun n’est trouvé, une exception TemplateDoesNotExist est générée.

Le paramètre facultatif skip est une liste d’origines à ignorer lors de l’extension des gabarits. Cela permet à des gabarits d’étendre d’autres gabarits du même nom. Une autre utilité est d’éviter les erreurs de récursion.

En général, il est suffisant que les chargeurs de gabarit personnalisés définissent get_template_sources() et get_contents(). get_template() n’a généralement pas besoin d’être surchargée.