Templates

Template :

fichier qui contient des variables et des tags, et qui sert à générer le document final.
on peut l'utiliser pour générer du html, du csv ou n'importe quel autre fichier basé sur du texte.
les variables sont évaluées par {{myVar}}.
les tags sont à un format du type {% myTag ... %}.

Variables dans les templates

Variables dans les templates :

les variables doivent avoir des noms alphanumériques.
quand {{myVariable}} est rencontré, il y a substitution par la valeur de la variable.
si la variable n'existe pas, la valeur de TEMPLATE_STRING_IF_INVALID est insérée (par défaut, elle vaut la chaîne vide).
quand {{myVariable.myField}} est rencontré, le point est évalué dans cet ordre jusqu'à trouver quelque chose :
- comme un accès au champ myField d'un dictionnaire.
- sinon, comme attribut ou méthode, et si c'est une méthode, elle est appelée sans argument pour récupérer le retour.
- et sinon, comme index numérique.
- sinon, c'est la valeur de TEMPLATE_STRING_IF_INVALID qui est insérée.

Filtres

Les filtres permettent de modifier le résultat d'une variable. Principes des filtres :

{{myVar|lower}} : applique un filtre à la variable et affiche le résultat (ici, mise en minuscules).
{{myVar|lower|capfirst}} : applique les 2 filtres successivement.
{{myVar|default:'-'}} : filtre avec un argument '-'. Attention : pas d'espace entre le ':' et l'argument !

Liste des filtres :

{{myVar|lower}} : met le résultat en minuscules.
{{myVar|upper}} : met le résultat en majuscules.
{{myVar|capfirst}} : première lettre en majuscules (mais ce qui est en majuscules reste.
{{myVar|safe}} : permet d'éviter la transformation du contenu par un escape HTML (sinon, & est transformé en &).
{{myVar|date:'d/m/Y, H:i:s'}} : donne la date au format 23/05/2015, 10:22:49
{{myVar|date:'D d F Y \a H\hi\ms\s'}} : donne la date au format sam 23 mai 2015 a 10h22m49s
{{myVar|date:'DATETIME_FORMAT'}} : donne la date au format 23 mai 2015 10:22:49
{{myVar|default:'-'}} : si myVar est à False, renvoie '-', sinon renvoie myVar.
{{myVar|default_if_none:'-'}} : si myVar est à None, renvoie '-', sinon renvoie myVar.
{{myVar|dictsort:'myKey'}} : trie la liste de dictionnaire par la clef 'myKey' et renvoie le résultat (idem avec dictsortreversed en sens inverse).
{{myVar|divisibleby:'2'}} : renvoie True si myVar divisible par 2.
{{myVar|escape}} : fait un escape HTML, mais juste à la fin, avant de sortir la valeur, donc comme si c'était le dernier filtre.
{{myVar|first}} : renvoie le premier élément de la liste myVar. Idem avec last.
{{myVar|floatformat:'2'}} : arrondit le nombre à 2 chiffres après la virgule.
{{myVar|join:','}} : comme en python avec join.
{{myVar|length}} : renvoie la longueur de la liste ou de la chaîne.
{{myVar|length_is:'2'}} : retourne True si longueur vaut 2.
{{myVar|slide:'0:2'}} : retourne une slice de la liste ou de la chaîne, comme en python.
{{myVar|time:H:i:s'}} : formatte un temps.
{{myVar|truncatechars:10}} : tronque à 10 caractères si trop grand, en incluant '...' (compris dans les 10 caractères).
{{myVar|truncatewords:10}} : tronque à 10 mots si trop grand, en rajoutant '...' à la fin.
{{myVar|unordered_list}} : génère une liste HTML à partir d'une variable contenant une liste, mais dans les tags <ul> et </ul>. Si la la liste a des sous-listes, les sous-listes HTML seront générées (avec les ul cette fois-ci).
{{myVar|urlencode}} : encode une valeur pour être utilisée dans une url.

Tags

{# my comment #} : commentaire dans un template.

Condition :

{% if myValue %}
...
{% elif %}
...
{% else %}
...
{% endif %}

on peut utiliser les opérateurs booléens and, or, not et ils ont la priorité habituelle, mais attention : on ne peut pas utiliser de parenthèses ! (utiliser des conditions imbriquées).
il y a aussi les opérateurs ==, !=, <, <=, >, >=, in, not in.
on peut utiliser {% if myList.length > 1 %} pour exécuter un bloc si plus d'un élément, mais attention : la plupart des autres filtres renvoient des valeurs alphanumériques sur lesquelles on ne peut pas faire de comparaisons numériques !

{% ifchanged %}{{myVar}}{% endifchanged %} : au sein d'une boucle, n'affiche la variable (ou le contenu) que si celui-ci à changer

Boucle :

{% for myObj in myObjectList %}
...
{% endfor %}

{% for x in myList reversed %} : permet de boucler sur la liste, mais en sens inverse.
{% for x, y in myPoints %} : permet de boucler sur une liste de paires.
{% for key, value in myDict.items %} : permet de boucler sur les valeurs d'un dictionnaire.
variables définies à l'intérieur d'une boucle for :
- forloop.counter : numéro d'itération, origine à 1.
- forloop.counter0 : numéro d'itération, origine à 0.
- forloop.first : True pour la première itération (idem avec forloop.last).

On peut avoir un contenu particulier si la liste est vide :

{% for x in myList %}
...
{% empty %}
contenu si la liste est vide
{% endfor %}

Génération de valeurs cycliques :

cycle pour avoir à chaque itération une des valeurs en cyclant sur celles-ci :
```
{% for x in myList %}
<tr class="{% cycle 'style1' 'style2' %}">...</tr>
{% endfor %}
    
```
renvoie ici style1, style2, style1, style2, ....
les arguments peuvent être des variables, mais on ne peut pas passer directement une liste !
on peut donner un nom à la variable courante pour pouvoir la réutiliser plusieurs fois sans changement : {% cycle 'style1' 'style2' as currentStyle %} et on peut alors utiliser {{currentStyle}}
{% cycle 'style1' 'style2' as currentStyle silent %} : permet de générer une valeur, la mettre dans la variable, mais sans l'insérer à cet endroit (on peut utiliser la variable pour mettre la valeur ailleurs).

Urls (liens) :

{% url 'myUrlName' myObj.id %}: inclus une url du nom donné avec les paramètres indiqués.
myUrlName est ici le nom donné à l'URL quand on l'a définie avec la fonction url : url(r'^(?P<myArg>\d+)$', views.myFunc, name = 'myUrlName')
myObj.id (champ id de myObj) permet alors de remplir le champ.
on peut aussi passer les arguments par nom (mais ne pas mélanger les deux) : {% url 'myUrlName' arg1=v1 arg2=v2 %}
on peut aussi définir une url sans l'afficher tout de suite, mais en lui donnant un nom pour l'afficher plus tard (la variable reste valable dans le {% block %}:
```
{% url 'myUrlName' val as myUrl %} # pas d'affichage ici
...
{{myUrl}} # affichage de l'url ici
    
```

On peut inclure un template dans un autre en faisant : {% include 'menu.html' %} (ici, pour inclure un menu par exemple).

Héritage de templates :

dans le template de base, myBaseTemplate.html, on définit des blocs qui pourront être remplacés :
```
{% block myBlock %}un contenu de base{% endblock %}
    
```
dans le template dérivé, on hérite du template de base et on définit le contenu des différents blocs (qui peut être dynamique bien sûr) :
```
{% extends 'myBaseTemplate.html' %}
{% block myBlock %}{% for x in myList%}...{% endfor %}{% endblock %}
    
```
si le template dérivé ne définit pas l'un des blocs du template de base, c'est le contenu du bloc chez le parent qui est utilisé.
{% extends %} doit être le premier tag.
{{ block.super }} : permet d'avoir le contenu du bloc parent dans un bloc donné (par exemple pour rajouter des choses après).

Serveur side includes :

{% ssi '/myDir/myFile.html' %} : inclut dans le template à cet endroit le fichier dont on donne le path complet.
attention : pour que ça marche, il faut que le fichier à inclure soit dans un sous-répertoire de ceux mentionnés dans la liste de répertoires de ALLOWED_INCLUDE_ROOTS (dans settings.py).
si on veut que le contenu du fichier à inclure soit lui-même évalué : {% ssi '/myDir/myFile.html' parsed %}

Inclusion de dates : si la localisation est en français dans settings.py (LANGUAGE_CODE = 'fr-FR') :

{% now "d/m/Y, H:i:s" %} va donner 23/05/2015, 10:22:49.
{% now "D d F Y \a H\hi\ms\s" %} va donner sam 23 mai 2015 a 10h22m49s (mettre des backslash sur les lettres que l'on veut mettre telles quelles).
{% now "DATETIME_FORMAT" %} va donner 23 mai 2015 10:22:49.

{% with myNewVar=myObj.compute %} : permet d'affecter un résultat calculé à une variable, pour éviter de le calculer plusieurs fois.

Pour éviter les Cross Site Request Forgeries, inclure dans une form : {% csrf_token %}

{% filter lower|capfirst %}...{% endfilter %} : filtre le contenu avec le filtre indiqué.

{% firstof var1 var2 var3 %} : affiche la première variable qui est n'est pas False.

Escape HTML :

on peut éviter l'escape HTML sur une partie du template en faisant :
```
{% autoescape off %}
...
{% endautoescape %}
    
```
on peut utiliser aussi {% autoescape on %} et imbriquer les 2 types.

{% verbatim %}...{% endverbatim %} : tout ce qui est entre les deux n'est pas interprété par le moteur de template.

Si on met {% debug %} dans le template, on a du debug.

Pour utiliser une librairie custom de filtres et de tags :

rajouter l'application dans INSTALLED_APPS.
charger la librairie dans chaque template par {% load myLib %}.
si plusieurs librairies : {% load myLib1 myLib2 %}.
attention : si un template hérite d'un autre qui charge une librairie, il doit aussi la charger !

programmer en python, tutoriel python, graphes en python, Aymeric Duclert