Repository with sources and generator of https://larlet.fr/david/ https://larlet.fr/david/

title: Le langage de template Django : Pour les auteurs de templates slug: le-langage-de-template-django-pour-les-auteurs-de-templates date: 2006-08-15 18:46:48 type: post vignette: images/logos/django.png contextual_title1: Comparaison de TurboGears et Django, deux frameworks web Python contextual_url1: 20060715-comparaison-de-turbogears-et-django-deux-frameworks-web-python contextual_title2: Rédaction de votre première appli Django, partie 4 : Conception d'un formulaire et vues génériques contextual_url2: 20060617-redaction-de-votre-premiere-appli-django-partie-4-conception-d-un-formulaire-et-vues-generiques contextual_title3: Rédaction de votre première appli Django, partie 3 : Création des vues de l'interface publique contextual_url3: 20060617-redaction-de-votre-premiere-appli-django-partie-3-creation-des-vues-de-l-interface-publique

Le langage de template Django a été conçu dans l'idée d'être un bon compromis entre puissance et facilité. Il est facilement accessible aux personnes ayant l'habitude de travailler avec du HTML. Si vous avez déjà utilisé un autre langage de template, comme Smarty ou CheetahTemplate, vous n'aurez aucune difficulté à adopter les templates Django.

Templates

Un template est un simple fichier texte. Il peut générer n'importe quel type de fichier texte (HTML, XML, CSV, etc).

Un template contient des variables qui seront remplacées par leurs valeurs lors de son évaluation et des tags qui controlent la logique du template.

Ci-dessous un template minimal qui illustre les bases. Chaque élément sera expliqué plus tard dans ce document.:

{% extends "base_generic.html" %}

{% block title %}{{ section.title }}{% endblock %}

{% block content %}

<h1>{{ section.title }}</h1>

{% for story in story_list %}
<h2>
  <a href="{{ story.get_absolute_url }}">
    {{ story.headline|upper }}
  </a>
</h2>

<p>{{ story.tease|truncatewords:"100" }}</p>
{% endfor %}
{% endblock %}

Philosophie

Pourquoi utiliser un template au format texte et non au format XML (comme celui du TAL Zope) ? Nous voulions que le langage de template puisse être utilisé pour plus que des templates XML/HTML. À World Online, nous l'utilisons pour les mails, la JavaScript et le CSV. Vous pouvez utiliser le langage de template pour tout format basé sur du texte.

Oh, encore un truc : Rendre du XML éditable par les humains est sadique !

Variables

Les variables ressemblent à {{ variable }}. Lorsque le moteur de template rencontre une variable, il évalue cette variable et la remplace par son résultat.

Utilisez un point (.) pour accéder aux attributs d’une variable.

En coulisses

Techniquement, lorsque le système de template rencontre un point, il effectue les recherches suivantes, dans cet ordre :

Dictionaire

Attribut

Appel de méthode

Index de liste

Dans le précédent exemple, {{ section.title }} sera remplacé par l'attribut title de l'objet section.

Si vous utilisez une variable qui n'existe pas, le système de template va insérer la valeur contenue dans le paramètre TEMPLATE_STRING_IF_INVALID qui correspond par défaut à '' (chaîne vide).

Lisez Utiliser les références incluses, ci-dessous, pour vous aider à connaître les variables disponibles pour un template donné.

Filtres

Vous pouvez modifier des variables lors de l'affichage en utilisant des filtres.

Les filtres ressemblent à {{ name|lower }}. Ceci affiche la valeur de la variable {{ name }} après avoir été filtrée par le filtre lower, qui convertit un texte en minuscule. Utilisez un pipe (|) pour appliquer un filtre.

Les filtres peuvent « s'enchaîner ». La sortie d'un filtre est l'entrée du suivant. {{ text|escape|linebreaks }} est souvent utilisé pour échapper le contenu d'un texte et convertir ensuite les sauts de lignes en tags <p>.

Certains filtres possèdent des arguments. Un argument de filtre ressemble à : {{ bio|truncatewords:"30" }}. Cela va afficher les 30 premiers mots de la variable bio. Les arguments de filtres sont toujours entre double quotes.

