Un gabarit est un fichier texte qui décrit la structure ou la mise en page d'un document (comme une page HTML) et qui utilise des emplacements réservés pour y insérer des informations issues de la base de données.

Le cadriciel Django va rechercher automatiquement ces gabarits dans un répertoire nommé 'templates' dans le dossier de l'application. Si vous reprenez la dernière ligne de la fonction index() dans l'exemple ci-dessus, la fonction render() a besoin du fichier index.html qui devrait être placé dans le dossie /locallibrary/catalog/templates/. Dans le cas contraire, cela génère une erreur car le fichier est considéré comme absent.

Vous pouvez en faire l'expérience dès à présent, après avoir redémarré votre serveur local, en accédant à l'URL 127.0.0.1:8000 de votre navigateur. Une page d'erreur explicite s'affiche en indiquant un message du type : "TemplateDoesNotExist at /catalog/", ainsi que de nombreux détails sur l'enchaînement des fonctions aboutissant à cette erreur.

Note : En fonction du paramétrage de votre projet - le fichier settings.py de votre projet - Django va chercher pour des gabarits dans différents répertoires et dans ceux de votre application par défaut. Si vous souhaitez approfondir ce sujet vous pouvez consulter la documentation Django relative aux gabarits.

Django utilise un langage pour les gabarits qui permet de résoudre certains sujets liés aux pages HTML. En l'occurrence, dans le site web de la bibliothèque nous aurons des bandeaux de navigateur et autres codes d'en-tête à réutiliser. Dans une vision classique, il faudrait récrire dans chaque page le même code pour obtenir le même rendu. Si cela peut se concevoir pour quelques pages, ce procédé devient vite inopérant voire risqué avec un site dynamique complet.

Le langage de gabarit de Django permet de définir un modèle de base puis de l'étendre ensuite. L'extrait de code ci-dessous vient du fichier de gabarit base_generic.html, vous constaterez qu'il s'y mélange du code HTML et des sections nommées contenu dans entre des marqueurs block et endblock qui peut contenir ou non des données.

Note : Les marqueurs de gabarits sont des fonctions que vous pouvez utiliser dans un modèle pour parcourir des listes, effectuer des opérations conditionnelles en fonction de la valeur d'une variable, etc. Outre les balises de modèle, la syntaxe de gabarit vous permet de référencer les variables qui sont transmises au modèle à partir de la vue et d'utiliser des filtres de gabarit pour mettre en forme les variables (par exemple, pour convertir une chaîne en minuscule).

Dans l'extrait ci-dessous vous avec trois sections nommées qui pourront être remplacés par la suite :

Lorsque l'on définit un gabarit pour une vue particulière, il convient de définir une base de gabarit et d'utiliser la balise extends dans une page complémentaire comme dans l'exemple ci-dessous. Ensuite, il est nécessaire de préciser les sections qui seront modifiées en utilisant les balises block/endblock qui définissent le début et la fin de section.

À titre indicatif, l'extrait ci-dessous présente la manière d'activer à l'aide de la balise extends le remplacement de la section content. La page HTML générée inclura la structure de la page définie plus haut et le code généré à la fois pour la section title, mais avec les éléments nouveaux, ci-dessous, pour la section content.

Nous allons nous appuyer sur le gabarit ci-dessous pour construire la page de base de la bibliothèque locale. Vous le constatez, il contient des éléments HTML et des blocs dédiés Django pour spécifier trois sections title, sidebar, et content. La section title contient un titre par défaut. De même la section sidebar contient un lien vers la liste des livres et des auteurs qui pourra être modifié ensuite.

Note : Il y a aussi deux balises supplémentaires : url et load static. Elles seront étudiées dans le chapitre suivant.

Créez un nouveau fichier nommé base_generic.html dans le dossier /locallibrary/catalog/templates/ (à créer aussi) et copiez-y le texte ci-dessous :

Ce gabarit fait appel - en ligne 7 - à la bibliothèque de style Bootstrap afin d'améliorer la présentation de la page. L'utilisation de Bootstrap (ou de tout autre cadriciel pour les pages web) est un moyen rapide de créer des pages bien organisées et qui s'affiche très bien sur les différents navigateurs.

De même, ce gabarit fait appel à une feuille de style - en ligne 10 - locale pour ajouter ou adapter des styles. Créez le fichier styles.css dans le répertoire /locallibrary/catalog/static/css/ (à créer aussi) et copiez le contenu ci-dessous :

Maintenant créez le fichier HTML index.html dans le dossier /locallibrary/catalog/templates/ et copiez-y le code ci-dessous. Ce code étend le template de base sur la première ligne et remplace le bloc par défaut content pour le template.

Dans la section contenu dynamique, des emplacements réservés sont définis pour pouvoir y insérer le contenu de variable qui sont identifiées à l'intérieur de doubles accolades (ouvrantes et fermantes). Pour une meilleure visibilité ces emplacements et les variables nommées sont identifiées en caractères gras dans l'extrait de code ci-dessus.

Note : Vous pouvez constater simplement que les balises de gabarit (fonctions) et les balises de variables sont entre accolades ; double accolades pour une variable ({{ num_books }}), et simple accolade avec le pourcentage ({% extends "base_generic.html" %}) pour les balises.

Gardez en mémoire que les variables utilisées dans les gabarits sont des clés d'un dictionnaire context transmis à la fonction render() de la vue (revenez à l'exemple plus haut, ou l'extrait ci-dessous). La fonction render() traitera le dictionnaire pour restituer une page HTML où les variables nommées auront été remplacées par leur valeur dans le dictionnaire.

Vos projets utiliseront probablement de fichiers statiques, par exemple des images, des fichiers de styles CSS ou des fonctions JavaScript. L'emplacement de ces fichiers n'est pas connu a priori ou peut changer en fonction de l'emplacement dans un projet Django. Pour cela, Django vous permet de spécifier les emplacements dans les gabarits par rapport à la variable globale du projet STATIC_URL. Le paramétrage par défaut du site web définit la variable STATIC_URL à '/static/', mais vous pouvez choisir de l'héberger ailleurs.

Au sein du gabarit, vous faites appel à la balise load en précisant "static" pour faire votre ajout, comme décrits dans l'extrait ci-dessous. Vous utilisez la balise static et vous spécifiez ensuite l'URL pour accéder au fichier nécessaire.

De la même manière, vous pouvez par exemple :

Note : Les exemples ci-dessus indiquent où se trouvent les fichiers, mais le cadriciel ne travaille pas ainsi par défaut. Nous avons configuré le serveur web de développement en modifiant le routage des URL (/locallibrary/locallibrary/urls.py) à la création du squelette du site. Cependant nous devrons travailler plus tard la mise en production.

Pour plus de détails sur les fichiers statiques vous pouvez consulter la documentation Django sur la gestion des fichiers statiques.

L'exemple ci-dessous introduit l'utilisation de la balise de gabarit url.

Cette balise accepte des références enregistrées par la fonction path() appelée dans les fichiers urls.py ainsi que les valeurs pour chacun des arguments associés à une vue. Elle retourne une URL qui peut être utilisée pour lier une ressource.

Par défaut Django ne sait pas où sont vos gabarits, vous devez lui indiquer où les trouver. Pour ce faire, vous allez ajouter le répertoire des gabarits (templates) à la variable d'environnement du projet TEMPLATES en éditant le fichier settings.py comme indiqué en gras ci-dessous :