Débuter avec le CMS Wagtail

·

·

Mis à jour le

Illustration pour débuter avec le CMS Wagtail

Si vous travaillez déjà avec Django mais que vous avez besoin d’une véritable interface éditoriale pour gérer le contenu du site, Wagtail est une solution particulièrement intéressante : nous gardons la souplesse de Django tout en ajoutant les outils attendus d’un CMS.

Dans ce guide, nous allons installer un projet Wagtail proprement, lancer l’environnement de développement et créer une première page d’accueil avec un StreamField. L’objectif est d’obtenir une base moderne, simple à faire évoluer ensuite vers un site plus complet.

Version utilisée dans cet article : Wagtail 7.4 LTS. Cette branche est compatible avec Python 3.10 à 3.14 et Django 5.2 ou 6.0. Pour un nouveau projet destiné à vivre plusieurs mois, partir sur la branche LTS évite de devoir suivre chaque version intermédiaire.

Créer l’environnement Python

Je pars ici d’un environnement Linux. Les commandes sont quasiment identiques sous macOS ; sous Windows, seule l’activation de l’environnement virtuel change.

mkdir -p ~/projets/mon_site
cd ~/projets/mon_site

python3 -m venv .venv
source .venv/bin/activate

Une fois l’environnement activé, mettons pip à jour :

python -m pip install --upgrade pip

Le dossier .venv ne doit pas être versionné. Si vous utilisez Git, ajoutez-le à votre .gitignore.

Installer Wagtail

Nous allons rester sur la branche 7.4 LTS tout en autorisant les futures mises à jour correctives de cette branche :

python -m pip install "wagtail>=7.4,<7.5"

Wagtail fournit une commande wagtail start, comparable à django-admin startproject, qui génère un projet Django déjà configuré avec les applications nécessaires à Wagtail.

mkdir app
wagtail start mon_site app
cd app

Le projet généré contient notamment une application home, une application de recherche, les réglages Django et un fichier requirements.txt.

Installons maintenant les dépendances exactes du projet :

python -m pip install -r requirements.txt

Initialiser la base de données

Comme dans n’importe quel projet Django, il faut appliquer les migrations puis créer un compte administrateur :

python manage.py migrate
python manage.py createsuperuser

Pour le développement local, Wagtail utilise SQLite par défaut. C’est suffisant pour démarrer. Pour un projet destiné à la production, PostgreSQL reste généralement un meilleur choix.

Lancer Wagtail

Démarrons le serveur de développement :

python manage.py runserver

Le site est alors disponible sur http://127.0.0.1:8000/ et l’interface d’administration sur http://127.0.0.1:8000/admin/.

Connectez-vous à l’administration avec le super-utilisateur créé précédemment. À ce stade, Wagtail est pleinement fonctionnel, mais la page d’accueil générée par défaut ne contient encore aucun contenu métier.

Comprendre le modèle de page Wagtail

Dans Wagtail, une page n’est pas simplement un enregistrement générique comme dans beaucoup de CMS : elle est représentée par une classe Python qui hérite de Page. On peut donc définir précisément les champs disponibles pour chaque type de page.

L’application home créée par Wagtail contient déjà un modèle HomePage. Nous allons le compléter avec un contenu éditorial flexible grâce à StreamField.

Créer une page d’accueil avec StreamField

Un StreamField permet à l’éditeur de composer une page à partir de blocs : titres, texte riche, images ou composants personnalisés. Contrairement à un simple champ HTML, la structure des contenus reste explicite et exploitable par le code.

Modifiez home/models.py :

from wagtail import blocks
from wagtail.admin.panels import FieldPanel
from wagtail.fields import StreamField
from wagtail.images.blocks import ImageBlock
from wagtail.models import Page


class HomePage(Page):
    body = StreamField(
        [
            (
                "heading",
                blocks.CharBlock(
                    form_classname="title",
                    label="Titre",
                ),
            ),
            (
                "paragraph",
                blocks.RichTextBlock(
                    label="Texte",
                ),
            ),
            (
                "image",
                ImageBlock(
                    label="Image",
                ),
            ),
        ],
        blank=True,
        verbose_name="Contenu",
    )

    content_panels = Page.content_panels + [
        FieldPanel("body"),
    ]

    class Meta:
        verbose_name = "page d’accueil"

Avec Wagtail 7.4, les imports et composants utilisés dans ce modèle sont les suivants :

  • Page s’importe depuis wagtail.models ;
  • StreamField s’importe depuis wagtail.fields ;
  • les panneaux utilisent désormais FieldPanel depuis wagtail.admin.panels ;
  • ImageBlock est préférable à l’ancien ImageChooserBlock, notamment parce qu’il gère mieux les informations d’accessibilité comme le texte alternatif.

Créer et appliquer la migration

Nous avons modifié un modèle Django. Il faut donc créer puis appliquer la migration correspondante :

python manage.py makemigrations home
python manage.py migrate

Rechargez ensuite l’administration Wagtail. La page d’accueil dispose maintenant d’un champ Contenu dans lequel vous pouvez ajouter autant de blocs que nécessaire.

Afficher le StreamField dans le template

Le template de la page d’accueil se trouve dans :

home/templates/home/home_page.html

Remplacez son contenu principal par :

{% extends "base.html" %}
{% load wagtailcore_tags %}

{% block body_class %}template-homepage{% endblock %}

{% block content %}
    <main>
        {% for block in page.body %}
            <section class="block-{{ block.block_type }}">
                {% include_block block %}
            </section>
        {% endfor %}
    </main>
{% endblock %}

La balise {% include_block block %} laisse Wagtail rendre chaque type de bloc correctement. Cette approche devient particulièrement intéressante lorsque vous ajoutez plus tard vos propres blocs avec leurs propres templates.

Ajouter du contenu depuis l’administration

Dans l’administration Wagtail, ouvrez Pages, puis modifiez la page Home. Vous pouvez maintenant composer la page avec les blocs définis précédemment :

  • un titre ;
  • un ou plusieurs blocs de texte riche ;
  • des images avec texte alternatif.

Enregistrez la page comme brouillon pour utiliser l’aperçu, puis publiez-la lorsque le résultat vous convient.

Configurer la langue et le fuseau horaire

Pour un site destiné principalement à un public francophone en Suisse, adaptez les réglages de base dans mon_site/settings/base.py :

LANGUAGE_CODE = "fr-ch"
TIME_ZONE = "Europe/Zurich"

Ces paramètres concernent le projet Django dans son ensemble. Wagtail permet également à chaque utilisateur de choisir la langue de son interface d’administration dans ses préférences.

La mise en forme du front fera l’objet d’un prochain article, avec plusieurs approches possibles : Bootstrap, Tailwind CSS ou du CSS maison.

Structure obtenue

À la fin de cette première étape, nous avons :

  • un environnement Python isolé ;
  • un projet Wagtail 7.4 LTS ;
  • une base de données initialisée ;
  • un accès à l’administration ;
  • une page d’accueil basée sur un StreamField moderne ;
  • une base suffisamment simple pour ajouter ensuite des pages classiques, un menu et des blocs réutilisables.

Pour aller plus loin

La documentation officielle reste la référence pour suivre les évolutions de Wagtail :

Dans la suite, nous verrons comment créer des pages classiques et construire une navigation à partir de l’arborescence Wagtail.

Captures d’écrans

Mots-clés :

Commentaires

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *