<!DOCTYPE html>

<html lang="fr" data-content_root="../../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>Le langage de gabarit de Django &#8212; Documentation Django 6.0.7</title>
    <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=34bb78ad" />
    <link rel="stylesheet" type="text/css" href="../../_static/default.css?v=bf4d74af" />
    <script src="../../_static/documentation_options.js?v=5190fde6"></script>
    <script src="../../_static/doctools.js?v=9bcbadda"></script>
    <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="../../_static/translations.js?v=e6b791cb"></script>
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Recherche" href="../../search.html" />
    <link rel="next" title="Balises et filtres de gabarit intégrés" href="builtins.html" />
    <link rel="prev" title="Gabarits" href="index.html" />
  </head><body>

    <div class="document">
  <div id="custom-doc" class="yui-t6">
    <div id="hd">
      <h1><a href="../../index.html">Documentation Django 6.0.7</a></h1>
      <div id="global-nav">
        <a title="Home page" href="../../index.html">Home</a>  |
        <a title="Table of contents" href="../../contents.html">Table of contents</a>  |
        <a title="Global index" href="../../genindex.html">Index</a>  |
        <a title="Module index" href="../../py-modindex.html">Modules</a>
      </div>
      <div class="nav">
    &laquo; <a href="index.html" title="Gabarits">previous</a>
     |
    <a href="../index.html" title="Référence de l’API" accesskey="U">up</a>
   |
    <a href="builtins.html" title="Balises et filtres de gabarit intégrés">next</a> &raquo;</div>
    </div>

    <div id="bd">
      <div id="yui-main">
        <div class="yui-b">
          <div class="yui-g" id="ref-templates-language">
            
  <section id="s-the-django-template-language">
<span id="the-django-template-language"></span><h1>Le langage de gabarit de Django<a class="headerlink" href="#the-django-template-language" title="Lien vers cette rubrique">¶</a></h1>
<p>Ce document présente la syntaxe du langage du système de gabarits de Django. Si vous recherchez une perspective plus technique sur son fonctionnement et sur la manière de l’étendre, consultez <a class="reference internal" href="api.html"><span class="doc">Le langage de gabarit de Django : pour les programmeurs Python</span></a>.</p>
<p>Le langage de gabarit de Django est conçu comme un compromis entre puissance et simplicité. Il est conçu pour que les habitués au code HTML se sentent à l’aise. Si vous avez des connaissances d’autres langages de gabarit orientés texte, tels que <a class="reference external" href="https://www.smarty.net/">Smarty</a> ou <a class="reference external" href="https://palletsprojects.com/p/jinja/">Jinja2</a>, vous n’allez pas être dépaysés avec les gabarits de Django.</p>
<div class="admonition-philosophy admonition">
<p class="admonition-title">Philosophie</p>
<p>Si vous avez un arrière-plan de programmation ou que vous êtes habitué aux langages qui mélangent le code de programmation directement dans le code HTML, vous devrez garder à l’esprit que le système des gabarits de Django n’est pas simplement du code Python intégré dans du code HTML. C’est un concept volontaire : le système des gabarits est conçu pour exprimer de la présentation, et non pas de la logique de programmation.</p>
<p>Le système des gabarits de Django fournit des balises dont les fonctions sont semblables à certaines structures de programmation (une balise <a class="reference internal" href="builtins.html#std-templatetag-if"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">if</span></code></a> pour les tests booléens, une balise <a class="reference internal" href="builtins.html#std-templatetag-for"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">for</span></code></a> pour les boucles, etc.), mais celles-ci ne sont pas simplement exécutées comme le code Python correspondant ; le système des gabarits de Django n’exécute pas n’importe quelle expression Python. Seuls les balises, les filtres et la syntaxe présentés ci-dessous sont pris en charge par défaut (même si vous pouvez ajouter <a class="reference internal" href="../../howto/custom-template-tags.html"><span class="doc">vos propres extensions</span></a> au langage de gabarit selon vos besoins).</p>
</div>
<section id="s-templates">
<span id="templates"></span><h2>Gabarits<a class="headerlink" href="#templates" title="Lien vers cette rubrique">¶</a></h2>
<p>Un gabarit est un fichier texte. Il peut générer tout format basé sur du texte (HTML, XML, CSV, etc.).</p>
<p>Un gabarit contient des <strong>variables</strong> qui sont remplacées par des valeurs lorsque le gabarit est évalué, ainsi que des <strong>balises</strong> qui contrôlent la logique du gabarit.</p>
<p>Voici un gabarit minimal illustrant quelques principes de base. Chaque élément sera ensuite expliqué plus loin dans ce document.</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">extends</span> <span class="s2">&quot;base_generic.html&quot;</span> <span class="cp">%}</span>

<span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}{{</span> <span class="nv">section.title</span> <span class="cp">}}{%</span> <span class="k">endblock</span> <span class="cp">%}</span>

<span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}</span>
<span class="p">&lt;</span><span class="nt">h1</span><span class="p">&gt;</span><span class="cp">{{</span> <span class="nv">section.title</span> <span class="cp">}}</span><span class="p">&lt;/</span><span class="nt">h1</span><span class="p">&gt;</span>

<span class="cp">{%</span> <span class="k">for</span> <span class="nv">story</span> <span class="k">in</span> <span class="nv">story_list</span> <span class="cp">%}</span>
<span class="p">&lt;</span><span class="nt">h2</span><span class="p">&gt;</span>
  <span class="p">&lt;</span><span class="nt">a</span> <span class="na">href</span><span class="o">=</span><span class="s">&quot;</span><span class="cp">{{</span> <span class="nv">story.get_absolute_url</span> <span class="cp">}}</span><span class="s">&quot;</span><span class="p">&gt;</span>
    <span class="cp">{{</span> <span class="nv">story.headline</span><span class="o">|</span><span class="nf">upper</span> <span class="cp">}}</span>
  <span class="p">&lt;/</span><span class="nt">a</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">h2</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span><span class="cp">{{</span> <span class="nv">story.tease</span><span class="o">|</span><span class="nf">truncatewords</span><span class="s2">:&quot;100&quot;</span> <span class="cp">}}</span><span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;</span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
