Tutoriel : Servir des fichiers statiques et utiliser l’héritage de modèle avec Django dans Visual Studio

Article
02/07/2025

Cet article présente l’étape 3 de la série de tutoriels Utiliser l’infrastructure web Django dans Visual Studio.

L’étape précédente de cette série de tutoriels crée une application Django minimale avec une seule page de code HTML autonome. Les applications web modernes sont généralement composées de nombreuses pages et utilisent des ressources partagées telles que des fichiers CSS et JavaScript pour fournir un style et un comportement cohérents. À l’étape 3, vous travaillez avec des modèles d’éléments Visual Studio pour ajouter du contenu à votre projet Django et développer les fonctionnalités de l’application.

À l’étape 3 du didacticiel, vous allez apprendre à :

Utiliser des modèles d’élément Visual Studio pour ajouter rapidement de nouveaux fichiers avec du code réutilisable
Servir des fichiers statiques à partir du code Django
Ajouter d’autres pages à l’application Django
Utiliser l’héritage de modèle pour créer un en-tête et une navigation entre les pages

Conditions préalables

Une solution Visual Studio et des projets d’application Django créés à l’étape 1 : créer le projet Django et mis à jour à l’étape 2 : Créer une application Django avec des vues et des modèles de page de cette série de tutoriels.
Consultez la section Prérequis de l’étape 1 de cette série de tutoriels pour plus d’informations sur les versions de modèles Django, les projets Visual Studio et les projets Django et le développement Python sur Mac.

Explorer les modèles d’élément dans Visual Studio

Lorsque vous développez une application Django, vous ajoutez généralement de nombreux autres fichiers Python, HTML, CSS et JavaScript. Pour chaque type de fichier (et d’autres fichiers comme web.config que vous devrez peut-être déployer), Visual Studio fournit des modèles d’éléments pratiques pour vous aider à démarrer. Vous pouvez utiliser ces modèles pour ajouter rapidement de nouveaux fichiers de différents types avec du code réutilisable.

Pour afficher les modèles disponibles, accédez à Explorateur de solutions dans Visual Studio et ouvrez votre structure de projet.
Cliquez avec le bouton droit sur le dossier dans lequel vous souhaitez créer un fichier, puis sélectionnez Ajouter>nouvel élément. La boîte de dialogue Ajouter un nouvel élément s’ouvre :
Pour utiliser un modèle, sélectionnez le modèle souhaité, entrez un nom pour le fichier, puis sélectionnez Ajouter.

Visual Studio ajoute le fichier à votre projet actuel et marque les modifications pour le contrôle de code source.

Comprendre comment Visual Studio identifie les modèles d’élément

Le fichier projet Visual Studio (.pyproj) contient un identificateur de type de projet qui marque le fichier en tant que projet Python. Visual Studio utilise cet identificateur de type pour reconnaître et afficher uniquement les modèles d’élément qui conviennent au type de projet. Visual Studio suit cette approche pour fournir un ensemble complet de modèles d’éléments pour de nombreux types de projet sans vous demander de les trier à chaque fois.

Servir des fichiers statiques à partir de votre application

Dans une application web créée avec Python (à l’aide de n’importe quelle infrastructure), vos fichiers Python s’exécutent toujours sur le serveur de l’hôte web et ne sont jamais transmis à l’ordinateur d’un utilisateur. D’autres fichiers tels que CSS et JavaScript sont utilisés uniquement par le navigateur. Par conséquent, le serveur hôte les remet simplement as-is lorsqu’ils sont demandés. Ces types de fichiers sont appelés fichiers « statiques », et Django peut les remettre automatiquement sans que vous ayez besoin d’écrire du code.

Un projet Django est configuré par défaut pour servir des fichiers statiques à partir du dossier statique de l’application. Ce comportement est rendu possible par le code suivant dans le fichier settings.py du projet Django :

# Static files (CSS, JavaScript, Images)
# https://docs.djangoproject.com/en/1.9/howto/static-files/

STATIC_URL = '/static/'

STATIC_ROOT = posixpath.join(*(BASE_DIR.split(os.path.sep) + ['static']))

Vous pouvez organiser les fichiers dans le dossier statique de l’application à l’aide de n’importe quelle structure de dossiers que vous aimez et utiliser des chemins relatifs dans le dossier statique pour faire référence aux fichiers.

