Le livre de

block

Définit un bloc qui peut être surpassé par des gabarits enfant. Consultez la partie sur l’héritage de gabarit au chapitre 4 pour plus d’information.

comment

Ignore tout ce qui se trouve entre {% comment %} et {% endcomment %}.

cycle

Parcourt les chaînes indiquées chaque fois que la balise est rencontrée.

À l’intérieur d’une boucle, elle parcourt les chaînes présentées à chaque tour de boucle:

{% for o in some_list %}
    <tr class="{% cycle row1,row2 %}">
        ...
    </tr>
{% endfor %}

À l’extérieur d’une boucle, donne aux valeurs un nom unique lors du premier appel, puis utilise ce nom à chaque parcour successif:

<tr class="{% cycle row1,row2,row3 as rowcolors %}">...</tr>
<tr class="{% cycle rowcolors %}">...</tr>
<tr class="{% cycle rowcolors %}">...</tr>

Vous pouvez utiliser autant de valeurs que vous le souhaitez, séparées par des virgules. Assurez-vous de ne pas placer d’espaces entre les valeurs - des virgules uniquement.

debug

Retourne un lot d’information de débuggage, comprenant le contexte courant et les modules importés.

extends

Signale que ce gabarit étend un gabarit parent.

Cette balise peut s’utiliser de deux façons:

• {% extends "base.html" %} (avec des parenthèses) utilise la valeur littérale "base.html" comme nom du gabarit parent à étendre.
• {% extends variable %} utilise la valeur de variable. Si la variable correspond à une chaîne, Django l’utilisera comme nom de gabarit parent. Si la variable correspond à un objet gabarit Template, Django utilisera cet objet comme gabarit parent.

Consultez le chapitre 4 pour des exemples d’utilisation.

filtre

Filtre le contenu de la variable au travers des filtres de variable.

Les filtres peuvent aussi être raccordés entre eux, et peuvent avoir des arguments - tout comme dans la syntaxe de variable.

Voici un exemple d’utilisation:

{% filter escape|lower %}
    This text will be HTML-escaped, and will appear in all
    lowercase.
{% endfilter %}

firstof

Retourne la première variable transmise qui ne soit pas False. Ne retourne rien si toutes les variables transmises sont False.

Voici un exemple d’utilisation:

{% firstof var1 var2 var3 %}

est équivalant à ce qui suit:

{% if var1 %}
    {{ var1 }}
{% else %}{% if var2 %}
    {{ var2 }}
{% else %}{% if var3 %}
    {{ var3 }}
{% endif %}{% endif %}{% endif %}

for

Boucle sur chaque élément d’un tableau. Par exemple, pour afficher une liste d’athlètes d’après athlete_list:

<ul>
{% for athlete in athlete_list %}
    <li>{{ athlete.name }}</li>
{% endfor %}
</ul>

Vous pouvez aussi boucler sur une liste dans le sens inverse en utilisant {% for obj in list reversed %}.

La boucle for fixe un nombre de variables disponibles à l’intérieur de la boucle (consultez la figure F-1.)

if

La balise {% if %} évalue une variable, et si cette variable est ?true? (c’est à dire qu’elle existe, qu’elle n’est pas vide, et qu’il ne s’agit pas d’une valeur Booleénne fausse), le contenu du bloc est rendu:

{% if athlete_list %}
    Number of athletes: {{ athlete_list|length }}
{% else %}
    No athletes.
{% endif %}

Si athlete_list n’est pas vide, le nombre d’athlètes sera affiché par la variable {{ athlete_list|length }}.

Comme vous pouvez le voir, la balise if peut prendre une clause optionnelle {% else %} qui sera afficher si le test échoue.

Les balises if peuvent utiliser and, or, ou not pour tester un nombre de variables ou pour nier une variable donnée:

{% if athlete_list and coach_list %}
    Both athletes and coaches are available.
{% endif %}

{% if not athlete_list %}
    There are no athletes.
{% endif %}

{% if athlete_list or coach_list %}
    There are some athletes or some coaches.
{% endif %}