</pre></div>
</div>
<div class="admonition-philosophy admonition">
<p class="admonition-title">Philosophie</p>
<p>Pourquoi utiliser des gabarits basés sur du texte plutôt qu’en XML (comme le langage TAL de Zope) ? Nous avons souhaité que le langage de gabarit de Django ne soit pas uniquement utilisable pour des gabarits XML/HTML. Vous pouvez utiliser le langage de gabarit pour tout format basé sur du texte, tel que des courriels, du JavaScript ou du CSV.</p>
</div>
</section>
<section id="s-variables">
<span id="s-template-variables"></span><span id="variables"></span><span id="template-variables"></span><h2>Variables<a class="headerlink" href="#variables" title="Lien vers cette rubrique">¶</a></h2>
<p>Les variables apparaissent comme ceci : <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">variable</span> <span class="pre">}}</span></code>. Lorsque le moteur de gabarit rencontre une variable, il l’évalue et la remplace par le résultat. Les noms de variables peuvent contenir tout caractère alphanumérique ainsi que le soulignement (<code class="docutils literal notranslate"><span class="pre">&quot;_&quot;</span></code>) mais ne peuvent pas commencer par un soulignement et ne peuvent pas être un nombre. Le point (<code class="docutils literal notranslate"><span class="pre">&quot;.&quot;</span></code>) peut aussi faire partie du nom de variable, mais avec une signification particulière, comme nous l’expliquons ci-après. Il est important de relever que <em>les espaces et la ponctuation ne sont pas autorisés dans les noms de variables</em>.</p>
<p>Le point (<code class="docutils literal notranslate"><span class="pre">.</span></code>) est utilisé pour accéder aux attributs d’une variable.</p>
<div class="admonition-behind-the-scenes admonition">
<p class="admonition-title">En coulisses</p>
<p>Techniquement, lorsque le système de gabarits rencontre un point, il essaie les méthodes d’accès suivantes, dans l’ordre :</p>
<ul class="simple">
<li><p>Consultation de dictionnaire</p></li>
<li><p>Consultation d’attribut ou de méthode</p></li>
<li><p>Consultation d’indice numérique</p></li>
</ul>
<p>Si la valeur résultante est exécutable, elle est appelée sans paramètre. Le résultat de l’appel devient la valeur de gabarit.</p>
<p>Cet ordre de consultation peut aboutir à un comportement inattendu avec des objets qui surchargent la consultation de dictionnaire. Par exemple, considérez l’extrait de code suivant qui essaie de faire une boucle sur un objet <code class="docutils literal notranslate"><span class="pre">collections.defaultdict</span></code>:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">for</span> <span class="nv">k</span><span class="o">,</span> <span class="nv">v</span> <span class="k">in</span> <span class="nv">defaultdict.items</span> <span class="cp">%}</span>
    Do something with k and v here...
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>Comme la consultation de dictionnaire s’effectue en premier, c’est ce qui arrive ici et une valeur par défaut en résulte au lieu de la méthode <code class="docutils literal notranslate"><span class="pre">.items()</span></code> attendue. Dans ce cas, il faut envisager de convertir l’objet en dictionnaire simple au préalable.</p>
</div>
<p>Dans l’exemple ci-dessus, <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">section.title</span> <span class="pre">}}</span></code> sera remplacé par l’attribut <code class="docutils literal notranslate"><span class="pre">title</span></code> de l’objet <code class="docutils literal notranslate"><span class="pre">section</span></code>.</p>
<p>Si vous appelez une variable qui n’existe pas, le système des gabarits insère la valeur de l’option <code class="docutils literal notranslate"><span class="pre">string_if_invalid</span></code>, qui vaut  <code class="docutils literal notranslate"><span class="pre">''</span></code> (chaîne vide) par défaut.</p>
<p>Notez que « bar » dans une expression de gabarit comme <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">foo.bar</span> <span class="pre">}}</span></code> 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.</p>
<p>Les attributs de variable qui commencent par un soulignement ne peuvent pas être accédés car ils sont généralement considérés comme privés.</p>
</section>
<section id="s-filters">
<span id="filters"></span><h2>Filtres<a class="headerlink" href="#filters" title="Lien vers cette rubrique">¶</a></h2>
<p>Vous pouvez modifier l’affichage des variables en utilisant des <strong>filtres</strong>.</p>
<p>Les filtres ressemblent à ceci : <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">nom|lower</span> <span class="pre">}}</span></code>. Ceci affiche la valeur de la variable <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">nom</span> <span class="pre">}}</span></code> après avoir été filtrée par le filtre <a class="reference internal" href="builtins.html#std-templatefilter-lower"><code class="xref std std-tfilter docutils literal notranslate"><span class="pre">lower</span></code></a> qui convertit le texte en minuscules. Utilisez la barre verticale (<code class="docutils literal notranslate"><span class="pre">|</span></code>) pour appliquer un filtre.</p>
<p>Les filtres peuvent s’enchaîner. Le résultat d’un filtre est appliqué au suivant. <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">text|escape|linebreaks</span> <span class="pre">}}</span></code> est un idiome courant pour échapper du contenu textuel, puis convertir les sauts de ligne en balises <code class="docutils literal notranslate"><span class="pre">&lt;p&gt;</span></code>.</p>
<p>Certains filtres acceptent des paramètres. Un paramètre de filtre ressemble à ceci : <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">bio|truncatewords:30</span> <span class="pre">}}</span></code>. Ceci affiche les 30 premiers mots de la variable <code class="docutils literal notranslate"><span class="pre">bio</span></code>.</p>
<p>Les paramètres de filtre contenant des espaces doivent être placés entre guillemets ; par exemple, pour concaténer une liste en utilisant une virgule et une espace, il faudrait écrire <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">liste|join:&quot;,</span> <span class="pre">&quot;</span> <span class="pre">}}</span></code>.</p>
<p>Django fournit une soixantaine de filtres de gabarit intégrés. Il sont tous documentés dans la <a class="reference internal" href="builtins.html#ref-templates-builtins-filters"><span class="std std-ref">référence des filtres intégrés</span></a>. Pour vous donner une idée de ce qui est disponible, voici quelques-uns des filtres de gabarit les plus utilisés :</p>
<dl>
<dt><a class="reference internal" href="builtins.html#std-templatefilter-default"><code class="xref std std-tfilter docutils literal notranslate"><span class="pre">default</span></code></a></dt><dd><p>Si une variable contient la valeur faux ou est vide, ce filtre utilise la valeur par défaut indiquée. Sinon, il utilise la valeur de la variable. Par exemple :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">value</span><span class="o">|</span><span class="nf">default</span><span class="s2">:&quot;nothing&quot;</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>Si <code class="docutils literal notranslate"><span class="pre">value</span></code> n’est pas fournie ou qu’elle est vide, le code ci-dessus affiche « <code class="docutils literal notranslate"><span class="pre">nothing</span></code> ».</p>
</dd>
<dt><a class="reference internal" href="builtins.html#std-templatefilter-length"><code class="xref std std-tfilter docutils literal notranslate"><span class="pre">length</span></code></a></dt><dd><p>Renvoie la longueur de la valeur. Cela fonctionne aussi bien pour du texte que des listes. Par exemple :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">value</span><span class="o">|</span><span class="nf">length</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>Si <code class="docutils literal notranslate"><span class="pre">value</span></code> vaut <code class="docutils literal notranslate"><span class="pre">['a',</span> <span class="pre">'b',</span> <span class="pre">'c',</span> <span class="pre">'d']</span></code>, le résultat sera <code class="docutils literal notranslate"><span class="pre">4</span></code>.</p>
</dd>
<dt><a class="reference internal" href="builtins.html#std-templatefilter-filesizeformat"><code class="xref std std-tfilter docutils literal notranslate"><span class="pre">filesizeformat</span></code></a></dt><dd><p>Met en forme la valeur sous forme de taille de fichier humainement lisible (par ex. <code class="docutils literal notranslate"><span class="pre">'13</span> <span class="pre">Kio'</span></code>, <code class="docutils literal notranslate"><span class="pre">'4.1</span> <span class="pre">Mio'</span></code>, <code class="docutils literal notranslate"><span class="pre">'102</span> <span class="pre">octets'</span></code>, etc). Par exemple :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">value</span><span class="o">|</span><span class="nf">filesizeformat</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>SI <code class="docutils literal notranslate"><span class="pre">value</span></code> contient 123456789, le résultat sera <code class="docutils literal notranslate"><span class="pre">117.7</span> <span class="pre">Mio</span></code>.</p>
</dd>
</dl>
<p>Ce n’était que quelques exemples ; voir la <a class="reference internal" href="builtins.html#ref-templates-builtins-filters"><span class="std std-ref">référence des filtres intégrés</span></a> pour une liste complète.</p>
<p>Vous pouvez aussi créer vos propres filtres de gabarit ; voir <a class="reference internal" href="../../howto/custom-template-tags.html"><span class="doc">Création de balises et filtres de gabarit personnalisés</span></a>.</p>
<div class="admonition seealso">
<p class="admonition-title">Voir aussi</p>
<p>L’interface d’administration de Django peut inclure une référence complète de tous les filtres et balises de gabarit disponibles pour un site donné. Voir <a class="reference internal" href="../contrib/admin/admindocs.html"><span class="doc">Le générateur de documentation de l’administration de Django</span></a>.</p>
</div>
</section>
<section id="s-tags">
<span id="tags"></span><h2>Balises<a class="headerlink" href="#tags" title="Lien vers cette rubrique">¶</a></h2>
<p>Les balises (tags en anglais) ressemblent à ceci : <code class="docutils literal notranslate"><span class="pre">{%</span> <span class="pre">tag</span> <span class="pre">%}</span></code>. Les balises sont plus complexes que les variables : certaines produisent du texte, d’autres contrôlent le flux en effectuant des boucles ou de la logique, et d’autres encore chargent des informations externes dans les gabarits pour que des variables puissent les utiliser ensuite.</p>
<p>Certains balises nécessitent une balise ouvrante et une balise fermante (par ex. <code class="docutils literal notranslate"><span class="pre">{%</span> <span class="pre">tag</span> <span class="pre">%}</span> <span class="pre">...</span> <span class="pre">contenu</span> <span class="pre">de</span> <span class="pre">la</span> <span class="pre">balise</span> <span class="pre">...</span> <span class="pre">{%</span> <span class="pre">endtag</span> <span class="pre">%}</span></code>).</p>
<p>Django fournit une vingtaine de balises de gabarit intégrées. Elles sont toutes documentées dans la <a class="reference internal" href="builtins.html#ref-templates-builtins-tags"><span class="std std-ref">référence des balises intégrées</span></a>. Pour vous donner une idée de ce qui est disponible, voici quelques-unes des balises de gabarit les plus utilisées :</p>
<dl>
<dt><a class="reference internal" href="builtins.html#std-templatetag-for"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">for</span></code></a></dt><dd><p>Loop over each item in an array. For example, to display a list of athletes
provided in <code class="docutils literal notranslate"><span class="pre">athlete_list</span></code>:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">ul</span><span class="p">&gt;</span>
<span class="cp">{%</span> <span class="k">for</span> <span class="nv">athlete</span> <span class="k">in</span> <span class="nv">athlete_list</span> <span class="cp">%}</span>
    <span class="p">&lt;</span><span class="nt">li</span><span class="p">&gt;</span><span class="cp">{{</span> <span class="nv">athlete.name</span> <span class="cp">}}</span><span class="p">&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="p">&lt;/</span><span class="nt">ul</span><span class="p">&gt;</span>