Utiliser un fichier CSS statique dans un modèle HTML

Procédez comme suit pour ajouter un fichier CSS à l’application, puis utilisez la feuille de style CSS dans le modèle index.html :

Dans de l’Explorateur de solutions, cliquez avec le bouton droit sur le dossier HelloDjangoApp dans votre projet, sélectionnez Ajouter>nouveau dossier, puis nommez le dossier statique.
Cliquez avec le bouton droit sur le dossier statique, puis sélectionnez Ajouter>nouvel élément.
Dans la boîte de dialogue Ajouter un nouvel élément, sélectionnez le modèle de feuille de style , nommez le fichier site.cs, puis sélectionnez Ajouter.

Visual Studio ajoute le fichier site.css au projet et ouvre le fichier dans l’éditeur. Voici un exemple de la structure de projet Django mise à jour :
Remplacez le contenu du fichier site.css par les styles suivants :
```
.message {
    font-weight: 600;
    color: blue;
}
```
Remplacez le contenu du fichier HelloDjangoApp/templates/index.html par le balisage suivant :
```
<html>
   <head>
      <title>{{ title }}</title>
      {% load static %} 
      <link rel="stylesheet" type="text/css" href="{% static 'site.css' %}" />
   </head>
   <body>
      <span class="message">{{ message }}</span>{{ content }}
   </body>
</html>
```
Ce code remplace l’élément HTML <strong> de l’étape 2 de la série de tutoriels par un élément <span> qui fait référence à la classe de style message. L’utilisation d’une classe de style de cette façon vous offre davantage de flexibilité dans le style de l’élément HTML.
Enregistrez les modifications de votre projet en sélectionnant Fichier>Tout enregistrer ou en utilisant le raccourci clavier Ctrl+Maj+S. (Cette étape n’est pas nécessaire, car lorsque vous développez votre projet, Visual Studio enregistre automatiquement vos fichiers.)
Exécutez le projet et observez les résultats. Lorsque vous avez terminé, arrêtez l’application.
(Facultatif) Vous pouvez valider vos modifications dans le contrôle de code source et mettre à jour votre référentiel distant. Pour plus d’informations, consultez Valider les modifications apportées au contrôle de code source à l’étape 2 de cette série de tutoriels.

Utiliser la balise {% load static %}

L’instruction {% load static %} doit être présente dans le fichier index.html avant les références relatives au site pour les fichiers statiques dans des éléments HTML tels que <head> et <body>. Dans l’exemple présenté dans cette section, les « fichiers statiques » font référence à un jeu d’étiquettes de modèle Django personnalisé. Le jeu d’étiquettes vous permet d’utiliser la syntaxe {% static %} pour faire référence aux fichiers statiques. Sans la balise {% load static %}, une exception s’affiche lorsque l’application s’exécute.

Ajouter des références sans la balise {% load static %}

Vous pouvez également configurer des références relatives de site aux fichiers statiques dans le balisage HTML sans utiliser la balise de {% load static %}. Dans ce cas, vous spécifiez l’emplacement du dossier statique dans la hiérarchie des dossiers du projet Django :

<html>
    <head>
        <title>{{ title }}</title>
        <link rel="stylesheet" type="text/css" href="../../static/site.css" />
    </head>
    <body>
        <span class="message">{{ message }}</span>{{ content }}
    </body>
</html>

Organiser les fichiers et dossiers statiques

Vous pouvez ajouter d’autres fichiers CSS, JavaScript et HTML dans votre dossier de statique en fonction des besoins de votre projet. Un moyen classique d’organiser les fichiers statiques consiste à créer des sous-dossiers nommés polices, scriptset contenu (pour les feuilles de style et tous les autres fichiers). Dans chaque cas, n’oubliez pas d’inclure les dossiers dans le chemin relatif du fichier dans les références {% static %}.

Ajouter une page à l’application Django

L’ajout d’une autre page à l’application Django implique les tâches suivantes :

Ajouter une fonction Python qui définit la vue
Ajouter un modèle pour le balisage HTML de la page
Mettre à jour les itinéraires d’URL dans le fichier urls.py du projet Django

Suivez ces étapes pour ajouter une page About (/about) au projet HelloDjangoApp, ainsi que des liens vers cette page à partir de la page d’accueil :