La Référence des filtres inclus ci-dessous décrit l'ensemble des ces filtres.

Héritage des templates

La plus intéressante -- mais aussi la plus complexe -- partie du moteur de template de Django est l'héritage. L'héritage des templates vous permet de construire un template « squelette » de base contenant tous les éléments usuels de votre site et définissant des blocs que les templates enfants pourront écraser et/ou compléter.

Il est plus simple, pour comprendre l'héritage des templates, de commencer par un exemple:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <link rel="stylesheet" href="style.css" />

    <title>{% block title %}Mon super site{% endblock %}</title>
</head>

<body>
    <div id="sidebar">
        {% block sidebar %}
        <ul>

            <li><a href="/">Accueil</a></li>
            <li><a href="/blog/">Blog</a></li>
        </ul>

        {% endblock %}
    </div>

    <div id="content">
        {% block content %}{% endblock %}
    </div>
</body>

Ce template, que nous appelerons base.html, définit un simple squelette HTML que vous pouvez utiliser pour une page à deux colonnes. C'est le boulot des templates « enfants » de compléter les blocs vides avec du contenu.

Dans cet exemple, le tag {% block %} définit trois blocs que les templates enfants peuvent compléter. Tout ce que les tags block font c'est d'indiquer au moteur de template qu'un template enfant peut écraser ces parties du template.

Un template enfant pourrait ressembler à ça:

{% extends "base.html" %}

{% block title %}Mon super blog{% endblock %}

{% block content %}
{% for entry in blog_entries %}
    <h2>{{ entry.title }}</h2>

    <p>{{ entry.body }}</p>
{% endfor %}
{% endblock %}

Le tag {% extends %} est la clé ici. Il indique au moteur de template que ce template « étend » un autre template. Lorsque le système de template évalue ce template, il commence par localiser le parent -- dans notre cas, « base.html ».

À ce moment, le moteur de template va tenir compte des trois tags {% block %} dans base.html et remplacer ces blocs avec le contenu du template enfant. En fonction de la valeur de blog_entries, la sortie devrait être proche de:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <link rel="stylesheet" href="style.css" />

    <title>Mon super blog</title>
</head>

<body>
    <div id="sidebar">
        <ul>

            <li><a href="/">Accueil</a></li>
            <li><a href="/blog/">Blog</a></li>
        </ul>

    </div>

    <div id="content">
        <h2>Billet un</h2>
        <p>C'est mon premier billet.</p>

        <h2>Billet deux</h2>
        <p>C'est mon second billet.</p>
    </div>
</body>

Notez que tant que le template enfant ne redéfinit pas le bloc sidebar, la valeur du template parent est utilisée à la place. Le contenu au sein d'un tag {% block %} dans un template parent est toujours utilisé en dernier lieu.

Vous pouvez utiliser autant de niveaux d'héritage que désiré. L'une des manières habituelle d'utiliser l'héritage est l'approche à trois niveaux suivante :

Créez un template base.html qui définit l'apparence globale de votre site.

Créez un template base_NOMDESECTION.html pour chaque section de votre site. Par exemple, base_news.html, base_sports.html. Ces templates étendent tous base.html et incluent le style/design spécifique à la section.

Créez un template individuel pour chaque type de page, comme les articles de nouveautés ou les billets d'un blog. Ces templates étendent le template de la section appropriée.

Cette approche maximise la réutilisation du code et rend facile l'ajout de blocs partagés entre plusieurs parties du site comme la navigation.

Voici quelques astuces pour utiliser l'héritage :

Si vous utilisez {% extends %} dans un template, ça doit être le premier tag du template. Dans le cas contraire l'héritage ne fonctionnera pas.

Il vaut mieux avoir de nombreux tags {% block %} dans vos templates de base. Rappelez-vous, les templates enfants n'ont pas à redéfinir la totalité des blocs, vous pouvez donc remplir les blocs avec un contenu intéressant par défaut. Ne redéfinissez ensuite que ceux dont vous avez besoin. Il vaut mieux en avoir plus que pas assez.