</pre></div>
</div>
</dd>
<dt><a class="reference internal" href="builtins.html#std-templatetag-if"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">if</span></code></a>, <code class="docutils literal notranslate"><span class="pre">elif</span></code> et <code class="docutils literal notranslate"><span class="pre">else</span></code></dt><dd><p>Évalue une variable, et si cette variable vaut <code class="docutils literal notranslate"><span class="pre">True</span></code>, le contenu du bloc est affiché :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">if</span> <span class="nv">athlete_list</span> <span class="cp">%}</span>
    Number of athletes: <span class="cp">{{</span> <span class="nv">athlete_list</span><span class="o">|</span><span class="nf">length</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">elif</span> <span class="nv">athlete_in_locker_room_list</span> <span class="cp">%}</span>
    Athletes should be out of the locker room soon!
<span class="cp">{%</span> <span class="k">else</span> <span class="cp">%}</span>
    No athletes.
<span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>Dans l’exemple ci-dessus, si <code class="docutils literal notranslate"><span class="pre">athlete_list</span></code> n’est pas vide, le nombre d’athlètes est affiché par la variable <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">athlete_list|length</span> <span class="pre">}}</span></code>. Sinon, dans le cas où <code class="docutils literal notranslate"><span class="pre">athlete_in_locker_room_list</span></code> n’est pas vide, le message « Athletes should be out… » sera affiché. Si les deux listes sont vides, c’est « No athletes. » qui sera affiché.</p>
<p>Vous pouvez également utiliser des filtres et différents opérateurs dans la balise <a class="reference internal" href="builtins.html#std-templatetag-if"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">if</span></code></a>:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">if</span> <span class="nv">athlete_list</span><span class="o">|</span><span class="nf">length</span> <span class="o">&gt;</span> <span class="m">1</span> <span class="cp">%}</span>
   Team: <span class="cp">{%</span> <span class="k">for</span> <span class="nv">athlete</span> <span class="k">in</span> <span class="nv">athlete_list</span> <span class="cp">%}</span> ... <span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">else</span> <span class="cp">%}</span>
   Athlete: <span class="cp">{{</span> <span class="nv">athlete_list.0.name</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>Même si l’exemple ci-dessus fonctionne, il faut savoir que la plupart des filtres de gabarit renvoient du texte, et que donc les comparaisons mathématiques impliquant des filtres fonctionnent rarement comme prévu. <a class="reference internal" href="builtins.html#std-templatefilter-length"><code class="xref std std-tfilter docutils literal notranslate"><span class="pre">length</span></code></a> est une exception.</p>
</dd>
<dt><a class="reference internal" href="builtins.html#std-templatetag-block"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">block</span></code></a> et <a class="reference internal" href="builtins.html#std-templatetag-extends"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">extends</span></code></a></dt><dd><p>Définit l”<a class="reference internal" href="#id1">héritage de gabarits</a> (voir ci-dessous), une manière puissante d’éliminer les contenus redondants au niveau des gabarits.</p>
</dd>
</dl>
<p>Les exemples ci-dessus ne sont qu’une sélection de la liste complète ; voir la <a class="reference internal" href="builtins.html#ref-templates-builtins-tags"><span class="std std-ref">référence des balises intégrées</span></a> pour une liste complète.</p>
<p>Vous pouvez aussi créer vos propres balises de gabarit ; voir <a class="reference internal" href="../../howto/custom-template-tags.html"><span class="doc">Création de balises et filtres de gabarit personnalisés</span></a>.</p>
<div class="admonition seealso">
<p class="admonition-title">Voir aussi</p>
<p>L’interface d’administration de Django peut inclure une référence complète de tous les filtres et balises de gabarit disponibles pour un site donné. Voir <a class="reference internal" href="../contrib/admin/admindocs.html"><span class="doc">Le générateur de documentation de l’administration de Django</span></a>.</p>
</div>
</section>
<section id="s-comments">
<span id="s-template-comments"></span><span id="comments"></span><span id="template-comments"></span><h2>Commentaires<a class="headerlink" href="#comments" title="Lien vers cette rubrique">¶</a></h2>
<p>Pour commenter une partie de ligne dans un gabarit, utilisez la syntaxe de commentaire : <code class="docutils literal notranslate"><span class="pre">{#</span> <span class="pre">#}</span></code>.</p>
<p>Par exemple, ce gabarit produit le contenu <code class="docutils literal notranslate"><span class="pre">'hello'</span></code>:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="c">{# greeting #}</span>hello
</pre></div>
</div>
<p>Un commentaire peut contenir n’importe quel code de gabarit, valide ou non. Par exemple :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="c">{# {% if foo %}bar{% else %} #}</span>
</pre></div>
</div>
<p>Cette syntaxe n’est utilisable que pour les commentaires d’une seule ligne (aucun saut de ligne n’est autorisé entre les délimiteurs <code class="docutils literal notranslate"><span class="pre">{#</span></code> et <code class="docutils literal notranslate"><span class="pre">#}</span></code>). Si vous avez besoin de mettre en commentaire plusieurs lignes d’un gabarit, référez-vous à la balise <a class="reference internal" href="builtins.html#std-templatetag-comment"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">comment</span></code></a>.</p>
</section>
<section id="s-template-inheritance">
<span id="s-id1"></span><span id="template-inheritance"></span><span id="id1"></span><h2>Héritage de gabarits<a class="headerlink" href="#template-inheritance" title="Lien vers cette rubrique">¶</a></h2>
<p>La partie la plus puissante, mais aussi la plus complexe, du moteur de gabarits de Django est l’héritage des gabarits. Cet héritage permet de construire un gabarit « squelette » de base contenant tous les éléments communs de votre site et de définir des <strong>blocs</strong> que les gabarits enfants peuvent surcharger.</p>
<p>Examinons l’héritage des gabarits en commençant par un exemple :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">&lt;!DOCTYPE html&gt;</span>
<span class="p">&lt;</span><span class="nt">html</span> <span class="na">lang</span><span class="o">=</span><span class="s">&quot;en&quot;</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">head</span><span class="p">&gt;</span>
    <span class="p">&lt;</span><span class="nt">link</span> <span class="na">rel</span><span class="o">=</span><span class="s">&quot;stylesheet&quot;</span> <span class="na">href</span><span class="o">=</span><span class="s">&quot;style.css&quot;</span><span class="p">&gt;</span>
    <span class="p">&lt;</span><span class="nt">title</span><span class="p">&gt;</span><span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}</span>My amazing site<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span><span class="p">&lt;/</span><span class="nt">title</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">head</span><span class="p">&gt;</span>

<span class="p">&lt;</span><span class="nt">body</span><span class="p">&gt;</span>
    <span class="p">&lt;</span><span class="nt">div</span> <span class="na">id</span><span class="o">=</span><span class="s">&quot;sidebar&quot;</span><span class="p">&gt;</span>
        <span class="cp">{%</span> <span class="k">block</span> <span class="nv">sidebar</span> <span class="cp">%}</span>
        <span class="p">&lt;</span><span class="nt">ul</span><span class="p">&gt;</span>
            <span class="p">&lt;</span><span class="nt">li</span><span class="p">&gt;&lt;</span><span class="nt">a</span> <span class="na">href</span><span class="o">=</span><span class="s">&quot;/&quot;</span><span class="p">&gt;</span>Home<span class="p">&lt;/</span><span class="nt">a</span><span class="p">&gt;&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
            <span class="p">&lt;</span><span class="nt">li</span><span class="p">&gt;&lt;</span><span class="nt">a</span> <span class="na">href</span><span class="o">=</span><span class="s">&quot;/blog/&quot;</span><span class="p">&gt;</span>Blog<span class="p">&lt;/</span><span class="nt">a</span><span class="p">&gt;&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
        <span class="p">&lt;/</span><span class="nt">ul</span><span class="p">&gt;</span>
        <span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
    <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>

    <span class="p">&lt;</span><span class="nt">div</span> <span class="na">id</span><span class="o">=</span><span class="s">&quot;content&quot;</span><span class="p">&gt;</span>
        <span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
    <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">body</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">html</span><span class="p">&gt;</span>
</pre></div>
</div>
<p>Ce gabarit que nous appellerons <code class="docutils literal notranslate"><span class="pre">base.html</span></code> définit un squelette de document HTML qui pourrait être employé pour une page sur deux colonnes. C’est le travail des gabarits « enfants » de remplir les blocs vides avec du contenu.</p>
<p>Dans cet exemple, la balise <a class="reference internal" href="builtins.html#std-templatetag-block"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">block</span></code></a> définit trois blocs que les gabarits enfants peuvent remplir. La balise <a class="reference internal" href="builtins.html#std-templatetag-block"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">block</span></code></a> ne fait que signaler au moteur de gabarits qu’un gabarit enfant peut surcharger ces portions du gabarit.</p>
<p>Un gabarit enfant pourrait ressembler à ceci :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">extends</span> <span class="s2">&quot;base.html&quot;</span> <span class="cp">%}</span>

<span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}</span>My amazing blog<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>

<span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">for</span> <span class="nv">entry</span> <span class="k">in</span> <span class="nv">blog_entries</span> <span class="cp">%}</span>
    <span class="p">&lt;</span><span class="nt">h2</span><span class="p">&gt;</span><span class="cp">{{</span> <span class="nv">entry.title</span> <span class="cp">}}</span><span class="p">&lt;/</span><span class="nt">h2</span><span class="p">&gt;</span>
    <span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span><span class="cp">{{</span> <span class="nv">entry.body</span> <span class="cp">}}</span><span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;</span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>La balise <a class="reference internal" href="builtins.html#std-templatetag-extends"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">extends</span></code></a> est ici la clé. Elle indique au moteur de gabarits que ce gabarit « étend » un autre gabarit. Lorsque le moteur de gabarits l’évalue, il récupère d’abord le parent, dans ce cas « base.html ».</p>
<p>À ce stade, le moteur de gabarits remarque les trois balises <a class="reference internal" href="builtins.html#std-templatetag-block"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">block</span></code></a> de <code class="docutils literal notranslate"><span class="pre">base.html</span></code> et remplace ces blocs par le contenu du gabarit enfant. En fonction de la valeur de <code class="docutils literal notranslate"><span class="pre">blog_entries</span></code>, le résultat pourrait ressembler à :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">&lt;!DOCTYPE html&gt;</span>
<span class="p">&lt;</span><span class="nt">html</span> <span class="na">lang</span><span class="o">=</span><span class="s">&quot;en&quot;</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">head</span><span class="p">&gt;</span>
    <span class="p">&lt;</span><span class="nt">link</span> <span class="na">rel</span><span class="o">=</span><span class="s">&quot;stylesheet&quot;</span> <span class="na">href</span><span class="o">=</span><span class="s">&quot;style.css&quot;</span><span class="p">&gt;</span>
    <span class="p">&lt;</span><span class="nt">title</span><span class="p">&gt;</span>My amazing blog<span class="p">&lt;/</span><span class="nt">title</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">head</span><span class="p">&gt;</span>

<span class="p">&lt;</span><span class="nt">body</span><span class="p">&gt;</span>
    <span class="p">&lt;</span><span class="nt">div</span> <span class="na">id</span><span class="o">=</span><span class="s">&quot;sidebar&quot;</span><span class="p">&gt;</span>
        <span class="p">&lt;</span><span class="nt">ul</span><span class="p">&gt;</span>
            <span class="p">&lt;</span><span class="nt">li</span><span class="p">&gt;&lt;</span><span class="nt">a</span> <span class="na">href</span><span class="o">=</span><span class="s">&quot;/&quot;</span><span class="p">&gt;</span>Home<span class="p">&lt;/</span><span class="nt">a</span><span class="p">&gt;&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
            <span class="p">&lt;</span><span class="nt">li</span><span class="p">&gt;&lt;</span><span class="nt">a</span> <span class="na">href</span><span class="o">=</span><span class="s">&quot;/blog/&quot;</span><span class="p">&gt;</span>Blog<span class="p">&lt;/</span><span class="nt">a</span><span class="p">&gt;&lt;/</span><span class="nt">li</span><span class="p">&gt;</span>
        <span class="p">&lt;/</span><span class="nt">ul</span><span class="p">&gt;</span>
    <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>

    <span class="p">&lt;</span><span class="nt">div</span> <span class="na">id</span><span class="o">=</span><span class="s">&quot;content&quot;</span><span class="p">&gt;</span>
        <span class="p">&lt;</span><span class="nt">h2</span><span class="p">&gt;</span>Entry one<span class="p">&lt;/</span><span class="nt">h2</span><span class="p">&gt;</span>
        <span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span>This is my first entry.<span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;</span>

        <span class="p">&lt;</span><span class="nt">h2</span><span class="p">&gt;</span>Entry two<span class="p">&lt;/</span><span class="nt">h2</span><span class="p">&gt;</span>
        <span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span>This is my second entry.<span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;</span>
    <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">body</span><span class="p">&gt;</span>
<span class="p">&lt;/</span><span class="nt">html</span><span class="p">&gt;</span>
</pre></div>
</div>
<p>Notez que comme le gabarit enfant n’a pas défini le bloc <code class="docutils literal notranslate"><span class="pre">sidebar</span></code>, c’est la valeur provenant du gabarit parent qui est utilisée. C’est toujours le contenu de la balise <code class="docutils literal notranslate"><span class="pre">{%</span> <span class="pre">block</span> <span class="pre">%}</span></code> du gabarit parent qui est utilisé comme contenu par défaut.</p>
<p>Vous pouvez utiliser autant de niveaux d’héritage que nécessaire. Une façon courante d’utiliser l’héritage est l’approche à trois niveaux suivante :</p>
<ul class="simple">
<li><p>Créer un gabarit <code class="docutils literal notranslate"><span class="pre">base.html</span></code> contenant l’apparence principale du site.</p></li>
<li><p>Créer un gabarit <code class="docutils literal notranslate"><span class="pre">base_NOMSECTION.html</span></code> pour chaque section du site. Par exemple, <code class="docutils literal notranslate"><span class="pre">base_actualites.html</span></code>, <code class="docutils literal notranslate"><span class="pre">base_sports.html</span></code>. Tous ces gabarits étendent <code class="docutils literal notranslate"><span class="pre">base.html</span></code> et contiennent le style et l’aspect spécifiques à la section.</p></li>
<li><p>Créer des gabarits individuels pour chaque type de page, tel qu’un article d’actualité ou un article de blog. Ces gabarits étendent le gabarit de la section dans laquelle ils figurent.</p></li>
</ul>
<p>Cette approche maximise la réutilisation de code et facilite l’ajout d’éléments aux zones de contenu partagé, telle que la navigation propre à la section.</p>
<p>Voici quelques astuces concernant l’héritage :</p>
<ul>
<li><p>Si vous utilisez <a class="reference internal" href="builtins.html#std-templatetag-extends"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">{%</span> <span class="pre">extends</span> <span class="pre">%}</span></code></a> dans un gabarit, cela doit être la première balise dans ce gabarit. Sinon, l’héritage des gabarits ne fonctionnera pas.</p></li>
<li><p>Ne soyez pas économe de balises <a class="reference internal" href="builtins.html#std-templatetag-block"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">{%</span> <span class="pre">block</span> <span class="pre">%}</span></code></a> dans vos gabarits de base. Rappelez-vous que les gabarits enfants ne doivent pas redéfinir tous les blocs du parent, vous pouvez donc placer du contenu généraliste dans certains blocs et ne redéfinir que ce qui est nécessaire dans les gabarits enfants. Il est préférable d’avoir trop de points d’insertion que d’en manquer.</p></li>
<li><p>Si vous vous retrouvez à dupliquer du contenu dans plusieurs gabarits, cela signifie probablement que vous devriez placer ce contenu dans un <code class="docutils literal notranslate"><span class="pre">{%</span> <span class="pre">block</span> <span class="pre">%}</span></code> d’un gabarit parent.</p></li>
<li><p>Si vous avez besoin de reproduire le contenu du bloc du gabarit parent, la variable <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">block.super</span> <span class="pre">}}</span></code> fera l’affaire. C’est utile lorsque vous voulez compléter le contenu d’un bloc parent plutôt que de l’écraser simplement. Les données insérées par <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">block.super</span> <span class="pre">}}</span></code> ne sont pas échappées automatiquement (voir la <a class="reference external" href="#automatic-html-escaping">section suivante</a>) puisqu’elles ont déjà été échappées dans le gabarit parent, si nécessaire.</p></li>
<li><p>En utilisant le même nom de gabarit que celui dont vous héritez, <a class="reference internal" href="builtins.html#std-templatetag-extends"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">{%</span> <span class="pre">extends</span> <span class="pre">%}</span></code></a> peut être utilisé pour hériter d’un gabarit tout en le surchargeant. Combiné avec <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">block.super</span> <span class="pre">}}</span></code>, il s’agit d’un puissant moyen de faire de petits ajustements. Consultez <a class="reference internal" href="../../howto/overriding-templates.html#extending-an-overridden-template"><span class="std std-ref">Extension d’un gabarit surchargé</span></a> dans le guide de la <em>Surcharge de gabarits</em> pour voir un exemple complet.</p></li>
<li><p>Les variables créées en dehors d’un bloc <a class="reference internal" href="builtins.html#std-templatetag-block"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">{%</span> <span class="pre">block</span> <span class="pre">%}</span></code></a> en utilisant la syntaxe de balise de gabarit <code class="docutils literal notranslate"><span class="pre">as</span></code> ne peuvent pas être utilisées à l’intérieur du bloc. Par exemple, ce gabarit ne produira rien du tout :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">translate</span> <span class="s2">&quot;Title&quot;</span> <span class="k">as</span> <span class="nv">title</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}{{</span> <span class="nv">title</span> <span class="cp">}}{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
</pre></div>
</div>
</li>
<li><p>Pour une meilleure lisibilité, vous pouvez donner un <em>nom</em> à votre balise <code class="docutils literal notranslate"><span class="pre">{%</span> <span class="pre">endblock</span> <span class="pre">%}</span></code>. Par exemple :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}</span>
...
<span class="cp">{%</span> <span class="k">endblock</span> <span class="nv">content</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>Dans les gros gabarits, cette technique permet de mieux voir quelle est la balise <code class="docutils literal notranslate"><span class="pre">{%</span> <span class="pre">block</span> <span class="pre">%}</span></code> que cette balise ferme.</p>
</li>
<li><p>Les balises <a class="reference internal" href="builtins.html#std-templatetag-block"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">{%</span> <span class="pre">block</span> <span class="pre">%}</span></code></a> sont évaluées en premier. C’est pourquoi le contenu d’un bloc est toujours écrasé, quelle que soit la valeur booléenne des balises environnantes. Par exemple, ce gabarit va <em>toujours</em> écraser le contenu du bloc <code class="docutils literal notranslate"><span class="pre">title</span></code> :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">if</span> <span class="nv">change_title</span> <span class="cp">%}</span>
    <span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}</span>Hello!<span class="cp">{%</span> <span class="k">endblock</span> <span class="nv">title</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endif</span> <span class="cp">%}</span>