Dans explorateur de solutions, cliquez avec le bouton droit sur le dossier templates/HelloDjangoApp dans votre projet, puis sélectionnez Ajouter>nouvel élément.

Conseil

Si vous ne voyez pas la commande Nouvel élément dans le menu Ajouter, veillez à arrêter votre application Django afin que Visual Studio quitte le mode débogage, si nécessaire.
Dans la boîte de dialogue Ajouter un nouvel élément, sélectionnez le modèle page HTML, nommez le fichier about.html, puis sélectionnez Ajouter.

Remplacez le contenu du fichier about.html par le balisage HTML suivant :

<html>
   <head>
      <title>{{ title }}</title>
      {% load static %}
      <link rel="stylesheet" type="text/css" href="{% static 'site.css' %}" />
   </head>
   <body>
      <div><a href="home">Home</a></div>
      {{ content }}
   </body>
</html>

Dans une étape suivante, vous remplacez le lien explicite vers la page d’accueil par une barre de navigation.

Dans le fichier HelloDjangoApp/views.py, ajoutez une fonction nommée about qui utilise le modèle :

def about(request):
   return render(
      request,
      "HelloDjangoApp/about.html",
      {
         'title' : "About HelloDjangoApp",
         'content' : "Example app page for Django."
      }
   )

Dans le fichier BasicProject/urls.py du projet Django, ajoutez le chemin d’accès de la page about en tant que dernier élément du tableau urlPatterns :

# Django processes URL patterns in the order they appear in the array
urlpatterns = [
   re_path(r'^$', HelloDjangoApp.views.index, name='index'),
   re_path(r'^home$', HelloDjangoApp.views.index, name='home'),
   re_path(r'^about$', HelloDjangoApp.views.about, name='about')
 ]

Dans le fichier templates/HelloDjangoApp/index.html, ajoutez le balisage suivant comme première instruction dans l’élément <body> :
```
<div><a href="about">About</a></div>
```
Ce balisage ajoute un lien à la page /about de l’application Django. Dans une étape ultérieure, vous remplacez ce lien par une barre de navigation.
Enregistrez les modifications de votre projet et réexécutez le projet. Accédez à la page /about et vérifiez la navigation entre les différentes pages d’application.
Lorsque vous avez terminé, arrêtez l’application.

Route vers la page « index »

Si vous essayez d’accéder à la page /index de votre application en cours d’exécution, vous voyez une Page introuvable (404) erreur.

Bien que le fichier HelloDjangoApp/views.py ait une fonction nommée index, les modèles de routage d’URL dans le fichier BasicProject/urls.py du projet Django ne contiennent pas d’expression régulière qui correspond à la chaîne index. L’expression actuelle de la page « index » de l’application est ^$. Pour faire correspondre la chaîne index, vous devez ajouter une autre entrée d’URL pour le modèle ^index$.

La section suivante décrit comment il est préférable d’utiliser la balise {% url '<pattern_name>' %} dans le modèle de page pour faire référence au nom d’un modèle. Dans ce cas, Django crée l’URL appropriée pour vous. Par exemple, vous pouvez remplacer le balisage <div><a href="home">Home</a></div> dans le fichier templates/HelloDjangoApp/about.html par le balisage <div><a href="{% url 'index' %}">Home</a></div>. L’utilisation de la chaîne 'index' fonctionne maintenant, car le premier modèle d’URL du fichier urls.py est nommé 'index'. Vous pouvez également utiliser 'home' pour faire référence au deuxième modèle.

Utiliser l’héritage du modèle pour l’en-tête et la navigation

Au lieu de liens de navigation explicites sur chaque page, de nombreuses applications web ont un en-tête de personnalisation et une barre de navigation qui fournit les liens de page les plus importants, les menus contextuels, et ainsi de suite. Pour garantir la cohérence au sein de l’application, la barre d’en-tête et de navigation doit être la même sur toutes les pages, mais vous n’avez pas besoin de répéter le même code dans chaque modèle de page. Vous pouvez définir les parties communes de toutes vos pages dans un seul fichier.

Le système de création de modèles de Django offre deux façons de réutiliser des éléments spécifiques sur plusieurs modèles :

