Le livre de

Revue du langage de gabarit

Tout d’abord, révisons rapidement quelques termes introduits au chapitre 4 :

• Un gabarit est un document texte, ou une chaîne Python standard, qui est balisé en utilisant le langage de gabarit de Django. Un gabarit peut contenir des balises de blocs et des variables.

• Une balise de bloc est un symbole qui fait quelquechose à l’intérieur d’un gabarit. Cette définition est délibérément vague. Par exemple, une balise de bloc peut produire du contenu, servir de structure de contrôle (une instruction if ou une boucle for), récupèrer du contenu depuis une base de données, ou permettre l’accès à d’autre balises de gabarit.

  Les balises de bloc sont encadrées par {% et %} :

  {% if is_logged_in %}
    Thanks for logging in!
  {% else %}
    Please log in.
  {% endif %}
  

• Une variable est un symbole à l’intérieur d’un gabarit qui produit une valeur.

  les balises de variable sont encadrées par {{ et }}:

  Mon prénom est {{ prenom }}. Mon nom est {{ nom }}.
  

• Un contexte est une correspondance nom -> valeur (similaire a un dictionnaire en Python) qui est transmis à un template.

• Un gabarit retourne un contexte en remplaçant les «trous» des variables par les valeur provenant du contexte et exécute toutes les balises de bloc.

Pour plus de détails sur les bases concernant ces termes, référez vous au chapitre 4

Le reste de ce chapitre aborde les manières d’étendre le moteur de gabarit. Mais tout d’abord, regardons rapidement la mécanique interne laissée de côté au chapitre 4 pour des raisons de simplicité.

RequestContext and Context Processors

Lors du rendu d’un gabarit, vous avez besoin d’un contexte. D’habitude il s’agit d’une instance de django.template.Context, mais Django fournit aussi une sous classe spéciale, django.template.RequestContext, qui agit légérement différement. RequestContext ajoute tout un tas de variables à votre contexte de gabarit par défaut — pensez à l’objet HttpRequest ou aux informations au sujet de l’utilisateur actuellement authentifié.

Utilisez RequestContext lorsque vous ne voulez pas avoir à spécifier le même jeu de variables dans une série de gabarits. Par exemple, considérez ces quatres vues :

from django.template import loader, Context

def view_1(request):
    # ...
    t = loader.get_template('template1.html')
    c = Context({
        'app': 'My app',
        'user': request.user,
        'ip_address': request.META['REMOTE_ADDR'],
        'message': 'I am view 1.'
    })
    return t.render(c)

def view_2(request):
    # ...
    t = loader.get_template('template2.html')
    c = Context({
        'app': 'My app',
        'user': request.user,
        'ip_address': request.META['REMOTE_ADDR'],
        'message': 'I am the second view.'
    })
    return t.render(c)

def view_3(request):
# ...
    t = loader.get_template('template3.html')
    c = Context({
        'app': 'My app',
        'user': request.user,
        'ip_address': request.META['REMOTE_ADDR'],
        'message': 'I am the third view.'
    })
    return t.render(c)

def view_4(request):
    # ...
    t = loader.get_template('template4.html')
    c = Context({
        'app': 'My app',
        'user': request.user,
        'ip_address': request.META['REMOTE_ADDR'],
        'message': 'I am the fourth view.'
    })
    return t.render(c)

(Notez que nous n’utilisons pas délibérément le raccourcis render_to_response() dans ces exemples — nous chargeons manuellement les gabarits, construisons les objets de contexte et assurons le rendu des gabarits. Nous allons «épeler» toutes les étapes dans un but de clareté)

Chacune des vues transmet les mêmes trois variables — app, user et ip_address — à son gabarit. Ne serait-il pas sympathique de pouvoir supprimer cette redondance ?

RequestContext et les processeurs de contexte ont été crées pour résoudre ce problème. Les processeurs de contexte vous laissent préciser un nombre de variables qui est fixé automatiquement pour chaque contexte — sans avoir à spécifier les variables dans chaque appel à render_to_response(). Vous n’avez plus qu’à utiliser RequestContext à la place de Context lorsque vous retounrez un gabarit.