</pre></div>
</div>
</li>
</ul>
<p>Pour terminer, notez que vous ne pouvez pas définir plusieurs balises <a class="reference internal" href="builtins.html#std-templatetag-block"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">block</span></code></a> ayant le même nom dans le même gabarit. Cette restriction existe parce qu’une balise <code class="docutils literal notranslate"><span class="pre">block</span></code> fonctionne dans les « deux » sens. C’est-à-dire qu’une balise <code class="docutils literal notranslate"><span class="pre">block</span></code> ne fait pas que définir un vide à combler, elle définit aussi le contenu qui comble ce vide dans le <em>parent</em>. S’il y avait deux balises <a class="reference internal" href="builtins.html#std-templatetag-block"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">block</span></code></a> ayant le même nom dans un gabarit, le parent de ce gabarit ne saurait pas de quel bloc le contenu doit être pris en compte.</p>
</section>
<section id="s-template-partials">
<span id="s-id2"></span><span id="template-partials"></span><span id="id2"></span><h2>Template partials<a class="headerlink" href="#template-partials" title="Lien vers cette rubrique">¶</a></h2>
<div class="versionadded">
<span class="title">New in Django 6.0.</span> </div>
<p>Template partials define reusable template fragments within a template file.
They are self-contained components that can be rendered multiple times within
the same template, helping to avoid repetition and maintain consistent output.</p>
<section id="s-basic-syntax">
<span id="basic-syntax"></span><h3>Basic syntax<a class="headerlink" href="#basic-syntax" title="Lien vers cette rubrique">¶</a></h3>
<p>A partial can be defined using the <a class="reference internal" href="builtins.html#std-templatetag-partialdef"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">partialdef</span></code></a> tag:</p>
<div class="literal-block-wrapper docutils container" id="id5">
<div class="code-block-caption"><span class="caption-text"><code class="docutils literal notranslate"><span class="pre">authors.html</span></code></span><a class="headerlink" href="#id5" title="Lien vers ce code">¶</a></div>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">partialdef</span> <span class="nv">user-info</span> <span class="cp">%}</span>
    <span class="p">&lt;</span><span class="nt">div</span> <span class="na">id</span><span class="o">=</span><span class="s">&quot;user-info-</span><span class="cp">{{</span> <span class="nv">user.username</span> <span class="cp">}}</span><span class="s">&quot;</span><span class="p">&gt;</span>
        <span class="p">&lt;</span><span class="nt">h3</span><span class="p">&gt;</span><span class="cp">{{</span> <span class="nv">user.name</span> <span class="cp">}}</span><span class="p">&lt;/</span><span class="nt">h3</span><span class="p">&gt;</span>
        <span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span><span class="cp">{{</span> <span class="nv">user.bio</span> <span class="cp">}}</span><span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;</span>
    <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