Les fichiers inclus représentent d’autres modèles de pages que vous insérez à un endroit spécifique dans le modèle de référence avec la syntaxe {% include <template_path> %}. Vous pouvez également utiliser une variable si vous souhaitez modifier le chemin dynamiquement dans le code. Les fichiers inclus sont généralement utilisés dans le corps d’une page pour s’extraire dans le modèle partagé dans un emplacement spécifique de la page.
L’héritage utilise la syntaxe {% extends <template_path> %} au début d’un modèle de page pour spécifier un modèle de base partagé sur lequel le modèle de référence s’appuie. L’héritage est utilisé couramment pour définir des éléments partagés comme la disposition, la barre de navigation et d’autres structures des pages d’une application. Cette approche exige que les modèles de référence ajoutent ou modifient uniquement des zones spécifiques du modèle de base appelé blocs.

Pour les deux approches, la valeur <template_path> est relative aux modèles de l’application dossier (../ ou ./ sont également autorisés).

Un modèle de base délimite les blocs à l’aide des balises {% block <block_name> %} et {% endblock %}. Si un modèle de référence utilise des balises portant le même nom de bloc, le contenu du bloc dans le modèle de référence remplace le bloc correspondant dans le modèle de base.

Les étapes suivantes illustrent l’héritage du modèle :

Dans explorateur de solutions, cliquez avec le bouton droit sur le dossier templates/HelloDjangoApp, puis créez un fichier à partir du modèle page HTML avec le nom layout.html.

Remplacez le contenu du fichier layout.html par le balisage HTML suivant :

<!DOCTYPE html>
<html>
<head>
   <meta charset="utf-8" />
   <title>{{ title }}</title>
   {% load static %}
   <link rel="stylesheet" type="text/css" href="{% static 'site.css' %}" />
</head>

<body>
   <div class="navbar">
      <a href="/" class="navbar-brand">Hello Django</a>
      <a href="{% url 'home' %}" class="navbar-item">Home</a>
      <a href="{% url 'about' %}" class="navbar-item">About</a>
   </div>

   <div class="body-content">
      {% block content %}
      {% endblock %}
      <hr/>
      <footer>
         <p>&copy; 2024</p>
      </footer>
   </div>
</body>
</html>

Ce modèle contient un bloc nommé content, qui identifie tout le contenu que les pages de référence doivent remplacer.

Dans le fichier HelloDjangoApp/static/site.css, ajoutez les styles suivants à la fin du fichier :

.navbar {
   background-color: lightslategray;
   font-size: 1em;
   font-family: 'Trebuchet MS', 'Lucida Sans Unicode', 'Lucida Grande', 'Lucida Sans', Arial, sans-serif;
   color: white;
   padding: 8px 5px 8px 5px;
}

.navbar a {
   text-decoration: none;
   color: inherit;
}

.navbar-brand {
   font-size: 1.2em;
   font-weight: 600;
}

.navbar-item {
   font-variant: small-caps;
   margin-left: 30px;
}

.body-content {
   padding: 5px;
   font-family:'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
}

Ces définitions de style génèrent un résultat intéressant pour cet exercice. Cette procédure pas à pas n’illustre pas la conception réactive.

Remplacez le contenu du fichier templates/HelloDjangoApp/index.html par le code suivant :
```
{% extends "HelloDjangoApp/layout.html" %}
{% block content %}
<span class="message">{{ message }}</span>{{ content }}
{% endblock %}
```
Le modèle index fait désormais référence au modèle de base et remplace le bloc content. Vous pouvez voir qu’à l’aide de l’héritage, ce modèle est simplifié.
Remplacez le contenu du fichier templates/HelloDjangoApp/about.html par le code suivant. Par conséquent, le modèle about fait également référence au modèle de base et remplace le bloc content :
```
{% extends "HelloDjangoApp/layout.html" %}
{% block content %}
{{ content }}
{% endblock %}
```
Réexécutez l’application et observez les résultats. Utilisez les liens de la barre de navigation pour basculer entre les pages d’application.
Lorsque vous avez terminé, arrêtez l’application et enregistrez les modifications apportées à votre projet.
Étant donné que vous avez apporté des modifications substantielles à l’application, il est judicieux d’enregistrer vos modifications dans un dépôt Git. Pour plus d’informations, consultez Valider les modifications apportées au contrôle de code source à l’étape 2 de cette série de tutoriels.

Étape suivante

Étape 4 : utiliser le modèle de projet web Django complet

Partage via