Si vous vous apercevez d'une duplication du contenu dans de nombreux templates, cela signifie probablement que vous devriez déplacer ce contenu dans un {% block %} au sein d'un template parent.

Si vous avez besoin du contenu issu du template parent, la variable {{ block.super }} est là pour ça. C'est intéressant si vous souhaitez ajouter quelquechose au contenu parent existant au lieu de l'écraser.

Pour finir, notez l'impossibilité de définir plusieurs tags {% block %} ayant le même nom dans le même template. Cette limitation existe car un tag block fonctionne dans les deux directions. Cela signifie qu'un tag block ne procure pas seulement un espace à compléter -- il définit aussi au niveau enfant le contenu parent accessible dans cet espace (par block.super).

Utiliser les références incluses

L'interface d'administration de Django inclue une référence complète à l'ensemble des tags et filtres de template disponibles pour un site donné. Pour y accéder, rendez vous dans votre interface d'administration et cliquez sur le lien « Documentation » en haut à droite de la page.

La référence est divisée en 4 sections : tags, filtres, modèles et vues.

Les sections tags et filtres décrivent tous les tags de base (en fait, les références de tag et de filtre qui suivent proviennent directement de ces pages) ainsi que vos propres bibliothèques de tags et de filtres disponibles.

La page des vues est la plus intéressante. Chaque URL de votre site a une entrée distincte ici, et cliquer sur cette URL vous donnera accès :

Au nom de la fonction qui génère cette vue.

À une description succinte de ce que fait la vue.

Au contexte, ou une liste de variables accessibles dans le template de la vue.

Au nom du ou des template(s) qui est(sont) utilisé(s) pour cette vue.

Chaque page de documentation d’une vue dispose aussi d’un bookmarklet que vous pouvez utiliser pour aller directement de n’importe quelle page à la page de documentation de cette vue.

Les sites propulsés par Django utilisant généralement des objets de base de données, la section modèles de la page de documentation décrit chaque type d’objet dans le système courant avec l’ensemble des champs disponibles dans cet objet.

L'ensemble des pages de documentation vous renseigne sur chaque tag, filtre, variable et objet disponible pour un template donné.

Tags personnalisés et bilbiothèques de filtres

Certaines applications procurent des tags personnalisés et des bilbiothèques de filtres. Pour y accéder dans un template, utilisez le tag {% load %}:

{% load comments %}

{% comment_form for blogs.entries entry.id with is_public yes %}

Ci-dessus, le tag load charge la bibliothèque de tags comments, ce qui rend ensuite le tag comment_form utilisable. Consultez la rubrique documentation de votre interface d'administration pour trouver la liste des bibliothèques personnalisées de votre installation.

Le tag {% load %} peut prendre plusieurs noms de bibliothèques à la fois, séparés par des espaces. Exemple:

{% load comments i18n %}

Bibliothèques personnalisées et héritage des templates

Lorsque vous chargez un tag personnalisé ou une bibliothèque de filtres, les tags/filtres ne sont accessibles qu’au sein du template courant -- et aucun des templates parents ou enfants issus de l’héritage des templates n’y a accès.

Par exemple, si un template foo.html a {% load comments %}, un template enfant (par exemple, un qui a {% extends "foo.html" %}) n’aura pas accès aux filtres et tags du template comments. Le template enfant doit avoir son propre {% load comments %}.

C'est une fonctionnalité pour la maintenabilité et l'intégrité des templates.

Référence des tags et filtres inclus

Pour ceux ne disposant pas d'une interface d'administration, la référence des tags et filtres suit. En raison de la personnalisation possible de Django, la référence dans votre administration prévaut sur celle-ci concernant l'accessibilité et la fonction des tags et filtres.

Référence des tags inclus

Référence des filtres inclus

La suite de la traduction est en cours, j'ai jugé qu'il était plus important de publier cette première partie qui pose les bases en attendant. Il faut avouer que la suite (en) est moins passionnante...

Vous pouvez maintenant retourner à la page d’accueil des traductions de la documentation de Django.

Cette traduction correspond à la révision 3589 (post 0.95).

article.md 21KB Директен файл Blame История

article.md 21KB

Директен файл Blame История