{% if not athlete_list or coach_list %}
    There are no athletes or there are some coaches (OK, so
    writing English translations of Boolean logic sounds
    stupid; it's not our fault).
{% endif %}

{% if athlete_list and not coach_list %}
    There are some athletes and absolutely no coaches.
{% endif %}

les balises if ne permettent pas les clauses and et or à l’intérieur de la même balise, parceque l’ordre logique pourrait être ambigue. Par exemple, ceci n’est pas valide:

{% if athlete_list and coach_list or cheerleader_list %}

Si vous devez combiner and et or pour une logique avancée, utilisez simplement les balises if imbriquées, par exemple:

{% if athlete_list %}
    {% if coach_list or cheerleader_list %}
        We have athletes, and either coaches or cheerleaders!
    {% endif %}
{% endif %}

L’usage multiple d’un même opérateur logique ne pose pas de problème, dès lors que vous utilisiez ce même opérateur. Par exemple, ceci est valide:

{% if athlete_list or coach_list or parent_list or teacher_list %}

ifchanged

Vérifie si une valeur à changé depuis la dernière itération d’une boucle. La balise de bloc ifchanged est utilisée à l’intérieur d’une boucle. Elle a deux usages possibles:

1. Elle compare sont propre contenu généré avec sont état précédent et affiche uniquement le contenu s’il a changé. Par exemple, ceci affiche une liste de jours, affichant le mois seulement si celui-ci change:

   <h1>Archive for {{ year }}</h1>
   
   {% for date in days %}
       {% ifchanged %}<h3>{{ date|date:"F" }}</h3>{%
       endifchanged %}
       <a href="{{ date|date:"M/d"|lower }}/">{{
       date|date:"j" }}</a>
   {% endfor %}
   

2. Si une variable est précisée, elle vérifie si cette variable a changé:

   {% for date in days %}
       {% ifchanged date.date %} {{ date.date }} {%
       endifchanged %}
       {% ifchanged date.hour date.date %}
           {{ date.hour }}
       {% endifchanged %}
   {% endfor %}
   

   Ce code présente la date à chaque fois qu’elle change, mais n’affiche l’heure que si à la fois l’heure et la date ont changé.

ifequal

Retourne le contenu du bloc si les deux arguments sont égaux entre eux.

Voici un exemple:

{% ifequal user.id comment.user_id %}
    ...
{% endifequal %}

Tout comme dans la balise {% if %}, une clause {% else %} est optionelle. Les arguments pouvant être des chaînes «codées en dur», ce qui suit est donc valide:

{% ifequal user.username "adrian" %}
    ...
{% endifequal %}

Il est seulement possible de comparer un argument à des variables de gabarit ou à des chaînes. Vous ne pouvez pas contrôler l’égalité avec les objets Python tel que True ou False. Si vous devez tester si quelque chose est vrai ou faux, utilisez la balise if à la place.

ifnotequal

Semblable à ifequal, excepté qu’elle test que les deux arguments ne sont pas égaux.

include

Charge un gabarit et le retourne avec le contexte courant. C’est une manière d’«inclure» d’autre gabarit au sein d’un gabarit.

Le nom du gabarit peut être une variable ou une chaîne (entre guillemets) codée en dur, entre guillemets simples ou doubles.

Cet exemple inclu le contenu du gabarit "foo/bar.html":

{% include "foo/bar.html" %}

Cet exemple inclu le contenu du gabarit dont le nom est contenu dans la variable template_name:

{% include template_name %}

load

Charge une bibliothèque de gabarits personnalisés. Consulter le chapitre 10 pour plus d’informations au sujet des bibliothèques de gabarits personnalisés.

now

Affiche la date, formattée selon la chaîne précisée.

Cette balise s’inspire et utilise le même format qu’une fonction date() en PHP `` (http://php.net/date). La version de Django, cependant, à quelques extensions personnalisées.

Le tableau F-2 montre les chaînes de formattage disponibles.

Voici un exemple:

It is {% now "jS F Y H:i" %}

Notez que vous pouvez échapper par un anti-slash une chaîne de format si vous voulez utiliser la valeur «brute». Dans cet exemple, «f» est échappé grâce à l’anti-slash, car sinon «f» est une chaîne de formattage qui affiche l’heure. Le «o» n’a pas besoin d’échappement, puisqu’il n’est pas un caractère de formattage:

It is the {% now "jS o\f F" %}

Ceci pourrait afficher «it is the 4th of September».

regroup

Regroupe une liste d’objets semblables par un attribut commun.

Cette balise complexe est mieux illustrée par l’utilisation d’un exemple. Admettons que people soit une liste d’objets Person qui ont des attributs first_name, last_name, et gender, et que vous vouliez afficher une liste qui ressemble à ceci:

* Male:
    * George Bush
    * Bill Clinton
* Female:
    * Margaret Thatcher
    * Condoleezza Rice
* Unknown:
    * Pat Smith

L’extrait suivant de code d’un gabarit pourrait accomplir cette tâche douteuse:

{% regroup people by gender as grouped %}
<ul>
{% for group in grouped %}
    <li>{{ group.grouper }}
    <ul>
        {% for item in group.list %}
        <li>{{ item }}</li>
        {% endfor %}
    </ul>
    </li>
{% endfor %}
</ul>

Comme vous pouvez le voir, {% regroup %} affecte à une variable la liste des objets ayant les attributs grouper et list. grouper contient l’élément qui a été regroupé; list contient la liste des objets qui partagent ce grouper. Dans le cas présent, grouper sera Male, Female, et Unknown, et list la liste des gens avec ces genres.

Notez que {% regroup %} ne fonctionne pas lorsque la liste qui doit être groupée n’est pas classée par la clef sur laquelle vous effectuez le regroupement ! Cela signifie que si votre liste de gens n’a pas été triée par genre, vous devrez vous assurer qu’elle soit triée avant de l’utiliser, autrement dit:

{% regroup people|dictsort:"gender" by gender as grouped %}

spaceless

Retire les espaces entre les balises HTML. Ceci inclut les caractères tabulation et nouvelle ligne.

Voici un exemple:

{% spaceless %}
    <p>
        <a href="foo/">Foo</a>
    </p>
{% endspaceless %}

Cet exemple retournera cet HTML:

<p><a href="foo/">Foo</a></p>

Seul l’espace entre les balises est retiré - pas l’espace entre les balises et le texte. Dans cet exemple, l’espace autour de Hello en sera pas supprimé:

{% spaceless %}
    <strong>
        Hello
    </strong>
{% endspaceless %}

ssi

Affiche dans la page le contenu d’un fichier donné.

Comme une simple balise «include», {% ssi %} inclu le contenu d’un autre fichier - qui doit être spécifié en utilisant un chemin absolut - dans le fichier courant:

{% ssi /home/html/ljworld.com/includes/right_generic.html %}

Si le paramètre optionel «parsé» est précisé, le contenu du fichier inclu est considéré comme du code de gabarit, au sein du contexte courant:

{% ssi /home/html/ljworld.com/includes/right_generic.html parsed %}

Notez que si vous utilisez {% ssi %}, vous aurez besoin de définir ALLOWED_INCLUDE_ROOTS dans vos paramètres Django, par mesure de sécurité.

La plupart du temps {% include %} fonctionne mieux que {% ssi %}; {% ssi %} existe principalement pour des raisons de rétro-compatibilité.

templatetag

Retourne l’un des charactères de syntaxe utilsé dans la composition des balises de gabarit.

Puisque le système de gabarit n’a pas de concept d’«échappement», vous devez utiliser la balise {% templatetag %} pour afficher l’une des parties utilisée dans les balises de gabarit.

L’argument indique quelle partie de gabarit retourner. (consultez le tableau F-3)

Table F-3. Valid Arguments to templatetag =================== ===================== Argument Output ––––––- –––––––

openblock {% closeblock %} openvariable {{ closevariable }} openbrace { closebrace } opencomment {# closecomment #} =================== =====================

url

Retourne un URL absolu (c’est à dire un URL sans le nom de domaine) correspondant à une fonction Vue et à des paramètres optionnels donnés. C’est une façon de retourner les liens sans violer le principe DRY en ayant à coder en dur les URLs dans vos gabarits:

{% url path.to.some_view arg1,arg2,name1=value1 %}

Le premier argument est un chemin vers une fonction Vue selon le format package.package.module.fonction. Les arguments additionnels sont optionnels et doivent être des valeurs séparées par des virgules et seront utilisées comme des arguments mot-clefs et positionnels dans l’URL. Tous les arguments requis par l’URLconf doivent être présent.

Par exemple, supposez que vous ayez une vue, app_name.client, dont l’URLconf prends un ID client. La ligne URLconf devrait ressembler à ceci:

('^client/(\d+)/$', 'app_name.client')

Si cet URLconf de l’application est inclu dans l’URLconf du projet sous un chemin tel que celui-ci:

('^clients/', include('project_name.app_name.urls'))

alors, dans un gabarit, vous pouvez créer un lien vers cette vue comme ceci:

{% url app_name.client client.id %}

La balise de gabarit retournera la chaîne /clients/client/123/.

widthratio

Pour créer des graphiques à barres, cette balise calcule le ratio d’une valeur donnée par rapport à une valeur maximale, puis applique ce ratio à une constante.

Voici un exemple:

<img src="bar.gif" height="10" width="{% widthratio this_value max_value
100 %}" />

Si this_value vaut 175 et max_value vaut 200, l’image de l’exemple précédent fera 88 pixels de large (puisque 175/200 = .875; .875 * 100 = 87.5, ce qui est arrondi à 88).

add

Exemple:

{{ value|add:"5" }}

Ajoute l’argument à la valeur.

addslashes

Exemple:

{{ string|addslashes }}

Ajoute un anti-slash avant les guillemets simples ou doubles. Ceci est utile pour transmettre des chaînes au Javascript, par exemple.

capfirst

Exemple:

{{ string|capfirst }}

Remplace le premier caractère de la chaîne par une capitale.

center

Exemple:

{{ string|center:"50" }}

Centre la chaîne dans un champ de largeur donnée.

cut

Exemple:

{{ string|cut:"spam" }}

Supprime toutes les valeurs de l’argument dans la chaîne donnée.

date

Exemple:

{{ value|date:"F j, Y" }}

Formate une date selon le format précisé (identique à la balise now.)

default

Exemple:

{{ value|default:"(N/A)" }}

Si la valeur par défaut n’est pas disponible, utilise la valeur donnée.

default_if_none

Exemple:

{{ value|default_if_none:"(N/A)" }}

Si la valeur par défaut est None, utilise la valeur donnée.

dictsort

Exemple:

{{ list|dictsort:"foo" }}

Prends une liste de dictionnaires et retourne cette liste triée selon la propriété donnéee en argument.

dictsortreversed

Exemple:

{{ list|dictsortreversed:"foo" }}

Prends une liste de dictionnaires et retourne cette liste triée en ordre inverse selon la propriété donnée en argument.

divisibleby

Exemple:

{% if value|divisibleby:"2" %}
    Even!
{% else %}
    Odd!
{% else %}

Retourne True si la valeur est divisible par l’argument.

escape

Exemple:

{{ string|escape }}

Èchappe une chaîne HTML. Spécifiquement, elle fait les remplacements suivants:

• "&" par "&"
• < par "&lt;"
• > par "&gt;"
• '"' (guillemets doubles) par '&quot;'
• "'" (guillemets simples) par '&#39;'

filesizeformat

Exemple:

{{ value|filesizeformat }}

Formate la valeur comme une taille de fichier «humainement lisible» (c’est à dire '13 KB', '4.1 MB', '102 bytes', etc..)

first

Exemple:

{{ list|first }}

Retourne le premier élément d’une liste.

fix_ampersands

Exemple:

{{ string|fix_ampersands }}

Remplace l’esperluette par l’entité &amp;.

floatformat

Exemples:

{{ value|floatformat }}
{{ value|floatformat:"2" }}

Lorsqu’elle est utilisée sans argument, arrondi un nombre flottant à une décimale - mais uniquement s’il y a une partie décimale à afficher, par exemple:

• 36.123 est converti en 36.1.
• 36.15 est converti en 36.2.
• 36 est converti en 36.

Lorsqu’elle est utilisée avec un argument numérique entier, floatformat arrondi un nombre aux décimales indiquées:

• 36.1234 avec floatformat:3 est converti en 36.123.
• 36 avec floatformat:4 gets est converti en 36.0000.

Si l’argument transmis à floatformat est négatif, il sera arrondi aux décimales indiquées - mais uniquement s’il y a une partie décimale à afficher:

• 36.1234 avec floatformat:-3 est converti en 36.123.
• 36 avec floatformat:-4 est converti en 36.

Utiliser floatformat sans arguments revient à utiliser floatformat avec un argument équivalant à -1.

get_digit

Exemple:

{{ value|get_digit:"1" }}

Pour un nombre complet FIXME FUZZY (given a whole number) donné, retourne le chiffre demandé, où 1 est le chiffre le plus à droite, 2 est le second le plus à droite, et ainsi de suite. Elle retourne la valeur originale en cas d’entrée invalide (si l’entrée ou l’argument n’est pas un entier, ou si l’argument est inférieur à 1). Autrement, la sortie est toujours un entier.

Given a whole number, returns the requested digit of it, where 1 is the rightmost digit, 2 is the second-to-rightmost digit, and so forth. It returns the original value for invalid input (if the input or argument is not an integer, or if the argument is less than 1). Otherwise, output is always an integer.

join

Exemple:

{{ list|join:", " }}

Concatène une liste avec une chaîne, pareillement à str.join(list) en Python.

length

Exemple:

{{ list|length }}

Retourne la longueur de la valeur.

length_is

Exemple:

{% if list|length_is:"3" %}
    ...
{% endif %}

Retourne un Booléen selon la longueur de la valeur passée en argument.

linebreaks

Exemple:

{{ string|linebreaks }}

Converti le retour chariot en balises <p> et <br />.

linebreaksbr

Exemple:

{{ string|linebreaksbr }}

Converti un retour chariot en balise <br />.

linenumbers

Exemple:

{{ string|linenumbers }}

Affiche le texte avec les numéro de ligne.

ljust

Exemple:

{{ string|ljust:"50" }}

Aligne à gauche la valeur dans un champ de largeur donnée.

lower

Exemple:

{{ string|lower }}

Converti l’intégralité d’une chaîne en bas de casse.

make_list

Exemple:

{% for i in number|make_list %}
    ...
{% endfor %}

Retourne la valeur sous forme de liste. Pour un entier, c’est une liste de chiffres. Pour une chaîne, c’est une liste de caractères.

phone2numeric

Exemple:

{{ string|phone2numeric }}

Converti un numéro de téléphone (potentiellement avec des lettres) en sa valeur numérique équivalente. Par exemple, '800-COLLECT' sera converti en '800-2655328'.

L’entré n’est pas nécessairement un numéro de téléphone valide. Ceci convertira joyeusement toute chaîne.

pluralize

Exemple:

La liste contient {{ list|length }} élément{{ list|pluralize }}.

retourne un suffixe pluriel si la valeur n’est pas 1. Par défaut, ce suffix est 's'.

Exemple:

Vous avez {{ num_messages }} message{{ num_messages|pluralize }}.

Pour les mots qui nécessitent un suffixe différent de 's', vous pouvez fournir un suffixe alternatif en paramètre du filtre.

Exemple:

Vous avez {{ nbr_tableau }} tableau{{ nbr_tableau|pluralize:"x" }}.

Pour les mots dont le pluriel n’est pas un simple suffixe, vous pouvez spécifier à la fois un suffixe singulier et un suffixe pluriel, séparer par une virgule.

Exemple:

Vous avez {{ nbr_journal }} journ{{ num_journal|pluralize:"al,aux" }}.

pprint

Exemple:

{{ object|pprint }}

Un emballage autour de la primitive Python pprint.pprint - pour débugage, vraiment.

random

Exemple:

{{ list|random }}

Retourne un élément aléatoirement depuis la liste;

removetags

Exemple:

{{ string|removetags:"br p div" }}

Retire de la sortie la liste des balises [X]HTML séparées par des espaces.

rjust

Exemple:

{{ string|rjust:"50" }}

Aligne à droite la valeur dans un champ de largeur donnée.

slice

Exemple:

{{ some_list|slice:":2" }}

Retourne un segment d’une liste.

Utilise la même syntaxe que la segmentation des liste en Python. Consultez http://diveintopython.org/native_data_types/lists.html#odbchelper.list.slice pour une introduction.

slugify

Exemple:

{{ string|slugify }}

Converti en bas de casse, retire les caractères non autorisés (alphanumériques et soulignement), puis converti les espaces en trait d’union. Supprime aussi les espaces au début et à la fin.

stringformat

Exemple:

{{ number|stringformat:"02i" }}

Formate la variable selon l’argument, un spécificateur du formatage de la chaîne. Ce spécificateur utilise la syntaxe Python, à l’exception du «%?» initial qui est homis.

Lisez la documentation Python http://docs.python.org/lib/typesseq-strings.html au sujet du formattage des chaînes.

striptags

Exemple:

{{ string|striptags }}

Découpe toutes les balises [X]HTML.

time

Exemple:

{{ value|time:"P" }}

Formate l’heure selon le format précisé (identique à la balise now).

timesince

Exemples:

{{ datetime|timesince }}
{{ datetime|timesince:"other_datetime" }}

Formate une date sous forme de temps passé depuis cette date (par exmple, «4 days, 6 hours»).

Accepte un argument optionnel qui est une variable contenant la date à utiliser comme point de comparaison (sans l’argument, la point de comparaison est maintenant). Par exemple, si blog_date est une instance de date représentant minuit au premier juin 2006, et que comment_date est une instance de date pour 08:00 le premier juin 2006, alors {{ comment_date|timesince:blog_date }} retournera «8 heures».

timeuntil

Exemples:

{{ datetime|timeuntil }}
{{ datetime|timeuntil:"other_datetime" }}

Similaire à timesince, sauf que la mesure représente le temps à partir de maintenant jusqu’à une date ou une heure donnée. Par exemple, si nous étions aujourd’hui le 29 juin 2006 et que conference_date soit une instance de date équivalente au 29 juin 2006, alors {{ conference_date|timeuntil }} retournera «28 jours».

Un argument optionnel est disponible. Il s’agit d’une variable contenant la date à utiliser comme point de comparaison (à la place de now, maintenant). Si from_date contient le 22 juin 2006, alors {{ conference_date|timeuntil:from_date }} retournera «7 jours».

title

:

Exemple:

{{ string|titlecase }}

Converti une chaîne en titre.

truncatewords

Exemple:

{{ string|truncatewords:"15" }}

Découpe une chaîne après un certain nombre de mots.

truncatewords_html

Exemple:

{{ string|truncatewords_html:"15" }}

Similaire à truncatewords, sauf qu’elle accepte les balises HTML. Toutes les balises qui sont ouvertes dans la chaîne et qui ne sont pas refermées avant la coupure sont refermées immédiatement après la coupure.

Ceci est moin efficace que truncatewords et doit donc être utilisé uniquement lorsqu’il s’agit de fournir du texte HTML.

unordered_list

Exemple:

<ul>
    {{ list|unordered_list }}
</ul>

Prends une liste imbriquée et retourne une liste HTML non ordonnées - sans les balises <ul> d’ouverture et de fermeture.

La liste est supposée être au format correct. Par exemple, si var contient ['States', [['Kansas', [['Lawrence', []], ['Topeka', []]]], ['Illinois', []]]], alors {{ var|unordered_list }} retournera ce qui suit:

<li>States
<ul>
        <li>Kansas
        <ul>
                <li>Lawrence</li>
                <li>Topeka</li>
        </ul>
        </li>
        <li>Illinois</li>
</ul>
</li>

upper

Exemple:

{{ string|upper }}

Converti toute une chaîne en capitale.

urlencode

Exemple:

<a href="{{ link|urlencode }}">linkage</a>

Traite une valeur pour un usage au sein d’un URL.

urlize

Exemple:

{{ string|urlize }}

Converti les URLs textuels en liens cliquables.

urlizetrunc

Exemple:

{{ string|urlizetrunc:"30" }}

Converti les URLs en liens cliquables, coupant ceux-ci au niveau de la limite précisée.

wordcount

Exemple:

{{ string|wordcount }}

Retourne le nombre de mots.

wordwrap

Exemple:

{{ string|wordwrap:"75" }}

Enveloppe les mots selon une longueur de ligne précisée.

yesno

Exemple:

{{ boolean|yesno:"Yes,No,Perhaps" }}

En fonction des valeurs de chaîne correspondants à True, False, et (facultatif) None, retourne l’une de ces chaînes selon la valeur (voir le tableau F-4).

Table F-4. Exemples of the yesno Filter

<< précédent ◊ suivant >>