L’approche la plus «bas niveau» pour utiliser les processeurs de contexte est de créer quelques processeurs puis de les passer à RequestContext. Voici comment les exemples précédents peuvent être écrit avec l’aide des processeurs de contexte :

from django.template import loader, RequestContext

def custom_proc(request):
    "A context processor that provides 'app', 'user' and
    'ip_address'."
    return {
        'app': 'My app',
        'user': request.user,
        'ip_address': request.META['REMOTE_ADDR']
    }

def view_1(request):
    # ...
    t = loader.get_template('template1.html')
    c = RequestContext(request, {'message': 'I am view 1.'},
            processors=[custom_proc])
    return t.render(c)

def view_2(request):
    # ...
    t = loader.get_template('template2.html')
    c = RequestContext(request, {'message': 'I am the second
    view.'},
            processors=[custom_proc])
    return t.render(c)

def view_3(request):
    # ...
    t = loader.get_template('template3.html')
    c = RequestContext(request, {'message': 'I am the third
    view.'},
            processors=[custom_proc])
    return t.render(c)

def view_4(request):
    # ...
    t = loader.get_template('template4.html')
    c = RequestContext(request, {'message': 'I am the fourth
    view.'},
            processors=[custom_proc])
    return t.render(c)

Parcourons ce code :

• Pour commencer, nous définissons une fonction custom_proc. C’est un processeur de contexte — il prends un objet HttpRequest et retourne un dictionnaire de varaibles à utiliser dans le contexte du gabarit. C’est tout ce qu’il fait.
• Nous avons modifiés les quatres fonctions de la vue afin d’utiliser RequestContext à la place de Context. Il y a deux différences dans la méthode de construction du contexte. Dans la première, RequestContext nécessite que le premier argument soit un objet HttpRequest - celui qui était transmis à la fonction vue en premier lieu (request). dans la seconde, RequestContext prends un argument processors optionnel, qui est une liste ou un tuple des fonctions processeurs de contexte à utiliser. Ici, nous passons custom_proc, le processeur personnalisé définit ci-dessus.
• Les vues n’ont plus besoin d’inclure app, user ou ip_address dans la construction du contexte, parceque ceux-ci in its context construction, because those are provided by custom_proc.
• Chaque vue conserve la souplesse d’introduire n’importe quelles variables de gabarit personnalisées dont elle aurait besoin. Dans cet exemple, la variable de gabarit message est différente dans chaque vue.

Au chapitre 4, nous avons introduit le raccourcis render_to_response(), qui vous évite d’avoir à appeler loader.get_template(), puis crée un Context, pour ensuite appeler la méthode render() sur le gabarit. De façon à démontrer le fonctionnement bas niveau des processeurs de contexte, l’exemple ci-desssous n’utilise pas render_to_response(). Il est possible — et préférabel — d’utiliser les processeurs de contexte avec render_to_response(). Faîtes cela avec l’argument context_instance, comme ceci :

from django.shortcuts import render_to_response
from django.template import RequestContext

def custom_proc(request):
    "A context processor that provides 'app', 'user' and
    'ip_address'."
    return {
        'app': 'My app',
        'user': request.user,
        'ip_address': request.META['REMOTE_ADDR']
    }

def view_1(request):
    # ...
    return render_to_response('template1.html',
        {'message': 'I am view 1.'},
        context_instance=RequestContext(request,
        processors=[custom_proc]))

def view_2(request):
    # ...
    return render_to_response('template2.html',
        {'message': 'I am the second view.'},
        context_instance=RequestContext(request,
        processors=[custom_proc]))

def view_3(request):
    # ...
    return render_to_response('template3.html',
        {'message': 'I am the third view.'},
        context_instance=RequestContext(request,
        processors=[custom_proc]))

def view_4(request):
    # ...
    return render_to_response('template4.html',
        {'message': 'I am the fourth view.'},
        context_instance=RequestContext(request,
        processors=[custom_proc]))

Ici, nous avons réduit le code du rendu de gabarit de chaque vues à une seule ligne (emballée).

C’est une amélioration mais, en évaluant la concision de ce code, nous devons admettre que nous ne semble pas loin d’atteindre l’extrême inverse ?

Nous avons supprimé la redondance des données (nos variables de gabarit) au prix de l’ajout de redondance dans le code (dans l’appel à processors). Utiliser les processeurs de contexte ne vous épargne pas beaucoup de saisie si vous devez tout le temps taper processors.

Pour cette raison, Django fournit un support globale pour les processeurs de contexte. Le paramètre TEMPLATE_CONTEXT_PROCESSORS désigne les processeurs de contexte qui doivent toujours êtres appliqués à RequestContext. Ceci supprime le besoin d’avoir à préciser processors à chaque utilisation de RequestContext.

Par défaut, TEMPLATE_CONTEXT_PROCESSORS est réglé comme suit :

TEMPLATE_CONTEXT_PROCESSORS = (
    'django.core.context_processors.auth',
    'django.core.context_processors.debug',
    'django.core.context_processors.i18n',
    'django.core.context_processors.media',
)

Ce réglage est un tuple de «callables» (ndt: «d’appellables») qui utilisent la même inteface que notre fonction custom_proc à venir — les fonctions qui prennent un objet requête pour argument et retournent un dictionnaire d’éléments injecté dans le contexte. Notez que les valeurs dans TEMPLATE_CONTEXT_PROCESSORS sont des chaînes, ce qui signifie que les processeurs doivent être quelquepart dans votre Python path (vous pouvez donc les consulter depuis le paramétre).

Chaque processeur est appliqué dans l’ordre. Ainsi, si un processeur ajoute une variable au contexte et qu’un second processeur ajoute une variable du même nom, la seconde écrasera la première.

Django fournit de nombreux processeurs de contexte simples, y compris ceux qui sont activés par défaut :

Au cœur du chargement de gabarit

Généralement, vous stockerez vos gexabarits dans des fichiers de votre système, mais vous pouvez utiliser des chargeurs de gabarit personnalisés pour le chargement des gabarits depuis d’autres sources.

Django propose deux façons de charger les gabarits:

• django.template.loader.get_template(template_name): get_template retourne le gabarit compilé (un objet Template) pour le gabarit d’un nom donné. Si le gabarit n’existe pas, une exception TemplateDoesNotExist sera levée.
• django.template.loader.select_template(template_name_list): select_template est similaire à get_template, sauf qu’elle prends une liste de noms de gabarit. De la liste, elle retourne le premier gabarit qui existe. Si aucun des gabarits n’existe, une exception TemplateDoesNotExist sera levée.

Comme nous l’avons vu au chapitre 4, chacun de ces fonctions utilise par défaut votre paramètre TEMPLATE_DIRS pour charger les gabarits. En interne, cependant, ces fonctions délèguent en fait à un chargeur de gabarit les modifications lourdes.

Certains chargeurs sont désactivés par défaut, mais vous pouvez les activer en éditant le paramètre TEMPLATE_LOADERS. TEMPLATE_LOADERS doit être un tuple de chaînes, où chaque chaîne représente un chargeur de gabarit. Ces chargeurs de gabarit sont fournis avec Django:

• django.template.loaders.filesystem.load_template_source: ce chargeur charge les gabarits depuis le système de fichier, selon TEMPLATE_DIRS. C’est activé par défaut.

• django.template.loaders.app_directories.load_template_source: Ce chargeur charge les gabarits depuis les applications Django sur le système de fichier. Pour chaque application dans INSTALLED_APPS, le chargeur cherche un sous-répertoire templates. Si le répertoire existe, Django y recherche des gabarits.

  Ceci signifie que vous pouvez stocker des gabarits avec vos applications individuelles, facilitant la distribution des applications Django avec des gabarits par défaut. Par exemple, si INSTALLED_APPS contient ('myproject.polls', 'myproject.music'), alors get_template('foo.html') cherchera des gabarits dans cet ordre :

  • /path/to/myproject/polls/templates/foo.html
  • /path/to/myproject/music/templates/foo.html

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

  Ce chargeur est activé par défaut

• django.template.loaders.eggs.load_template_source: ce chargeur est semblable à app_directories, mis à part qu’il charge le gabarit depuis les oeufs Python plutôt que depuis le système de fichier. Ce chargeur est désactivé par défaut; vous devrez l’activer si vous utilisz des oeufs pour distribuer votre application.

Django utilise le chargeur de gabarit selon le paramètre TEMPLATE_LOADERS. Il utilise chaque chargeur jusqu’à ce qu’un chargeur trouve une correspondance.

Étendre le système de gabarit

À présent que vous comprenez un peu plus la mécanique du système de gabarit, voyons comment étendre le système avec du code personnalisé.

La personnalisation de gabarit vient principalement sous la forme de balises de gabarit personnalisées ou de filtres. Bien que le langage de gabarit de Django propose de nombreuses balises et filtres embarqués, vous construirez probablement vos propres bibliothèques de balises et de filtres qui répondent à vos besoins personnels. Heureusement, il est assez facile de définir votre propre fonctionalité.

from django import template

register = template.Library()

def cut(value, arg):
    "Removes all values of arg from the given string"
    return value.replace(arg, '')

{{ somevariable|cut:"0" }}

def lower(value): # Only one argument.
    "Converts a string into all lowercase"
    return value.lower()

register.filter('cut', cut)
register.filter('lower', lower)

@register.filter(name='cut')
def cut(value, arg):
    return value.replace(arg, '')

@register.filter
def lower(value):
    return value.lower()

from django import template

register = template.Library()

@register.filter(name='cut')
def cut(value, arg):
    return value.replace(arg, '')

<p>The time is {% current_time "%Y-%m-%d %I:%M %p" %}.</p>

from django import template

def do_current_time(parser, token):
    try:
        # split_contents() knows not to split quoted strings.
        tag_name, format_string = token.split_contents()
    except ValueError:
        msg = '%r tag requires a single argument' %
        token.contents[0]
        raise template.TemplateSyntaxError(msg)
    return CurrentTimeNode(format_string[1:-1])

import datetime

class CurrentTimeNode(template.Node):

    def __init__(self, format_string):
        self.format_string = format_string

    def render(self, context):
        now = datetime.datetime.now()
        return now.strftime(self.format_string)

register.tag('current_time', do_current_time)

@register.tag(name="current_time")
def do_current_time(parser, token):
    # ...

@register.tag
def shout(parser, token):
    # ...

class CurrentTimeNode2(template.Node):

    def __init__(self, format_string):
        self.format_string = format_string

    def render(self, context):
        now = datetime.datetime.now()
        context['current_time'] =
        now.strftime(self.format_string)
        return ''

{% current_time2 "%Y-%M-%d %I:%M %p" %}
<p>The time is {{ current_time }}.</p>

{% get_current_time "%Y-%M-%d %I:%M %p" as my_current_time %}
<p>The current time is {{ my_current_time }}.</p>

import re

class CurrentTimeNode3(template.Node):

    def __init__(self, format_string, var_name):
        self.format_string = format_string
        self.var_name = var_name

    def render(self, context):
        now = datetime.datetime.now()
        context[self.var_name] =
        now.strftime(self.format_string)
        return ''

def do_current_time(parser, token):
    # This version uses a regular expression to parse tag
    contents.
    try:
        # Splitting by None == splitting by spaces.
        tag_name, arg = token.contents.split(None, 1)
    except ValueError:
        msg = '%r tag requires arguments' % token.contents[0]
        raise template.TemplateSyntaxError(msg)

    m = re.search(r'(.*?) as (\w+)', arg)
    if m:
        fmt, var_name = m.groups()
    else:
        msg = '%r tag had invalid arguments' % tag_name
        raise template.TemplateSyntaxError(msg)

    if not (fmt[0] == fmt[-1] and fmt[0] in ('"', "'")):
        msg = "%r tag's argument should be in quotes" %
        tag_name
        raise template.TemplateSyntaxError(msg)

    return CurrentTimeNode3(fmt[1:-1], var_name)

def do_comment(parser, token):
    nodelist = parser.parse(('endcomment',))
    parser.delete_first_token()
    return CommentNode()

class CommentNode(template.Node):
    def render(self, context):
        return ''

{% upper %}
    This will appear in uppercase, {{ your_name }}.
{% endupper %}

 @register.tag
 def do_upper(parser, token):
     nodelist = parser.parse(('endupper',))
     parser.delete_first_token()
``DJANGO_SETTINGS_MODULE``     return UpperNode(nodelist)

 class UpperNode(template.Node):

     def __init__(self, nodelist):
         self.nodelist = nodelist

     def render(self, context):
         output = self.nodelist.render(context)
         return output.upper()

def current_time(format_string):
    return datetime.datetime.now().strftime(format_string)

register.simple_tag(current_time)

@register.simple_tag
def current_time(token):
    ...

{% show_results poll %}

<ul>
  <li>First choice</li>
  <li>Second choice</li>
  <li>Third choice</li>
</ul>

def show_books_for_author(author):
    books = author.book_set.all()
    return {'books': books}

<ul>
{% for book in books %}
    <li> {{ book }} </li>
{% endfor %}
</ul>

register.inclusion_tag('books/books_for_author.html')(show_books_for_author)

@register.inclusion_tag('books/books_for_author.html')
def show_books_for_author(show_books_for_author):
    ...

@register.inclusion_tag('link.html', takes_context=True)
def jump_link(context):
    return {
        'link': context['home_link'],
        'title': context['home_title'],
    }

Aller directement au <a href="{{ link }}">{{ title }}</a>.

{% jump_link %}

Écrire des chargeurs de gabarit personnalisés

Le chargeur de gabarit embarqué dans Django (décrit dans la section précédente «Au cœur du chargement de gabarit») couvrira généralement tous vos besoins en matière de chargement de gabarit, mais il est très facile d’écrire le votre si vous avez besoin d’une logique de chargement spécifique. Par exemple, vous pouvez charger des gabarits depuis une base de données, ou directement depuis un dépôt Subversion en utilisant la dépendance Subversion pour Python, ou (comme montré briévement) depuis une archive ZIP.

Un chargeur de gabarit — c’est à dire, chaque entrée dans le paramètre TEMPLATE_LOADERS — s’attend à être appelé avec cette interface:

load_template_source(template_name, template_dirs=None)

L’argument template_name est le nom du gabarit à charger (comme transmis à loader.get_template() ou loader.select_template()), et template_dirs est une liste optionnelle de répertoires à parcourir en lieu et place de TEMPLATE_DIRS.

Si un chargeur est capable de charger un gabarit avec succès, il doit retourner un tuple: (template_source, template_path). Ici, template_source est la chaîne de gabarit qui devra être compilée par le moteur de gabarit, et template_path est le chemin d’où fut chargé le gabarit. Ce chemin doit être affiché à l’utilisateur pour débugage, ainsi il doit rapidement identifer la provenance du gabarit chargé.

Si le chargeur est incapable de charger un gabarit, il doit lever django.template.TemplateDoesNotExist.

Chaque fonction de chargement doit avoir aussi un attribut de fonction is_usable. C’est un Booléen qui informe le moteur de gabarit de la disponibilité d’un chargeur dans l’installation actuelle de Python. Par exemple, le chargeur d’oeufs (qui est capable de charger des gabarits depuis des oeufs Python) fixe is_usable à False si le module pkg_ressources n’est pas installé, puisque pkg_ressources est nécessaire à la lecture des données depuis les oeufs.

Un exemple devrait aider )à clarifier tout ceci. Voici une fonction d’un chargeur de gabarit qui peut charger des gabarit depuis un fichier ZIP. Elle utilise un paramètre personnalisé, TEMPLATE_ZIP_FILES, comme chemin de recherche, au lieu de TEMPLATE_DIRS, et s’attends à ce que chaque élément sur ce chemin soit un fichier ZIP contenant des gabarits:

import zipfile
from django.conf import settings
from django.template import TemplateDoesNotExist

def load_template_source(template_name, template_dirs=None):
    """Template loader that loads templates from a ZIP file."""

    template_zipfiles = getattr(settings, "TEMPLATE_ZIP_FILES",
    [])

    # Try each ZIP file in TEMPLATE_ZIP_FILES.
    for fname in template_zipfiles:
        try:
            z = zipfile.ZipFile(fname)
            source = z.read(template_name)
        except (IOError, KeyError):
            continue
        z.close()
        # We found a template, so return the source.
        template_path = "%s:%s" % (fname, template_name)
        return (source, template_path)

    # If we reach here, the template couldn't be loaded
    raise TemplateDoesNotExist(template_name)

# This loader is always usable (since zipfile is included with
Python)
load_template_source.is_usable = True

Le seule étape qui reste si nous désirons utiliser ce chargeur est de l’ajouter au paramètre TEMPLATE_LOADERS. Si nous plaçons ce code dans un paquet appelé mysite.zip_loader, alors nous ajoutons mysite.zip_loader.load_template_source à TEMPLATE_LOADERS.

Utiliser la référence native au gabarit

L’interface d’administration de Django inclut une référence complète à toutes les balises de gabarit et filtres disponibles pour un site donné. Elle est destinée à être un outil que les développeurs de Django fournissent aux développeurs de gabarits. Pour le voir, rendez-vous dans l’interface d’administration et cliquez sur le lien Documentation en haut à droite de la page.

La référence est divisée en quatre sections: balises, filtres, modèles et vues. Les sections balises et filtres décrivent toutes les balises embarquées (en fait, les références balise et filtre du chapitre 4 proviennent directement de ces pages) tout comme toutes bibliothèques disponibles de balise ou de filtre personnalisés.

La page vues est la plus précieuse. Ici, haque URL de votre site possède une entrée séparée. Si la vue concernée inclu un docstring, un clique sur l’URL vous affichera:

• Le nom de la fonction vue qui génère cette vue
• Une courte description de ce que fait la vue
• Le contexte, ou une liste des variables disponibles dans le gabarit de la vue
• Le nom du ou des gabarits qui sont utilisés pour cette vue

Pour un exemple détaillé de la documentaton d’une vue, lisez le code source de la vue générique object_list, qui se trouve dans django/views/generic/list_detail.py.

Puisque les sites propulsés par Django utilisent habituellement des objets base de données, les pages des modèles décrivent chaque type d’objet du système, avec tous les champs disponibles sur cet objet.

Prises ensemble, les pages de documentation doivent vous indiquer toutes les balises, filtres, varaibles et objets disponibles dans un gabarit donné.

Configuration du système de gabarit en mode autonome

Note

Cette partie intéressera uniquement les personnes qui tentent d’utiliser le système de gabarit comme un composant de sortie vers une autre application. Si vous utilisez le système de gabarit comme composant d’une application Django, l’information détaillée ici ne vous concerne pas.

Normallement, Django chargera toute les informations de configuration dont il a besoin depuis son propre fichier de configuration par défaut, combiné avec les paramètres du module donné dans la variable d’environnement DJANGO_SETTINGS_MODULE. Mais si vous utilisez le système de gabarit indépendemment du reste de Django, l’approche par variable d’environnement n’est pas très pratique, parce que vous voudrez probablement configurer le système de gabarit dans la continuité du reste de votre application plutôt que d’avoir à gérer les fichiers de paramétrage et de pointer vers eux via les variables d’environnement.

Pour résoudre ce problème, vous devez utiliser l’option de configuration manuelle décrite entièrement dans l’annexe E. En résumé, vous devez importer les composants appropriés du système de gabarit, puis, avant même d’appeler l’une des fonctions de gabarit, appeler django.conf.settings.configure() avec tous les paramètres que vous désirez préciser.

Vous devriez au moins considérer les paramètres TEMPLATE_DIRS (si vous allez utiliser les chargeurs de gabarits), DEFAULT_CHARSET (même si le utf-8 par défaut est probablement correct), et TEMPLATE_DEBUG. Tous les paramètres disponibles sont détaillés à l’annexe E, et tout paramètre commençant par TEMPLATE_ est d’un intérêt évident.

Et ensuite ?

Jusqu’à présent, ce livre considérait que le contenu que vous affichiez était du HTML. Ce n’est pas une mauvaise hypothèse pour un livre qui traite du développement web, mais viendra le moment où vous voudrez utiliser Django pour retourner d’autres types de format de données.

Le chapitre suivant décrit la façon dont vous pouvez utiliser Django pour produire des images, des PDFs, et toute autre format de données que vous pourriez imaginer.

<< précédent ◊ suivant >>