<span class="cp">{%</span> <span class="k">endpartialdef</span> <span class="cp">%}</span>
</pre></div>
</div>
</div>
<p>For extra readability, the name can be included in the <code class="docutils literal notranslate"><span class="pre">{%</span> <span class="pre">endpartialdef</span> <span class="pre">%}</span></code>
closing tag:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">partialdef</span> <span class="nv">user-info</span> <span class="cp">%}</span>
    <span class="c">{# ... #}</span>
<span class="cp">{%</span> <span class="k">endpartialdef</span> <span class="nv">user-info</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>The template fragment can be rendered using the <a class="reference internal" href="builtins.html#std-templatetag-partial"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">partial</span></code></a> tag:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">partial</span> <span class="nv">user-info</span> <span class="cp">%}</span>
</pre></div>
</div>
</section>
<section id="s-fragment-reuse">
<span id="fragment-reuse"></span><h3>Fragment reuse<a class="headerlink" href="#fragment-reuse" title="Lien vers cette rubrique">¶</a></h3>
<p>A template fragment can be reused multiple times:</p>
<div class="literal-block-wrapper docutils container" id="id6">
<div class="code-block-caption"><span class="caption-text"><code class="docutils literal notranslate"><span class="pre">authors.html</span></code></span><a class="headerlink" href="#id6" title="Lien vers ce code">¶</a></div>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}</span>
    <span class="p">&lt;</span><span class="nt">h2</span><span class="p">&gt;</span>Authors<span class="p">&lt;/</span><span class="nt">h2</span><span class="p">&gt;</span>
    <span class="cp">{%</span> <span class="k">for</span> <span class="nv">user</span> <span class="k">in</span> <span class="nv">authors</span> <span class="cp">%}</span>
        <span class="cp">{%</span> <span class="k">partial</span> <span class="nv">user-info</span> <span class="cp">%}</span>
    <span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>

    <span class="p">&lt;</span><span class="nt">h2</span><span class="p">&gt;</span>Editors<span class="p">&lt;/</span><span class="nt">h2</span><span class="p">&gt;</span>
    <span class="cp">{%</span> <span class="k">for</span> <span class="nv">user</span> <span class="k">in</span> <span class="nv">editors</span> <span class="cp">%}</span>
        <span class="cp">{%</span> <span class="k">partial</span> <span class="nv">user-info</span> <span class="cp">%}</span>
    <span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
