{"title":"Balises et filtres de gabarit personnalisés","version":"1.9","locale":"fr","docname":"howto/custom-template-tags","url":"/fr/1.9/howto/custom-template-tags/","canonical":"https://djangodocs.dev/fr/1.9/howto/custom-template-tags/","summary":"Le langage de gabarits de Django offre une large palette de balises et filtres intégrés conçus pour répondre aux besoins de la logique de présentation de votre…","html":"

Balises et filtres de gabarit personnalisésLien vers cette rubrique#

\n

Le langage de gabarits de Django offre une large palette de balises et filtres intégrés conçus pour répondre aux besoins de la logique de présentation de votre application. Néanmoins, il se peut que vous rencontriez des besoins non couverts par cet ensemble de fonctions de gabarits. Il est possible d’étendre le moteur de gabarit en définissant des balises et des filtres personnalisés en Python, puis en les rendant disponibles dans vos gabarits par la balise {% load %}.

\n
\n

Disposition du codeLien vers cette rubrique#

\n

L’endroit le plus souvent utilisé pour placer des balises et filtres de gabarit personnalisés est à l’intérieur d’une application Django. S’ils sont liés à une application existante, il est logique de les y intégrer ; sinon, ils peuvent être ajoutés à une nouvelle application. Lorsqu’une application Django est ajoutée à INSTALLED_APPS, toute balise qu’elle définit à l’endroit conventionnel présenté ci-dessous est automatiquement mise à disposition du chargement depuis les gabarits.

\n

L’application doit contenir un répertoire templatetags au même niveau que models.py, views.py, etc. S’il n’existe pas encore, créez-le, sans oublier le fichier __init__.py pour que le répertoire soit bien considéré comme un paquet Python.

\n\n

Vos balises et filtres personnalisés se trouveront dans un module à l’intérieur du répertoire templatetags. Le nom du fichier de module est le nom que vous utiliserez plus tard pour charger les balises, prenez donc soin de choisir un nom qui n’est pas déjà utilisé pour des balises et filtres d’une autre application.

\n

Par exemple, si vos balises/filtres personnalisés se trouvent dans un fichier nommé poll_extras.py, la disposition des fichiers de votre application pourrait ressembler à ceci :

\n
Code
polls/\n    __init__.py\n    models.py\n    templatetags/\n        __init__.py\n        poll_extras.py\n    views.py\n
\n

Et dans votre gabarit, voici ce qu’il faudrait écrire :

\n
Django template
{% load poll_extras %}\n
\n

L’application qui contient les balises personnalisées doit apparaître dans INSTALLED_APPS pour que la balise {% load %} fonctionne. C’est un élément de sécurité : cela permet d’accueillir du code Python de beaucoup de bibliothèques de gabarits sur une même machine sans devoir permettre l’accès à toutes ces bibliothèques pour chaque installation Django.

\n

Il n’y a aucune limite sur le nombre de modules que l’on peut placer dans le paquet templatetags. Gardez simplement à l’esprit qu’une commande {% load %} va charger les balises/filtres du nom de module Python indiqué, et non pas du nom de l’application.

\n

Pour être valide, le module de la bibliothèque de balises doit contenir une variable au niveau module nommée register et qui doit être une instance de template.Library, dans laquelle toutes les balises et les filtres sont inscrits. Ainsi, dans la partie supérieure de votre module, écrivez ceci :

\n
Code
from django import template\n\nregister = template.Library()\n
\n\n

Il est aussi possible d’inscrire les modules de balises de gabarit au moyen du paramètre 'libraries' de DjangoTemplates. Cette méthode est utile si vous souhaitez utiliser un nom autre que celui du module de balises de gabarit au moment de charger ces balises. Cela permet aussi d’inscrire des balises sans devoir installer une application.

\n\n
\n
\n

Écriture de filtres de gabarits personnalisésLien vers cette rubrique#

\n

Les filtres personnalisés ne sont que des fonctions Python qui acceptent un ou deux paramètres :

\n\n

Par exemple, dans le filtre {{ var|foo:"bar" }}, le filtre foo reçoit la variable var et le paramètre "bar".

\n

Dans la mesure où le langage de gabarit ne s’occupe pas de la gestion des exceptions, toute exception générée dans un filtre de gabarit apparaît comme erreur de serveur. C’est pourquoi les fonctions de filtres devraient éviter de générer des exceptions quand il existe une valeur de repli raisonnable à renvoyer. Dans le cas d’une valeur d’entrée représentant clairement un bogue dans un gabarit, il se peut que la génération d’une exception soit toujours la meilleure solution plutôt que d’échouer silencieusement en masquant l’erreur.

\n

Voici un exemple de définition de filtre :

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

Et voici une exemple de la manière dont ce filtre pourrait être utilisé :

\n
Django template
{{ somevariable|cut:"0" }}\n
\n

La plupart des filtres n’acceptent pas de paramètre. Dans ce cas, ne rajoutez pas de paramètre à votre fonction. Exemple :

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

Inscription de filtres personnalisésLien vers cette rubrique#

\n
\n
\ndjango.template.Library.filter()Lien vers cette définition#
\n
\n\n

Après avoir écrit la définition d’un filtre, il est nécessaire de l’inscrire avec votre instance de Library pour qu’il soit disponible dans le langage de gabarit de Django :

\n
Code
register.filter('cut', cut)\nregister.filter('lower', lower)\n
\n

La méthode Library.filter() accepte deux paramètres :

\n
    \n

  1. Le nom du filtre, une chaîne.

    2. \n

  2. La fonction de compilation, une fonction Python (et non pas le nom de la fonction sous forme de chaîne).

    3. \n
\n

Vous pouvez aussi utiliser register.filter() sous forme de décorateur :

\n
Code
@register.filter(name='cut')\ndef cut(value, arg):\n    return value.replace(arg, '')\n\n@register.filter\ndef lower(value):\n    return value.lower()\n
\n

Si vous omettez le paramètre name comme dans le second exemple ci-dessus, Django utilisera le nom de la fonction comme nom de filtre.

\n

Pour terminer, register.filter() accepte aussi trois paramètres nommés : is_safe, needs_autoescape et expects_localtime. Ces paramètres sont décrits dans filtres et échappement automatique et filtres et fuseaux horaires ci-dessous.

\n
\n
\n

Filtres de gabarits agissant sur des chaînesLien vers cette rubrique#

\n
\n
\ndjango.template.defaultfilters.stringfilter()Lien vers cette définition#
\n
\n\n

Si vous écrivez un filtre de gabarit qui s’attend uniquement à une chaîne comme premier paramètre, vous devriez utiliser le décorateur stringfilter. Celui-ci se chargera de convertir un objet dans son équivalent chaîne de caractères avant de le passer à votre fonction :

\n
Code
from django import template\nfrom django.template.defaultfilters import stringfilter\n\nregister = template.Library()\n\n@register.filter\n@stringfilter\ndef lower(value):\n    return value.lower()\n
\n

De cette façon, vous pourrez par exemple passer un nombre entier à ce filtre et il ne générera pas d’erreur AttributeError (les nombres entiers n’ont pas de méthode lower()).

\n
\n
\n

Les filtres et l’échappement automatiqueLien vers cette rubrique#

\n

Quand vous écrivez un filtre personnalisé, réfléchissez sur la façon dont celui-ci va interagir avec le comportement d’échappement automatique de Django. Notez que trois types de chaînes peuvent circuler dans le code des gabarits :

\n\n

Le code des filtres de gabarits entre dans l’une des deux situations suivantes :

\n
    \n

  1. Votre filtre n’introduit aucun nouveau caractère HTML non sûr (<, >, ', " ou &) dans le résultat. Dans ce cas, vous pouvez laisser Django s’occuper de toute la gestion de l’échappement automatique. Tout ce que vous avez à faire est de définir le drapeau is_safe à True lorsque vous inscrivez votre fonction de filtre, comme ceci :

    \n
    Code
    @register.filter(is_safe=True)\ndef myfilter(value):\n    return value\n
    \n

    Ce drapeau indique à Django que si une chaîne « sûre » (safe) est passée à votre filtre, le résultat sera toujours « sûr » et que si une chaîne non sûre est passée, Django l’échappera automatiquement si nécessaire.

    \n

    Vous pouvez considérer cela comme signifiant que « ce filtre est sûr, il n’introduit aucune éventualité de code HTML non sûr ».

    \n

    La raison d’être de is_safe est qu’il existe un grand nombre d’opérations normales sur les chaînes qui transforment un objet SafeData en un objet str ou unicode normal, et qu’au lieu d’essayer d’identifier tous ces cas de figure, ce qui serait très difficile, Django répare les dommages après que le filtre ait fait son travail.

    \n

    Par exemple, imaginons un filtre qui ajoute la chaîne xx à la fin de n’importe quelle variable d’entrée. Comme cela n’introduit aucun caractère HTML dangereux dans le résultat (sauf s’il y en avait déjà), vous devriez marquer ce filtre avec is_safe:

    \n
    Code
    @register.filter(is_safe=True)\ndef add_xx(value):\n    return '%sxx' % value\n
    \n

    Lorsque ce filtre est utilisé dans un gabarit dans lequel l’échappement automatique est en vigueur, Django va échapper le contenu chaque fois que la variable dde départ n’est pas déjà marquée comme « sûre ».

    \n

    Par défaut, is_safe vaut False, et vous pouvez simplement l’omettre quand il n’est pas nécessaire.

    \n

    Soyez prudent quand vous décidez si votre filtre conserve réellement des chaînes sûres. Si vous enlevez des caractères, il se peut que vous laissiez par mégarde des balises ou entités HTML mal équilibrées dans le résultat. Par exemple, en enlevant un > du contenu initial, cela pourrait transformer <a> en <a qui devrait alors être échappé à l’affichage pour éviter de poser des problèmes. De même, enlever un point-virgule (;) peut transformer &amp; en &amp, ce qui n’est plus une entité valide et devrait donc de nouveau être échappé. Ce ne sera pas si subtil dans la plupart des cas, mais gardez à l’esprit ce genre de problème potentiel lorsque vous relisez votre code.

    \n

    Le marquage d’un filtre avec is_safe force la valeur de retour du filtre en chaîne de caractères. Si votre filtre doit renvoyer un booléen ou une autre valeur non textuelle, le marquage avec is_safe va probablement générer des conséquences inattendues (comme la conversion du booléen False en chaîne “False”).

    \n
    2. \n

  2. Une autre option possible est de s’occuper manuellement dans le code du filtre d’effectuer d’éventuels échappements. C’est nécessaire quand vous introduisez de nouvelles balises HTML dans le résultat. Il faut alors marquer le contenu comme sûr et exempt de besoin d’échappement afin que le code HTML introduit ne soit pas échappé plus tard, ce qui implique donc que vous gériez vous-même ce contenu.

    \n

    Pour marquer le résultat comme une chaîne sûre, utilisez django.utils.safestring.mark_safe().

    \n

    Mais restez prudent. Vous devez faire plus que simplement marquer le résultat comme sûr. Vous devez vous assurer qu’il soit réellement sûr et votre action dépend de l’activité de l’échappement automatique. L’idée est d’écrire des filtres qui peuvent agir dans des gabarits où l’échappement automatique est activé ou non, afin de faciliter la tâche aux rédacteurs de gabarits.

    \n

    Pour que vos filtres sachent si l’échappement automatique est actuellement actif, définissez le drapeau needs_autoescape à True lorsque vous inscrivez votre fonction de filtre (il vaut False par défaut). Ce drapeau indique à Django que votre fonction de filtre souhaite recevoir un paramètre mot-clé supplémentaire, autoescape. Ce paramètre vaudra True quand l’échappement automatique est en vigueur et False dans le cas contraire. Il est recommandé de définir la valeur par défaut du paramètre autoescape à True, pour que si la fonction est appelée depuis le code Python, l’échappement soit activé par défaut.

    \n

    Par exemple, écrivons un filtre qui met en évidence le premier caractère d’une chaîne :

    \n
    Code
    from django import template\nfrom django.utils.html import conditional_escape\nfrom django.utils.safestring import mark_safe\n\nregister = template.Library()\n\n@register.filter(needs_autoescape=True)\ndef initial_letter_filter(text, autoescape=True):\n    first, other = text[0], text[1:]\n    if autoescape:\n        esc = conditional_escape\n    else:\n        esc = lambda x: x\n    result = '<strong>%s</strong>%s' % (esc(first), esc(other))\n    return mark_safe(result)\n
    \n

    Le drapeau needs_autoescape et le paramètre nommé autoescape signifient que notre fonction saura si l’échappement automatique est en vigueur au moment où le filtre est appelé. Nous utilisons autoescape pour savoir si nous devons faire passer les données reçues par la fonction django.utils.html.conditional_escape (sinon, nous utilisons la fonction neutre comme fonction d’échappement). La fonction conditional_escape() est semblable à escape(), sauf que l’échappement n’a lieu que si la valeur d’entrée n’est pas déjà une instance de SafeData. Si une instance de SafeData est transmise à conditional_escape(), les données sont renvoyées sans être modifiées.

    \n

    Finalement, dans l’exemple ci-dessus, nous n’oublions pas de marquer le résultat comme sûr afin que notre code HTML soit inséré directement dans le gabarit sans échappement supplémentaire.

    \n

    Il n’y a pas besoin de se préoccuper du drapeau is_safe dans ce cas (même si on pourrait le définir sans dommages). Chaque fois que vous gérez manuellement la question de l’échappement automatique et que vous renvoyez une chaîne sûre, le drapeau is_safe ne change rien, quelle que soit sa valeur.

    \n
    3. \n
\n\n
\n
\n

Filtres et fuseaux horairesLien vers cette rubrique#

\n

Si vous écrivez un filtre personnalisé qui opère sur des objets datetime, vous allez généralement l’inscrire avec le drapeau expects_localtime défini à True:

\n
Code
@register.filter(expects_localtime=True)\ndef businesshours(value):\n    try:\n        return 9 <= value.hour < 17\n    except AttributeError:\n        return ''\n
\n

Lorsque ce drapeau est défini et si le premier paramètre du filtre est un objet date/heure sensible aux fuseaux horaires, Django le convertit au besoin dans le fuseau horaire actuel avant de le passer à votre filtre, selon les règles de conversion de fuseaux horaires dans les gabarits.

\n
\n
\n
\n

Écriture de balises de gabarits personnaliséesLien vers cette rubrique#

\n

Les balises sont plus complexes que les filtres, car les balises peuvent tout faire. Django fournit un certain nombre de raccourcis qui facilitent l’écriture de la plupart des types de balises. Nous allons commencer par explorer ces raccourcis, puis expliquer comment écrire une balise à partir de rien pour les cas où les raccourcis ne conviennent pas au besoin.

\n
\n

Balises simplesLien vers cette rubrique#

\n
\n
\ndjango.template.Library.simple_tag()Lien vers cette définition#
\n
\n\n

Bien des balises de gabarit acceptent des paramètres (chaînes ou variables de gabarit) et renvoient un résultat après avoir effectué quelques opérations sur la base des paramètres initiaux et de certaines informations externes. Par exemple, une balise current_time pourrait accepter une chaîne de formatage et renvoyer l’heure sous forme de chaîne dans le bon format.

\n

Pour faciliter la création de ce type de balise, Django fournit une fonction utilitaire, simple_tag. Cette fonction, qui est une méthode de django.template.Library, accepte elle-même une fonction qui accepte autant de paramètres que nécessaire, l’enveloppe dans une fonction render ainsi que les autres éléments nécessaires tels que mentionnés ci-dessus et l’inscrit dans le système de gabarits.

\n

Notre fonction current_time pourrait donc être écrite comme ceci :

\n
Code
import datetime\nfrom django import template\n\nregister = template.Library()\n\n@register.simple_tag\ndef current_time(format_string):\n    return datetime.datetime.now().strftime(format_string)\n
\n

Quelques petites choses à signaler au sujet de la fonction utilitaire simple_tag:

\n\n

Au contraire des autres utilitaires de balises, simple_tag passe son résultat par conditional_escape() si le contexte de gabarit est en mode échappement automatique, pour garantir du HTML correct et vous protéger d’éventuelles vulnérabilités XSS.

\n

Si l’échappement complémentaire n’est pas souhaité, il est nécessaire d’utiliser mark_safe() pour autant que vous soyez absolument sûr que votre code ne contienne pas de vulnérabilité XSS. Pour la construction de petits bouts de HTML, il est fortement recommandé d’utiliser format_html() au lieu de mark_safe().

\n\n

Si votre balise de gabarit a besoin d’accéder au contexte en cours, vous pouvez utiliser le paramètre takes_context lors de l’inscription de la balise :

\n
Code
@register.simple_tag(takes_context=True)\ndef current_time(context, format_string):\n    timezone = context['timezone']\n    return your_get_current_time_method(timezone, format_string)\n
\n

Notez que le premier paramètre doit être nommé context.

\n

Pour plus d’informations sur le fonctionnement de l’option takes_context, consultez la section sur les balises d’inclusion.

\n

Si vous avez besoin de renommer votre balise, vous pouvez lui donner un nom personnalisé :

\n
Code
register.simple_tag(lambda x: x - 1, name='minusone')\n\n@register.simple_tag(name='minustwo')\ndef some_function(value):\n    return value - 2\n
\n

Les fonctions simple_tag peuvent accepter n’importe quel nombre de paramètres positionnels ou nommés. Par exemple :

\n
Code
@register.simple_tag\ndef my_tag(a, b, *args, **kwargs):\n    warning = kwargs['warning']\n    profile = kwargs['profile']\n    ...\n    return ...\n
\n

Puis, dans le gabarit, n’importe quel nombre de paramètres séparés par des espaces peuvent être transmis à la balise de gabarit. Comme en Python, les valeurs des paramètres nommés sont définis par le signe égal (=) et doivent être placés après les paramètres positionnels. Par exemple :

\n
Django template
{% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %}\n
\n\n

Il est possible de stocker le résultat de la balise dans une variable de gabarit au lieu de l’afficher directement. Cela se fait en utilisant le paramètre as suivi du nom de variable. Ce faisant, vous pouvez ensuite afficher ce contenu à l’endroit où vous le souhaitez :

\n
Django template
{% current_time "%Y-%m-%d %I:%M %p" as the_time %}\n<p>The time is {{ the_time }}.</p>\n
\n
\n
\n

Balises d’inclusionLien vers cette rubrique#

\n
\n
\ndjango.template.Library.inclusion_tag()Lien vers cette définition#
\n
\n\n

Un autre type de balises de gabarit fréquent est le type qui affiche certaines données en effectuant le rendu d’un autre gabarit. Par exemple, l’interface d’administration de Django utilise des balises de gabarit personnalisées pour afficher les boutons au bas des pages de formulaires d’ajout/édition. Ces boutons ont toujours une même apparence, mais les cibles de leurs liens changent en fonction de l’objet en cours d’édition, ils représentent donc un cas typique d’utilisation d’un petit gabarit complété par certains détails sur l’objet en cours (dans le cas précis de l’interface d’administration, il s’agit de la balise submit_row).

\n

Ces types de balises sont appelées des « balises d’inclusion ».

\n

Un exemple sera le meilleur moyen d’illustrer l’écriture de balises d’inclusion. Écrivons une balise qui affiche une liste de choix pour un objet Poll donné, comme celui qui a été créé dans les tutoriels. Nous utiliserons la balise comme ceci :

\n
Django template
{% show_results poll %}\n
\n

… et cela donnera le résultat suivant :

\n
Html
<ul>\n  <li>First choice</li>\n  <li>Second choice</li>\n  <li>Third choice</li>\n</ul>\n
\n

Pour commencer, définissez la fonction qui accepte le paramètre et qui produit un dictionnaire de données comme résultat. Le point important ici est que nous devons uniquement renvoyer un dictionnaire, rien d’autre de plus complexe. Il sera utilisé comme contexte de gabarit pour le fragment de gabarit. Exemple :

\n
Code
def show_results(poll):\n    choices = poll.choice_set.all()\n    return {'choices': choices}\n
\n

Ensuite, créez le gabarit utilisé pour faire le rendu du résultat de la balise. Ce gabarit est une fonctionnalité figée de la balise : c’est le rédacteur de la balise qui le définit, pas le concepteur des gabarits. Suivant notre exemple, le gabarit est très simple :

\n
Django template
<ul>\n{% for choice in choices %}\n    <li> {{ choice }} </li>\n{% endfor %}\n</ul>\n
\n

Maintenant, créez et inscrivez la balise d’inclusion en appelant la méthode inclusion_tag() d’un objet Library. Suivant notre exemple, si le gabarit ci-dessus se trouve dans un fichier nommé results.html dans un répertoire parcouru par le chargeur de gabarits, voici comment nous inscrivons la balise :

\n
Code
# Here, register is a django.template.Library instance, as before\n@register.inclusion_tag('results.html')\ndef show_results(poll):\n    ...\n
\n

Il est également possible d’inscrire la balise d’inclusion en utilisant une instance de django.template.Template:

\n
Code
from django.template.loader import get_template\nt = get_template('results.html')\nregister.inclusion_tag(t)(show_results)\n
\n

… lorsque nous avons initialement créé la fonction.

\n

Il peut arriver que vos balises d’inclusion nécessitent un grand nombre de paramètres, ce qui rend pénible pour les auteurs des gabarits la transmission de tous les paramètres en se souvenant de l’ordre exigé. Pour résoudre ce problème, Django fournit l’option takes_context pour les balises d’inclusion. Si vous définissez takes_context lors de la création d’une balise de gabarit, celle-ci n’aura aucun paramètre obligatoire et la fonction Python sous-jacente recevra un paramètre, le contexte du gabarit au moment où la balise a été appelée.

\n

Par exemple, disons que vous écrivez une balise d’inclusion qui sera toujours utilisée dans un contexte contenant les variables home_link et home_title pointant sur la page principale. Voici à quoi la fonction Python ressemblerait :

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

Notez que le premier paramètre de la fonction doit être nommé context.

\n

Dans la ligne register.inclusion_tag(), nous précisons takes_context=True ainsi que le nom du gabarit. Voici à quoi pourrait ressembler le gabarit link.html:

\n
Django template
Jump directly to <a href="{{ link }}">{{ title }}</a>.\n
\n

Puis, chaque fois que vous souhaitez utiliser cette balise personnalisée, chargez sa bibliothèque et appelez-la sans paramètre, comme ceci :

\n
Django template
{% jump_link %}\n
\n

Notez que lorsque vous utilisez takes_context=True, il n’y a pas besoin de transmettre de paramètres à la balise de gabarit. Cette dernière a automatiquement accès au contexte.

\n

Le paramètre takes_context vaut False par défaut. Lorsqu’il est défini à True, la balise reçoit l’objet contexte, comme dans cet exemple. C’est la seule différence entre ce cas et l’exemple inclusion_tag précédent.

\n

Les fonctions inclusion_tag acceptent n’importe quel nombre de paramètres positionnels ou nommés. Par exemple :

\n
Code
@register.inclusion_tag('my_template.html')\ndef my_tag(a, b, *args, **kwargs):\n    warning = kwargs['warning']\n    profile = kwargs['profile']\n    ...\n    return ...\n
\n

Puis, dans le gabarit, n’importe quel nombre de paramètres séparés par des espaces peuvent être transmis à la balise de gabarit. Comme en Python, les valeurs des paramètres nommés sont définis par le signe égal (=) et doivent être placés après les paramètres positionnels. Par exemple :

\n
Django template
{% my_tag 123 "abcd" book.title warning=message|lower profile=user.profile %}\n
\n
\n
\n

Balises d’attributionLien vers cette rubrique#

\n
\n
\ndjango.template.Library.assignment_tag()Lien vers cette définition#
\n
\n\n\n

Pour faciliter la création de balises définissant une variable dans le contexte, Django fournit la fonction utilitaire assignment_tag. Cette fonction fonctionne de la même manière que simple_tag(), sauf qu’elle stocke le résultat de la balise dans la variable de contexte indiquée plutôt que de directement l’afficher.

\n

Notre fonction current_time précédente aurait donc pu être écrite comme ceci :

\n
Code
@register.assignment_tag\ndef get_current_time(format_string):\n    return datetime.datetime.now().strftime(format_string)\n
\n

Vous pouvez ensuite stocker le résultat dans une variable de gabarit en utilisant le paramètre as suivi du nom de variable, et l’afficher vous-même là où vous le souhaitez :

\n
Django template
{% get_current_time "%Y-%m-%d %I:%M %p" as the_time %}\n<p>The time is {{ the_time }}.</p>\n
\n
\n
\n

Balises de gabarits personnalisées (niveau avancé)Lien vers cette rubrique#

\n

Il peut arriver que les fonctionnalités de base de la création d’une balise de gabarit personnalisée ne suffisent pas. Ne vous en faites pas. Django vous offre un accès complet à l’interface interne nécessaire pour construire une balise de gabarit à partir de rien.

\n
\n
\n

Aperçu rapideLien vers cette rubrique#

\n

Le système de gabarits fonctionne par un processus en deux étapes : la compilation et le rendu. Pour créer une balise de gabarit personnalisée, il s’agit de définir à la fois le comportement de la compilation et celui du rendu.

\n

Quand Django compile un gabarit, il divise le texte brut du gabarit en « nœuds ». Chaque nœud est une instance de django.template.Node et possède une méthode render(). Un gabarit compilé est simplement une liste d’objets Node. Lorsque vous appelez render() sur un objet gabarit compilé, le gabarit appelle render() pour chaque Node de sa liste de nœuds en leur passant le contexte. Les résultats sont tous concaténés pour former le rendu du gabarit.

\n

Ainsi, pour créer une balise de gabarit personnalisée, vous définissez la manière de convertir la balise de gabarit brute en un Node (fonction de compilation) et ce que fait la méthode render() du nœud.

\n
\n
\n

Écriture de la fonction de compilationLien vers cette rubrique#

\n

Pour chaque balise de gabarit que l’analyseur de gabarit rencontre, il appelle une fonction Python avec le contenu de la balise et l’objet analyseur lui-même. Cette fonction est responsable de renvoyer une instance de Node en fonction du contenu de la balise.

\n

Par exemple, écrivons une implémentation complète de notre simple balise de gabarit, {% current_time %}, qui affiche l’heure et la date courantes formatées en fonction d’un paramètre donné à la balise, en respectant la syntaxe strftime(). Il est conseillé de définir la syntaxe de la balise avant toute autre chose. Dans notre cas, disons que la balise devrait être utilisée comme ceci :

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

L’analyseur de cette fonction doit capturer le paramètre et créer un objet Node:

\n
Code
from django import template\n\ndef do_current_time(parser, token):\n    try:\n        # split_contents() knows not to split quoted strings.\n        tag_name, format_string = token.split_contents()\n    except ValueError:\n        raise template.TemplateSyntaxError(\n            "%r tag requires a single argument" % token.contents.split()[0]\n        )\n    if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")):\n        raise template.TemplateSyntaxError(\n            "%r tag's argument should be in quotes" % tag_name\n        )\n    return CurrentTimeNode(format_string[1:-1])\n
\n

Notes :

\n\n
\n
\n

Écriture de la fonction de renduLien vers cette rubrique#

\n

La seconde étape dans l’écriture de balises de gabarit est définir une sous-classe de Node possédant une méthode render().

\n

Pour continuer l’exemple ci-dessus, nous devons définir CurrentTimeNode:

\n
Code
import datetime\nfrom django import template\n\nclass CurrentTimeNode(template.Node):\n    def __init__(self, format_string):\n        self.format_string = format_string\n\n    def render(self, context):\n        return datetime.datetime.now().strftime(self.format_string)\n
\n

Notes :

\n\n

Au final, cette distinction entre compilation et rendu aboutit à un système de gabarit efficace, car un gabarit peut produire un rendu avec plusieurs contextes différents sans devoir être analysé plusieurs fois.

\n
\n
\n

Considérations sur l’échappement automatiqueLien vers cette rubrique#

\n

Le résultat des balises de gabarit ne passe pas automatiquement par les filtres d’échappement automatique (à l’exception de simple_tag() comme expliqué plus haut) . Toutefois, il y a quand même deux ou trois choses à garder à l’esprit en écrivant des balises de gabarit.

\n

Si la fonction render() de votre gabarit conserve le résultat dans une variable de contexte (plutôt que de renvoyer le résultat dans une chaîne), elle devrait alors s’occuper d’appeler mark_safe() si nécessaire. Lorsque la variable sera finalement affichée, elle sera affectée par le réglage d’échappement automatique en vigueur à ce moment, il faut donc que les contenus qui ne doivent plus être échappés soient marqués comme tels.

\n

De même, si votre balise de gabarit crée un nouveau contexte pour procéder à certains sous-rendus, définissez l’attribut d’échappement automatique pour la valeur du contexte en cours. La méthode __init__ de la classe Context accepte un paramètre nommé autoescape et qui est destiné à cet effet. Par exemple :

\n
Code
from django.template import Context\n\ndef render(self, context):\n    # ...\n    new_context = Context({'var': obj}, autoescape=context.autoescape)\n    # ... Do something with new_context ...\n
\n

Ce n’est pas une situation très courante, mais c’est utile si vous faites vous-même le rendu d’un gabarit. Par exemple :

\n
Code
def render(self, context):\n    t = context.template.engine.get_template('small_fragment.html')\n    return t.render(Context({'var': obj}, autoescape=context.autoescape))\n
\n\n

Si nous avions négligé de passer la valeur actuelle de context.autoescape au nouveau Context de cet exemple, les résultats auraient toujours subi un échappement automatique, ce qui pourrait ne pas correspondre au comportement attendu si la balise de gabarit est utilisée à l’intérieur d’un bloc {% autoescape off %}.

\n
\n
\n

Considérations sur la concurrence entre « threads »Lien vers cette rubrique#

\n

Dès qu’un nœud est analysé, sa méthode render peut être appelée indéfiniment. Comme Django est parfois lancé dans un environnement avec plusieurs fils d’exécution parallèles (multi-thread), un même nœud peut être rendu plusieurs fois simultanément avec différents contextes en réponse à des requêtes séparées. Il est donc important de s’assurer que vos balises de gabarit sont robustes à la concurrence.

\n

Pour que vos balises de gabarit sachent gérer la concurrence, il ne faut jamais stocker des informations d’état dans le nœud lui-même. Par exemple, Django contient une balise de gabarit cycle qui parcourt une liste de chaînes données à chaque rendu :

\n
Django template
{% for o in some_list %}\n    <tr class="{% cycle 'row1' 'row2' %}">\n        ...\n    </tr>\n{% endfor %}\n
\n

Une implémentation naïve de CycleNode pourrait ressembler à ceci :

\n
Code
import itertools\nfrom django import template\n\nclass CycleNode(template.Node):\n    def __init__(self, cyclevars):\n        self.cycle_iter = itertools.cycle(cyclevars)\n\n    def render(self, context):\n        return next(self.cycle_iter)\n
\n

Mais supposons que deux gabarits soient rendus en parallèle et qu’ils contiennent l’extrait de gabarit ci-dessus :

\n
    \n

  1. Le fil d’exécution 1 effectue sa première itération de boucle, CycleNode.render() renvoie « row1 »

    2. \n

  2. Le fil d’exécution 2 effectue sa première itération de boucle, CycleNode.render() renvoie « row2 »

    3. \n

  3. Le fil d’exécution 1 effectue sa seconde itération de boucle, CycleNode.render() renvoie « row1 »

    4. \n

  4. Le fil d’exécution 2 effectue sa seconde itération de boucle, CycleNode.render() renvoie « row2 »

    5. \n
\n

Le nœud CycleNode effectue son itération, mais globalement. En ce qui concerne les fils d’exécution 1 et 2, ils renvoient toujours la même valeur. Ce n’est évidemment pas ce que nous voulons !

\n

Pour résoudre ce problème, Django met à disposition un render_context qui est associé au context du gabarit qui est en cours de rendu. render_context se comporte comme un dictionnaire Python et doit être utilisé pour stocker l’état de Node entre les invocations de la méthode render.

\n

Révisons notre implémentation de CycleNode en utilisant render_context:

\n
Code
class CycleNode(template.Node):\n    def __init__(self, cyclevars):\n        self.cyclevars = cyclevars\n\n    def render(self, context):\n        if self not in context.render_context:\n            context.render_context[self] = itertools.cycle(self.cyclevars)\n        cycle_iter = context.render_context[self]\n        return next(cycle_iter)\n
\n

Notez qu’il est totalement correct de stocker sous forme d’attribut de l’information globale qui ne changera pas durant le cycle de vie de Node. Dans le cas de CycleNode, le paramètre cyclevars ne change plus après que Node a été instancié, nous n’avons donc pas besoin de le placer dans render_context. Mais l’information d’état qui est spécifique au gabarit en cours de rendu, comme l’état d’itération de CycleNode, doit être stockée dans render_context.

\n\n
\n
\n

Inscription de la baliseLien vers cette rubrique#

\n

Pour terminer, inscrivez la balise dans l’instance Library de votre module, comme expliqué dans la section sur l”écriture des filtres de gabarit personnalisés ci-dessus. Exemple :

\n
Code
register.tag('current_time', do_current_time)\n
\n

La méthode tag() accepte deux paramètres :

\n
    \n

  1. Le nom de la balise de gabarit (une chaîne). En cas d’omission, c’est le nom de la fonction de compilation qui sera utilisé.

    2. \n

  2. La fonction de compilation, une fonction Python (et non pas le nom de la fonction sous forme de chaîne).

    3. \n
\n

Comme pour l’inscription de filtre, il est aussi possible d’utiliser une syntaxe de décorateur :

\n
Code
@register.tag(name="current_time")\ndef do_current_time(parser, token):\n    ...\n\n@register.tag\ndef shout(parser, token):\n    ...\n
\n

Si vous omettez le paramètre name comme dans le second exemple ci-dessus, Django utilise le nom de la fonction comme nom de balise.

\n
\n
\n

Transmission de variables de gabarit à la baliseLien vers cette rubrique#

\n

Même si vous pouvez transmettre autant de paramètres que souhaité à la balise de gabarit en utilisant token.split_contents(), les paramètres sont alors tous identifiés comme chaînes de caractères. Pour pouvoir passer du contenu dynamique (une variable de gabarit) comme paramètre d’une balise de gabarit, cela demande un petit peu plus d’effort.

\n

Dans les exemples précédents, l’heure actuelle a été formatée en chaîne et celle-ci a été renvoyée en tant que chaîne. Supposons que nous souhaitions passer un DateTimeField d’un objet pour que la balise de gabarit mette en forme cette date :

\n
Django template
<p>This post was last updated at {% format_time blog_entry.date_updated "%Y-%m-%d %I:%M %p" %}.</p>\n
\n

Initialement, token.split_contents() renverra trois valeurs :

\n
    \n

  1. Le nom de la balise

    2. \n

  2. La chaîne 'blog_entry.date_updated' (sans les guillemets).

    3. \n

  3. La chaîne de formatage '"%Y-%m-%d %I:%M %p"'. La valeur de retour de split_contents() contiendra les guillemets ouvrant et fermant pour de telles chaînes constantes.

    4. \n
\n

Votre balise devrait maintenant commencer à ressembler à ceci :

\n
Code
from django import template\n\ndef do_format_time(parser, token):\n    try:\n        # split_contents() knows not to split quoted strings.\n        tag_name, date_to_be_formatted, format_string = token.split_contents()\n    except ValueError:\n        raise template.TemplateSyntaxError(\n            "%r tag requires exactly two arguments" % token.contents.split()[0]\n        )\n    if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")):\n        raise template.TemplateSyntaxError(\n            "%r tag's argument should be in quotes" % tag_name\n        )\n    return FormatTimeNode(date_to_be_formatted, format_string[1:-1])\n
\n

Vous devez aussi modifier la fonction de rendu pour récupérer le contenu réel de la propriété date_updated de l’objet blog_entry. Cela peut se faire en utilisant la classe Variable() de django.template.

\n

Pour utiliser la clase Variable, il suffit de l’instancier avec le nom de la variable à résoudre puis d’appeler variable.resolve(context). Ainsi, par exemple :

\n
Code
class FormatTimeNode(template.Node):\n    def __init__(self, date_to_be_formatted, format_string):\n        self.date_to_be_formatted = template.Variable(date_to_be_formatted)\n        self.format_string = format_string\n\n    def render(self, context):\n        try:\n            actual_date = self.date_to_be_formatted.resolve(context)\n            return actual_date.strftime(self.format_string)\n        except template.VariableDoesNotExist:\n            return ''\n
\n

La résolution de variable lèvera une exception VariableDoesNotExist si elle ne peut pas résoudre la chaîne qui lui a été passée dans le contexte actuel de la page.

\n
\n
\n

Définition d’une variable dans le contexteLien vers cette rubrique#

\n

Les exemples ci-dessus ne font qu’afficher une valeur. Il est généralement plus souple de définir des variables de gabarit dans les balises de gabarit que d’afficher des valeurs. De cette façon, les auteurs de gabarits peuvent réutiliser les valeurs créées par vos balises de gabarit.

\n

Pour définir une variable dans le contexte, il suffit d’attribuer des valeurs à l’objet dictionnaire du contexte dans la méthode render(). Voici une version mise à jour de CurrentTimeNode qui définit une variable de gabarit current_time au lieu de l’afficher :

\n
Code
import datetime\nfrom django import template\n\nclass CurrentTimeNode2(template.Node):\n    def __init__(self, format_string):\n        self.format_string = format_string\n    def render(self, context):\n        context['current_time'] = datetime.datetime.now().strftime(self.format_string)\n        return ''\n
\n

Notez que render() renvoie la chaîne vide. render() doit toujours renvoyer une chaîne. Si la balise de gabarit ne fait que définir une variable, render() doit renvoyer la chaîne vide.

\n

Voici comment on pourrait utiliser cette nouvelle version de la balise :

\n
Django template
{% current_time "%Y-%M-%d %I:%M %p" %}<p>The time is {{ current_time }}.</p>\n
\n\n

Mais il reste un problème avec CurrentTimeNode2: le nom de variable current_time est codé en dur. Cela veut dire que vous devrez vous assurer que votre gabarit n’utilise pas {{ current_time }} ailleurs, parce que {% current_time %} va écraser de manière aveugle la valeur de cette éventuelle variable. Une solution plus propre est de permettre à la balise de gabarit de définir le nom de la variable produite, comme ceci :

\n
Django template
{% current_time "%Y-%M-%d %I:%M %p" as my_current_time %}\n<p>The current time is {{ my_current_time }}.</p>\n
\n

Pour faire cela, il faudra modifier à la fois la fonction de compilation et la classe Node, comme ceci :

\n
Code
import re\n\nclass CurrentTimeNode3(template.Node):\n    def __init__(self, format_string, var_name):\n        self.format_string = format_string\n        self.var_name = var_name\n    def render(self, context):\n        context[self.var_name] = datetime.datetime.now().strftime(self.format_string)\n        return ''\n\ndef do_current_time(parser, token):\n    # This version uses a regular expression to parse tag contents.\n    try:\n        # Splitting by None == splitting by spaces.\n        tag_name, arg = token.contents.split(None, 1)\n    except ValueError:\n        raise template.TemplateSyntaxError(\n            "%r tag requires arguments" % token.contents.split()[0]\n        )\n    m = re.search(r'(.*?) as (\\w+)', arg)\n    if not m:\n        raise template.TemplateSyntaxError("%r tag had invalid arguments" % tag_name)\n    format_string, var_name = m.groups()\n    if not (format_string[0] == format_string[-1] and format_string[0] in ('"', "'")):\n        raise template.TemplateSyntaxError(\n            "%r tag's argument should be in quotes" % tag_name\n        )\n    return CurrentTimeNode3(format_string[1:-1], var_name)\n
\n

La différence ici est que do_current_time() capture la chaîne de format et le nom de la variable, les transmettant les deux à CurrentTimeNode3.

\n

Finalement, si vous n’avez besoin que d’une syntaxe simple pour votre balise de gabarit de mise à jour du contexte, envisagez l’utilisation du raccourci simple_tag() qui permet d’attribuer le résultat de la balise à une variable de gabarit.

\n
\n
\n

Analyse jusqu’à la prochaine balise de blocLien vers cette rubrique#

\n

Les balises de gabarit peuvent travailler en tandem. Par exemple, la balise {% comment %} standard masque tout jusqu’à la prochaine occurrence de {% endcomment %}. Pour créer une balise de gabarit semblable, utilisez parser.parse() dans votre fonction de compilation.

\n

Voici comment une balise {% comment %} simplifiée pourrait être écrite :

\n
Code
def do_comment(parser, token):\n    nodelist = parser.parse(('endcomment',))\n    parser.delete_first_token()\n    return CommentNode()\n\nclass CommentNode(template.Node):\n    def render(self, context):\n        return ''\n
\n\n

parser.parse() accepte un tuple de noms de balises bloc définissant les limites d’analyse. Elle renvoie une instance de django.template.NodeList contenant une liste de tous les objets Node que l’analyseur a rencontré avant que n’apparaisse l’une des balises indiquées dans le tuple.

\n

Dans nodelist = parser.parse(('endcomment',)) de l’exemple ci-dessus, nodelist est une liste de tous les nœuds entre {% comment %} et {% endcomment %}, à l’exclusion de {% comment %} et {% endcomment %}.

\n

Après l’appel à parser.parse(), l’analyseur n’a pas encore « consommé » la balise {% endcomment %}, c’est pourquoi le code doit explicitement appeler parser.delete_first_token().

\n

CommentNode.render() renvoie simplement une chaîne vide. Tout ce qui se trouve entre {% comment %} et {% endcomment %} est ignoré.

\n
\n
\n

Analyse jusqu’à la prochaine balise de bloc et enregistrement du contenuLien vers cette rubrique#

\n

Dans l’exemple prédédent, do_comment() a ignoré tout ce qui apparaissait entre {% comment %} et {% endcomment %}. Au lieu de faire cela, il est possible de faire quelque chose avec le code situé entre les balises de bloc.

\n

Par exemple, voici une balise de gabarit personnalisée, {% upper %}, qui met en majuscules tout ce qui se trouve entre elle et {% endupper %}.

\n

Utilisation :

\n
Django template
{% upper %}This will appear in uppercase, {{ your_name }}.{% endupper %}\n
\n

Comme dans l’exemple précédent, nous utilisons parser.parse(). Mais cette fois-ci, nous passons le contenu de nodelist à Node:

\n
Code
def do_upper(parser, token):\n    nodelist = parser.parse(('endupper',))\n    parser.delete_first_token()\n    return UpperNode(nodelist)\n\nclass UpperNode(template.Node):\n    def __init__(self, nodelist):\n        self.nodelist = nodelist\n    def render(self, context):\n        output = self.nodelist.render(context)\n        return output.upper()\n
\n

Le seul nouveau concept ici est l’appel à self.nodelist.render(context) dans UpperNode.render().

\n

Pour plus d’exemples de rendus complexes, consultez le code source des balises {% for %} dans django/template/defaulttags.py et {% if %} dans django/template/smartif.py.

\n
\n
","rootId":"custom-template-tags-and-filters","toc":[{"title":"Disposition du code","anchor":"code-layout","children":[]},{"title":"Écriture de filtres de gabarits personnalisés","anchor":"writing-custom-template-filters","children":[{"title":"Inscription de filtres personnalisés","anchor":"registering-custom-filters","children":[]},{"title":"Filtres de gabarits agissant sur des chaînes","anchor":"template-filters-that-expect-strings","children":[]},{"title":"Les filtres et l’échappement automatique","anchor":"filters-and-auto-escaping","children":[]},{"title":"Filtres et fuseaux horaires","anchor":"filters-and-time-zones","children":[]}]},{"title":"Écriture de balises de gabarits personnalisées","anchor":"writing-custom-template-tags","children":[{"title":"Balises simples","anchor":"simple-tags","children":[]},{"title":"Balises d’inclusion","anchor":"inclusion-tags","children":[]},{"title":"Balises d’attribution","anchor":"assignment-tags","children":[]},{"title":"Balises de gabarits personnalisées (niveau avancé)","anchor":"advanced-custom-template-tags","children":[]},{"title":"Aperçu rapide","anchor":"a-quick-overview","children":[]},{"title":"Écriture de la fonction de compilation","anchor":"writing-the-compilation-function","children":[]},{"title":"Écriture de la fonction de rendu","anchor":"writing-the-renderer","children":[]},{"title":"Considérations sur l’échappement automatique","anchor":"auto-escaping-considerations","children":[]},{"title":"Considérations sur la concurrence entre « threads »","anchor":"thread-safety-considerations","children":[]},{"title":"Inscription de la balise","anchor":"registering-the-tag","children":[]},{"title":"Transmission de variables de gabarit à la balise","anchor":"passing-template-variables-to-the-tag","children":[]},{"title":"Définition d’une variable dans le contexte","anchor":"setting-a-variable-in-the-context","children":[]},{"title":"Analyse jusqu’à la prochaine balise de bloc","anchor":"parsing-until-another-block-tag","children":[]},{"title":"Analyse jusqu’à la prochaine balise de bloc et enregistrement du contenu","anchor":"parsing-until-another-block-tag-and-saving-contents","children":[]}]}],"breadcrumbs":[{"docname":"howto/index","title":"Guides pratiques","url":"/fr/1.9/howto/"}],"prev":{"docname":"howto/custom-lookups","title":"Expressions de recherche personnalisées","url":"/fr/1.9/howto/custom-lookups/"},"next":{"docname":"howto/custom-file-storage","title":"Écriture d’un système de stockage personnalisé","url":"/fr/1.9/howto/custom-file-storage/"},"formats":{"html":"/fr/1.9/howto/custom-template-tags/","markdown":"/fr/1.9/howto/custom-template-tags.md","json":"/fr/1.9/howto/custom-template-tags.json"},"source":"https://github.com/django/django/blob/stable/1.9.x/docs/howto/custom-template-tags.txt","official":"https://docs.djangoproject.com/fr/1.9/howto/custom-template-tags/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0","1.11","1.10","1.9"],"inLocales":["en","fr","ja","id","pt-br","es"]}