</pre></div>
</div>
</div>
<p>The partial content is rendered each time the named partial is used, with the
current template context.</p>
</section>
<section id="s-inline-partials">
<span id="s-template-partials-inline"></span><span id="inline-partials"></span><span id="template-partials-inline"></span><h3>Inline partials<a class="headerlink" href="#inline-partials" title="Lien vers cette rubrique">¶</a></h3>
<p>A template fragment can be defined and rendered in-place using the <code class="docutils literal notranslate"><span class="pre">inline</span></code>
argument. This defines the partial for later reuse while also rendering it
immediately at its definition:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="c">{# Define and render immediately. #}</span>
<span class="cp">{%</span> <span class="k">partialdef</span> <span class="nv">user-info</span> <span class="nv">inline</span> <span class="cp">%}</span>
    <span class="p">&lt;</span><span class="nt">div</span> <span class="na">id</span><span class="o">=</span><span class="s">&quot;user-info-</span><span class="cp">{{</span> <span class="nv">user.username</span> <span class="cp">}}</span><span class="s">&quot;</span><span class="p">&gt;</span>
        <span class="p">&lt;</span><span class="nt">h3</span><span class="p">&gt;</span><span class="cp">{{</span> <span class="nv">user.name</span> <span class="cp">}}</span><span class="p">&lt;/</span><span class="nt">h3</span><span class="p">&gt;</span>
        <span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span><span class="cp">{{</span> <span class="nv">user.bio</span> <span class="cp">}}</span><span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;</span>
    <span class="p">&lt;/</span><span class="nt">div</span><span class="p">&gt;</span>
<span class="cp">{%</span> <span class="k">endpartialdef</span> <span class="cp">%}</span>

<span class="c">{# Other page content here. #}</span>

<span class="c">{# Reuse later elsewhere in the template. #}</span>
<span class="p">&lt;</span><span class="nt">section</span> <span class="na">class</span><span class="o">=</span><span class="s">&quot;featured-authors&quot;</span><span class="p">&gt;</span>
    <span class="p">&lt;</span><span class="nt">h2</span><span class="p">&gt;</span>Featured Authors<span class="p">&lt;/</span><span class="nt">h2</span><span class="p">&gt;</span>
    <span class="cp">{%</span> <span class="k">for</span> <span class="nv">user</span> <span class="k">in</span> <span class="nv">featured</span> <span class="cp">%}</span>
        <span class="cp">{%</span> <span class="k">partial</span> <span class="nv">user-info</span> <span class="cp">%}</span>
    <span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
<span class="p">&lt;/</span><span class="nt">section</span><span class="p">&gt;</span>
</pre></div>
</div>
</section>
<section id="s-accessing-partials-directly">
<span id="s-template-partials-direct-access"></span><span id="accessing-partials-directly"></span><span id="template-partials-direct-access"></span><h3>Accessing partials directly<a class="headerlink" href="#accessing-partials-directly" title="Lien vers cette rubrique">¶</a></h3>
<p>Template fragments defined with <a class="reference internal" href="builtins.html#std-templatetag-partialdef"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">partialdef</span></code></a> can be accessed directly via
template loading or inclusion using the <code class="docutils literal notranslate"><span class="pre">template.html#partial_name</span></code> syntax.</p>
<p>For example, using the <a class="reference internal" href="../../topics/http/shortcuts.html#django.shortcuts.render" title="django.shortcuts.render"><code class="xref py py-func docutils literal notranslate"><span class="pre">render()</span></code></a> shortcut, the following
code renders only the partial named <code class="docutils literal notranslate"><span class="pre">user-info</span></code> defined in the
<code class="docutils literal notranslate"><span class="pre">authors.html</span></code> template:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span><span class="w"> </span><span class="nn">django.contrib.auth.models</span><span class="w"> </span><span class="kn">import</span> <span class="n">User</span>
<span class="kn">from</span><span class="w"> </span><span class="nn">django.shortcuts</span><span class="w"> </span><span class="kn">import</span> <span class="n">get_object_or_404</span><span class="p">,</span> <span class="n">render</span>


<span class="k">def</span><span class="w"> </span><span class="nf">user_info_partial</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="n">user_id</span><span class="p">):</span>
    <span class="n">user</span> <span class="o">=</span> <span class="n">get_object_or_404</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="nb">id</span><span class="o">=</span><span class="n">user_id</span><span class="p">)</span>
    <span class="k">return</span> <span class="n">render</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="s2">&quot;authors.html#user-info&quot;</span><span class="p">,</span> <span class="p">{</span><span class="s2">&quot;user&quot;</span><span class="p">:</span> <span class="n">user</span><span class="p">})</span>
</pre></div>
</div>
<p>This approach is particularly useful for AJAX-style requests that update only
specific portions of a page with the rendered template fragment.</p>
<p>Template partials can also be included using the <a class="reference internal" href="builtins.html#std-templatetag-include"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">include</span></code></a> template tag
with the same <code class="docutils literal notranslate"><span class="pre">#</span></code> directive:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">include</span> <span class="s2">&quot;authors.html#user-info&quot;</span> <span class="cp">%}</span>
</pre></div>
</div>
</section>
<section id="s-context-handling">
<span id="context-handling"></span><h3>Context handling<a class="headerlink" href="#context-handling" title="Lien vers cette rubrique">¶</a></h3>
<p>Template partials are rendered with the current template context. They work as
expected in loops and with context variables:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">for</span> <span class="nv">user</span> <span class="k">in</span> <span class="nv">users</span> <span class="cp">%}</span>
    <span class="cp">{%</span> <span class="k">partial</span> <span class="nv">user-info</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>Context variables can be adjusted using the <a class="reference internal" href="builtins.html#std-templatetag-with"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">with</span></code></a> tag:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">with</span> <span class="nv">user</span><span class="o">=</span><span class="nv">featured_author</span> <span class="cp">%}</span>
    <span class="p">&lt;</span><span class="nt">h2</span><span class="p">&gt;</span>Featured Author of the Month<span class="p">&lt;/</span><span class="nt">h2</span><span class="p">&gt;</span>
    <span class="cp">{%</span> <span class="k">partial</span> <span class="nv">user-info</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endwith</span> <span class="cp">%}</span>
</pre></div>
</div>
</section>
</section>
<section id="s-automatic-html-escaping">
<span id="s-id3"></span><span id="automatic-html-escaping"></span><span id="id3"></span><h2>Échappement HTML automatique<a class="headerlink" href="#automatic-html-escaping" title="Lien vers cette rubrique">¶</a></h2>
<p>Lors de la production de HTML avec les gabarits, il y a toujours un risque qu’une variable inclue des caractères qui altèrent le HTML produit. Par exemple, considérez cet extrait de gabarit :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span>Hello, <span class="cp">{{</span> <span class="nv">name</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>Au premier abord, cela semble une manière inoffensive d’afficher un nom d’utilisateur, mais imaginez ce qui se produit si l’utilisateur a saisi son nom comme ceci :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">script</span><span class="p">&gt;</span><span class="nx">alert</span><span class="p">(</span><span class="s1">&#39;hello&#39;</span><span class="p">)&lt;/</span><span class="nt">script</span><span class="p">&gt;</span>
</pre></div>
</div>
<p>Avec cette valeur pour le nom, le gabarit serait produit comme ceci :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span>Hello, <span class="p">&lt;</span><span class="nt">script</span><span class="p">&gt;</span><span class="nx">alert</span><span class="p">(</span><span class="s1">&#39;hello&#39;</span><span class="p">)&lt;/</span><span class="nt">script</span><span class="p">&gt;</span>
</pre></div>
</div>
<p>… ce qui signifie que le navigateur afficherait une fenêtre d’alerte JavaScript !</p>
<p>De la même manière, que se passe-t-il si le nom contient un symbole <code class="docutils literal notranslate"><span class="pre">'&lt;'</span></code> comme ceci ?</p>
<div class="highlight-html notranslate"><div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">b</span><span class="p">&gt;</span>username
</pre></div>
</div>
<p>Cela aboutit à l’affichage d’un résultat de gabarit comme ceci :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span>Hello, <span class="p">&lt;</span><span class="nt">b</span><span class="p">&gt;</span>username
</pre></div>
</div>
<p>…ce qui ferait que tout le reste de la page web serait affiché en gras !</p>
<p>Clairement, il ne faut pas se fier aveuglément aux données envoyées par les utilisateurs en les insérant directement dans vos pages web, car un utilisateur malveillant pourrait exploiter ce genre de faille dans une mauvaise perspective. Ce type de faille de sécurité est appelé une attaque <a class="reference external" href="https://en.wikipedia.org/wiki/Cross-site_scripting">Cross Site Scripting</a> (XSS).</p>
<p>Pour éviter ce problème, vous avez deux options :</p>
<ul class="simple">
<li><p>Premièrement, vous pouvez vous efforcer de faire passer ces variables non sécurisées par le filtre <a class="reference internal" href="builtins.html#std-templatefilter-escape"><code class="xref std std-tfilter docutils literal notranslate"><span class="pre">escape</span></code></a> (documenté ci-dessous), qui convertit les caractères HTML potentiellement dangereux en caractères inoffensifs. C’est la solution par défaut choisie par Django dans ses premières années, mais le problème est que la pression est sur <em>vous</em>, développeur ou auteur de gabarit, qui devez vous assurer que tout soit bien échappé. Il est très vite fait d’oublier d’échapper des données.</p></li>
<li><p>Deuxièmement, vous pouvez profiter de l’échappement automatique de HTML que Django effectue. Le reste de cette section décrit le fonctionnement de l’échappement automatique.</p></li>
</ul>
<p>Par défaut dans Django, chaque gabarit échappe automatiquement le résultat de chaque balise de variable. Plus précisément, ces cinq caractères sont échappés :</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">&lt;</span></code> est converti en <code class="docutils literal notranslate"><span class="pre">&amp;lt;</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">&gt;</span></code> est converti en <code class="docutils literal notranslate"><span class="pre">&amp;gt;</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">'</span></code> (apostrophe) est converti en <code class="docutils literal notranslate"><span class="pre">&amp;#x27;</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">&quot;</span></code> (guillemet) est converti en <code class="docutils literal notranslate"><span class="pre">&amp;quot;</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">&amp;</span></code> est converti en <code class="docutils literal notranslate"><span class="pre">&amp;amp;</span></code></p></li>
</ul>
<p>Nous répétons ici que ce comportement est actif par défaut. Si vous utilisez le système des gabarits de Django, vous êtes protégé.</p>
<section id="s-how-to-turn-it-off">
<span id="how-to-turn-it-off"></span><h3>Comment désactiver l’échappement automatique<a class="headerlink" href="#how-to-turn-it-off" title="Lien vers cette rubrique">¶</a></h3>
<p>Si vous ne voulez pas que les données soient échappées automatiquement, au niveau d’un site, d’un gabarit ou d’une variable, vous pouvez le désactiver de plusieurs manières.</p>
<p>Pourquoi vouloir désactiver ce comportement ? Parce qu’il peut arriver parfois que des variables de gabarit contiennent des données que vous voulez vraiment afficher comme contenu HTML brut, auquel cas vous ne souhaitez pas que ces contenus soient échappés. Par exemple, vous stockez peut-être du code HTML dans votre base de données afin de l’intégrer tel quel dans un gabarit. Un autre exemple est quand vous voulez utiliser le système des gabarits de Django pour produire du texte <em>non</em> HTML, comme un message électronique.</p>
<section id="s-for-individual-variables">
<span id="for-individual-variables"></span><h4>Pour des variables individuelles<a class="headerlink" href="#for-individual-variables" title="Lien vers cette rubrique">¶</a></h4>
<p>Pour désactiver l’échappement automatique pour une variable individuelle, utilisez le filtre <a class="reference internal" href="builtins.html#std-templatefilter-safe"><code class="xref std std-tfilter docutils literal notranslate"><span class="pre">safe</span></code></a>:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span>This will be escaped: <span class="cp">{{</span> <span class="nv">data</span> <span class="cp">}}</span>
This will not be escaped: <span class="cp">{{</span> <span class="nv">data</span><span class="o">|</span><span class="nf">safe</span> <span class="cp">}}</span>
</pre></div>
</div>
<p><code class="docutils literal notranslate"><span class="pre">safe</span></code> (sûr en anglais) peut être considéré comme un raccourci de <em>sûr de ne pas nécessiter d’échappement</em> ou <em>peut être interprété en HTML de manière sûre</em>. Dans cet exemple, si <code class="docutils literal notranslate"><span class="pre">data</span></code> contient <code class="docutils literal notranslate"><span class="pre">'&lt;b&gt;'</span></code>, le résultat affiché sera :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span>This will be escaped: <span class="ni">&amp;lt;</span>b<span class="ni">&amp;gt;</span>
This will not be escaped: <span class="p">&lt;</span><span class="nt">b</span><span class="p">&gt;</span>
</pre></div>
</div>
</section>
<section id="s-for-template-blocks">
<span id="for-template-blocks"></span><h4>Pour des blocs de gabarits<a class="headerlink" href="#for-template-blocks" title="Lien vers cette rubrique">¶</a></h4>
<p>Pour contrôler l’échappement automatique dans un gabarit, entourez le gabarit (ou une portion du gabarit) par la balise <a class="reference internal" href="builtins.html#std-templatetag-autoescape"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">autoescape</span></code></a>, comme ceci :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">autoescape</span> <span class="nv">off</span> <span class="cp">%}</span>
    Hello <span class="cp">{{</span> <span class="nv">name</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">endautoescape</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>La balise <a class="reference internal" href="builtins.html#std-templatetag-autoescape"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">autoescape</span></code></a> accepte <code class="docutils literal notranslate"><span class="pre">on</span></code> ou <code class="docutils literal notranslate"><span class="pre">off</span></code> comme paramètre. Il est parfois souhaitable de forcer l’échappement automatique dans un contexte où il est désactivé. Voici un exemple de gabarit :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span>Auto-escaping is on by default. Hello <span class="cp">{{</span> <span class="nv">name</span> <span class="cp">}}</span>

<span class="cp">{%</span> <span class="k">autoescape</span> <span class="nv">off</span> <span class="cp">%}</span>
    This will not be auto-escaped: <span class="cp">{{</span> <span class="nv">data</span> <span class="cp">}}</span>.

    Nor this: <span class="cp">{{</span> <span class="nv">other_data</span> <span class="cp">}}</span>
    <span class="cp">{%</span> <span class="k">autoescape</span> <span class="nv">on</span> <span class="cp">%}</span>
        Auto-escaping applies again: <span class="cp">{{</span> <span class="nv">name</span> <span class="cp">}}</span>
    <span class="cp">{%</span> <span class="k">endautoescape</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endautoescape</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>La balise d’échappement automatique transmet ses effets aux gabarits qui étendent le gabarit en cours ainsi qu’aux gabarits inclus par la balise <a class="reference internal" href="builtins.html#std-templatetag-include"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">include</span></code></a>, comme pour toutes les balises de bloc. Par exemple :</p>
<div class="literal-block-wrapper docutils container" id="id7">
<div class="code-block-caption"><span class="caption-text"><code class="docutils literal notranslate"><span class="pre">base.html</span></code></span><a class="headerlink" href="#id7" title="Lien vers ce code">¶</a></div>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">autoescape</span> <span class="nv">off</span> <span class="cp">%}</span>
<span class="p">&lt;</span><span class="nt">h1</span><span class="p">&gt;</span><span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}{%</span> <span class="k">endblock</span> <span class="cp">%}</span><span class="p">&lt;/</span><span class="nt">h1</span><span class="p">&gt;</span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">endautoescape</span> <span class="cp">%}</span>
</pre></div>
</div>
</div>
<div class="literal-block-wrapper docutils container" id="id8">
<div class="code-block-caption"><span class="caption-text"><code class="docutils literal notranslate"><span class="pre">child.html</span></code></span><a class="headerlink" href="#id8" title="Lien vers ce code">¶</a></div>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">extends</span> <span class="s2">&quot;base.html&quot;</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">title</span> <span class="cp">%}</span>This <span class="ni">&amp;amp;</span> that<span class="cp">{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">block</span> <span class="nv">content</span> <span class="cp">%}{{</span> <span class="nv">greeting</span> <span class="cp">}}{%</span> <span class="k">endblock</span> <span class="cp">%}</span>
</pre></div>
</div>
</div>
<p>Comme l’échappement automatique est désactivé dans le gabarit de base, il sera aussi désactivé dans le gabarit enfant, ce qui aboutit par exemple au contenu HTML affiché suivant lorsque la variable <code class="docutils literal notranslate"><span class="pre">greeting</span></code> contient le texte <code class="docutils literal notranslate"><span class="pre">&lt;b&gt;Hello!&lt;/b&gt;</span></code>:</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="p">&lt;</span><span class="nt">h1</span><span class="p">&gt;</span>This <span class="ni">&amp;amp;</span> that<span class="p">&lt;/</span><span class="nt">h1</span><span class="p">&gt;</span>
<span class="p">&lt;</span><span class="nt">b</span><span class="p">&gt;</span>Hello!<span class="p">&lt;/</span><span class="nt">b</span><span class="p">&gt;</span>
</pre></div>
</div>
</section>
</section>
<section id="s-notes">
<span id="notes"></span><h3>Notes<a class="headerlink" href="#notes" title="Lien vers cette rubrique">¶</a></h3>
<p>Généralement, les rédacteurs de gabarits n’ont pas besoin de se préoccuper de l’échappement automatique. Les développeurs du côté Python (ceux qui écrivent les vues et les filtres personnalisés) doivent réfléchir aux situations dans lesquelles les données ne devraient pas subir d’échappement et marquer les données en conséquence, afin que tout fonctionne comme prévu dans les gabarits.</p>
<p>Si vous créez un gabarit pouvant être utilisé dans des situations où vous n’êtes pas sûr si l’échappement automatique est actif, ajoutez le filtre <a class="reference internal" href="builtins.html#std-templatefilter-escape"><code class="xref std std-tfilter docutils literal notranslate"><span class="pre">escape</span></code></a> à toute variable nécessitant l’échappement. Quand l’échappement automatique est actif, il n’y a pas de risque que que le filtre <a class="reference internal" href="builtins.html#std-templatefilter-escape"><code class="xref std std-tfilter docutils literal notranslate"><span class="pre">escape</span></code></a> <em>échappe doublement</em> les données car celui-ci ne touche pas aux variables ayant déjà subi l’échappement automatique.</p>
</section>
<section id="s-string-literals-and-automatic-escaping">
<span id="s-id4"></span><span id="string-literals-and-automatic-escaping"></span><span id="id4"></span><h3>Texte littéral et échappement automatique<a class="headerlink" href="#string-literals-and-automatic-escaping" title="Lien vers cette rubrique">¶</a></h3>
<p>Comme mentionné précédemment, les paramètres de filtres peuvent être des chaînes de caractères :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">data</span><span class="o">|</span><span class="nf">default</span><span class="s2">:&quot;This is a string literal.&quot;</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>Tout texte littéral est inséré <strong>sans</strong> échappement automatique dans le gabarit, comme s’il était systématiquement passé par le filtre <a class="reference internal" href="builtins.html#std-templatefilter-safe"><code class="xref std std-tfilter docutils literal notranslate"><span class="pre">safe</span></code></a>. La logique de ce comportement est que l’auteur du gabarit a le contrôle sur le contenu du texte, il peut donc s’assurer que le texte est correctement échappé au moment de la rédaction du gabarit.</p>
<p>Cela signifie qu’il faut écrire :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">data</span><span class="o">|</span><span class="nf">default</span><span class="s2">:&quot;3 &amp;lt; 2&quot;</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>…et non pas :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">data</span><span class="o">|</span><span class="nf">default</span><span class="s2">:&quot;3 &lt; 2&quot;</span> <span class="cp">}}</span>  <span class="c">{# Bad! Don&#39;t do this. #}</span>
</pre></div>
</div>
<p>Cela n’affecte pas les données provenant de la variable elle-même. Le contenu de la variable est toujours échappé automatiquement, si nécessaire, parce qu’il est hors du contrôle de l’auteur du gabarit.</p>
</section>
</section>
<section id="s-accessing-method-calls">
<span id="s-template-accessing-methods"></span><span id="accessing-method-calls"></span><span id="template-accessing-methods"></span><h2>Accès aux appels de méthodes<a class="headerlink" href="#accessing-method-calls" title="Lien vers cette rubrique">¶</a></h2>
<p>La plupart des appels de méthodes liées aux objets sont aussi disponibles depuis les gabarits. Cela signifie que les gabarits n’ont pas uniquement accès aux attributs de classe (comme les noms de champs) ou aux variables transmises depuis les vues. Par exemple, l’ORM de Django offre la syntaxe <a class="reference internal" href="../../topics/db/queries.html#topics-db-queries-related"><span class="std std-ref">« entry_set »</span></a> pour récupérer une collection d’objets liés par une clé étrangère. Ainsi, étant donné un modèle « comment » avec une relation clé étrangère vers un modèle « task », vous pouvez effectuer une boucle sur tous les commentaires liés à une tâche donnée comme ceci :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">for</span> <span class="nv">comment</span> <span class="k">in</span> <span class="nv">task.comment_set.all</span> <span class="cp">%}</span>
    <span class="cp">{{</span> <span class="nv">comment</span> <span class="cp">}}</span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>De même, les objets <a class="reference internal" href="../models/querysets.html"><span class="doc">QuerySets</span></a> offrent une méthode <code class="docutils literal notranslate"><span class="pre">count()</span></code> pour compter le nombre d’objets qu’ils contiennent. Vous pouvez donc obtenir le nombre de tous les commentaires liés à la tâche actuelle avec :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">task.comment_set.all.count</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>Vous pouvez aussi accéder aux méthodes que vous avez explicitement définies pour vos propres modèles :</p>
<div class="literal-block-wrapper docutils container" id="id9">
<div class="code-block-caption"><span class="caption-text"><code class="docutils literal notranslate"><span class="pre">models.py</span></code></span><a class="headerlink" href="#id9" title="Lien vers ce code">¶</a></div>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">Task</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
    <span class="k">def</span><span class="w"> </span><span class="nf">foo</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="k">return</span> <span class="s2">&quot;bar&quot;</span>
</pre></div>
</div>
</div>
<div class="literal-block-wrapper docutils container" id="id10">
<div class="code-block-caption"><span class="caption-text"><code class="docutils literal notranslate"><span class="pre">template.html</span></code></span><a class="headerlink" href="#id10" title="Lien vers ce code">¶</a></div>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{{</span> <span class="nv">task.foo</span> <span class="cp">}}</span>
</pre></div>
</div>
</div>
<p>Comme Django limite intentionnellement les traitements logiques possibles dans le langage de gabarit, il n’est pas possible de transmettre des paramètres aux appels de méthodes depuis les gabarits. Les données doivent être calculées dans les vues, puis transmises aux gabarits pour être affichées.</p>
</section>
<section id="s-custom-tag-and-filter-libraries">
<span id="s-loading-custom-template-libraries"></span><span id="custom-tag-and-filter-libraries"></span><span id="loading-custom-template-libraries"></span><h2>Bibliothèques de balises et filtres personnalisés<a class="headerlink" href="#custom-tag-and-filter-libraries" title="Lien vers cette rubrique">¶</a></h2>
<p>Certaines applications contiennent leurs propres bibliothèques de balises et de filtres. Pour y accéder à partir d’un gabarit, vérifiez que l’application se trouve dans <a class="reference internal" href="../settings.html#std-setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">INSTALLED_APPS</span></code></a> (nous aurions ajouté <code class="docutils literal notranslate"><span class="pre">'django.contrib.humanize'</span></code> pour cet exemple), puis utilisez la balise <a class="reference internal" href="builtins.html#std-templatetag-load"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">load</span></code></a> dans le gabarit :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">load</span> <span class="nv">humanize</span> <span class="cp">%}</span>

<span class="cp">{{</span> <span class="m">45000</span><span class="o">|</span><span class="nf">intcomma</span> <span class="cp">}}</span>
</pre></div>
</div>
<p>Ci-dessus, la balise <a class="reference internal" href="builtins.html#std-templatetag-load"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">load</span></code></a> charge la bibliothèque de balises <code class="docutils literal notranslate"><span class="pre">humanize</span></code>, ce qui permet ensuite d’utiliser le filtre <code class="docutils literal notranslate"><span class="pre">intcomma</span></code> dans le gabarit. Si <a class="reference internal" href="../contrib/admin/admindocs.html#module-django.contrib.admindocs" title="django.contrib.admindocs: Django's admin documentation generator."><code class="xref py py-mod docutils literal notranslate"><span class="pre">django.contrib.admindocs</span></code></a> est activée, vous pouvez consulter la section de documentation de votre interface d’administration pour trouver la liste des bibliothèques personnalisées dans votre installation.</p>
<p>La balise <a class="reference internal" href="builtins.html#std-templatetag-load"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">load</span></code></a> accepte plusieurs noms de bibliothèques séparés par des espaces. Exemple :</p>
<div class="highlight-html+django notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">load</span> <span class="nv">humanize</span> <span class="nv">i18n</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>Consultez <a class="reference internal" href="../../howto/custom-template-tags.html"><span class="doc">Création de balises et filtres de gabarit personnalisés</span></a> pour obtenir des informations sur l’écriture de vos propres bibliothèques de gabarits.</p>
<section id="s-custom-libraries-and-template-inheritance">
<span id="custom-libraries-and-template-inheritance"></span><h3>Bibliothèques personnalisées et héritage de gabarits<a class="headerlink" href="#custom-libraries-and-template-inheritance" title="Lien vers cette rubrique">¶</a></h3>
<p>Lorsque vous chargez une bibliothèque de balises ou de filtres, ces balises/filtres ne sont disponibles que pour le gabarit concerné, et pas pour les gabarits parents ou enfants dans la chaîne d’héritage des gabarits.</p>
<p>Par exemple, si un gabarit <code class="docutils literal notranslate"><span class="pre">foo.html</span></code> contient <code class="docutils literal notranslate"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">humanize</span> <span class="pre">%}</span></code>, un gabarit enfant (c’est-à-dire un gabarit contenant <code class="docutils literal notranslate"><span class="pre">{%</span> <span class="pre">extends</span> <span class="pre">&quot;foo.html&quot;</span> <span class="pre">%}</span></code>)  n’aura <em>pas</em> accès aux balises et filtres de gabarit de <code class="docutils literal notranslate"><span class="pre">humanize</span></code>. Le gabarit enfant est responsable de charger lui-même <code class="docutils literal notranslate"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">humanize</span> <span class="pre">%}</span></code>.</p>
<p>C’est un comportement volontaire pour une meilleure maintenance et propreté du code.</p>
<div class="admonition seealso">
<p class="admonition-title">Voir aussi</p>
<dl class="simple">
<dt><a class="reference internal" href="index.html"><span class="doc">La référence des gabarits</span></a></dt><dd><p>Documente les balises et filtres intégrés, l’utilisation d’un langage de gabarit alternatif, et d’autres choses encore.</p>
</dd>
</dl>
</div>
</section>
</section>
</section>


          </div>
        </div>
      </div>
      
        
          <div class="yui-b" id="sidebar">
            
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper">
  <div>
    <h3><a href="../../contents.html">Table des matières</a></h3>
    <ul>
<li><a class="reference internal" href="#">Le langage de gabarit de Django</a><ul>
<li><a class="reference internal" href="#templates">Gabarits</a></li>
<li><a class="reference internal" href="#variables">Variables</a></li>
<li><a class="reference internal" href="#filters">Filtres</a></li>
<li><a class="reference internal" href="#tags">Balises</a></li>
<li><a class="reference internal" href="#comments">Commentaires</a></li>
<li><a class="reference internal" href="#template-inheritance">Héritage de gabarits</a></li>
<li><a class="reference internal" href="#template-partials">Template partials</a><ul>
<li><a class="reference internal" href="#basic-syntax">Basic syntax</a></li>
<li><a class="reference internal" href="#fragment-reuse">Fragment reuse</a></li>
<li><a class="reference internal" href="#inline-partials">Inline partials</a></li>
<li><a class="reference internal" href="#accessing-partials-directly">Accessing partials directly</a></li>
<li><a class="reference internal" href="#context-handling">Context handling</a></li>
</ul>
</li>
<li><a class="reference internal" href="#automatic-html-escaping">Échappement HTML automatique</a><ul>
<li><a class="reference internal" href="#how-to-turn-it-off">Comment désactiver l’échappement automatique</a><ul>
<li><a class="reference internal" href="#for-individual-variables">Pour des variables individuelles</a></li>
<li><a class="reference internal" href="#for-template-blocks">Pour des blocs de gabarits</a></li>
</ul>
</li>
<li><a class="reference internal" href="#notes">Notes</a></li>
<li><a class="reference internal" href="#string-literals-and-automatic-escaping">Texte littéral et échappement automatique</a></li>
</ul>
</li>
<li><a class="reference internal" href="#accessing-method-calls">Accès aux appels de méthodes</a></li>
<li><a class="reference internal" href="#custom-tag-and-filter-libraries">Bibliothèques de balises et filtres personnalisés</a><ul>
<li><a class="reference internal" href="#custom-libraries-and-template-inheritance">Bibliothèques personnalisées et héritage de gabarits</a></li>
</ul>
</li>
</ul>
</li>
</ul>

  </div>
  <div>
    <h4>Sujet précédent</h4>
    <p class="topless"><a href="index.html"
                          title="Chapitre précédent">Gabarits</a></p>
  </div>
  <div>
    <h4>Sujet suivant</h4>
    <p class="topless"><a href="builtins.html"
                          title="Chapitre suivant">Balises et filtres de gabarit intégrés</a></p>
  </div>
  <div role="note" aria-label="source link">
    <h3>Cette page</h3>
    <ul class="this-page-menu">
      <li><a href="../../_sources/ref/templates/language.txt"
            rel="nofollow">Montrer le code source</a></li>
    </ul>
   </div>
<search id="searchbox" style="display: none" role="search">
  <h3 id="searchlabel">Recherche rapide</h3>
    <div class="searchformwrapper">
    <form class="search" action="../../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>
    </div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
        </div>
      </div>
              <h3>Last update:</h3>
              <p class="topless">août 05, 2026</p>
          </div>
        
      
    </div>

    <div id="ft">
      <div class="nav">
    &laquo; <a href="index.html" title="Gabarits">previous</a>
     |
    <a href="../index.html" title="Référence de l’API" accesskey="U">up</a>
   |
    <a href="builtins.html" title="Balises et filtres de gabarit intégrés">next</a> &raquo;</div>
    </div>
  </div>

      <div class="clearer"></div>
    </div>
  </body>
</html>