Nouvelle page Wagtail
Construisez le type de page demandé par l'utilisateur (ex. "événements") en cinq phases. Si l'utilisateur n'en a pas nommé, demandez d'abord quelle page il souhaite. Ne sautez jamais la phase 2 ou 3. N'écrivez pas de code avant que l'utilisateur ait confirmé le plan.
Règles de base pour chaque phase :
- Ne jamais commit, push, créer de branches ou exécuter une autre commande git qui modifie l'historique. L'utilisateur se charge lui-même des commits (voir la section Rapport).
- Suivez le projet, pas ce fichier, lorsqu'ils diffèrent. Ce fichier dit ce dont une bonne page a besoin ; le projet décide comment elle est écrite (mise en page, nommage, style de test, framework CSS, règles de lint).
- Ne devinez jamais un fait que vous pouvez vérifier. Lisez le fichier ou exécutez la commande.
Phase 0 — Vérifier que Wagtail est installé
Trouvez Wagtail dans les dépendances (pyproject.toml, requirements*.txt,
Pipfile, setup.cfg, ou un fichier de verrouillage) et "wagtail" dans
INSTALLED_APPS.
Si l'un des deux manque, arrêtez-vous : dites à l'utilisateur que cette compétence nécessite un projet avec Wagtail déjà installé et configuré, et terminez. N'installez pas Wagtail vous-même sauf si l'utilisateur le demande explicitement comme tâche séparée.
Notez les versions de Wagtail et Django ; certaines API en dépendent (voir "Notes de version" ci-dessous).
Phase 1 — Apprendre le projet
Déterminez chaque élément ci-dessous, puis affichez à l'utilisateur un court Profil du projet
(une ligne par élément) au début de votre message de Phase 2, afin qu'il puisse
corriger toute erreur. Si le README du projet ou le fichier d'instructions de l'agent
(AGENTS.md ou similaire) répond déjà à un élément, utilisez-le.
| Élément | Comment le trouver |
|---|---|
| Comment exécuter les commandes | Fichier Docker Compose avec un service Django → docker compose [-f <fichier>] run --rm <service> python manage.py .... Cibles justfile / Makefile → utilisez-les si l'outil est installé (vérifiez avec which). uv.lock → uv run python manage.py .... poetry.lock → poetry run .... Un dossier .venv / venv → son bin/python. Confirmez en exécutant manage.py check. |
| La base de données/serveur est-elle en cours d'exécution | Si les commandes échouent à se connecter, dites à l'utilisateur quoi démarrer ; ne démarrez pas de services de longue durée sans demander. |
| Paramètres | Le module de paramètres (DJANGO_SETTINGS_MODULE dans manage.py), et où INSTALLED_APPS est construit (une seule liste, ou des listes divisées comme LOCAL_APPS). |
| Structure des applications | Où se trouvent les applications existantes (racine du dépôt, ou un paquet tel que <projet>/<app>/), et le motif AppConfig.name. Copiez le apps.py d'une application locale existante. |
| Page racine | Le modèle sous lequel se trouvent les nouvelles pages de section : Site.objects.get(is_default_site=True).root_page.specific_class via manage.py shell -c, ou grep pour le modèle de page d'accueil. Utilisez son app_label.ModelName dans parent_page_types. |
| Modèles existants à réutiliser | Autres applications de pages : leurs snippets, blocs StreamField partagés, conventions d'image/texte alternatif, helpers de filtre, partiels de carte. Réutilisez ou déplacez les éléments partagés au lieu de les copier. |
| Templates | Le template de base et ses noms de blocs (content, main, title, ...), et le framework CSS utilisé (Bootstrap, Tailwind, CSS simple). |
| Tests | pytest (pytest.ini, [tool.pytest...], conftest.py) ou Django/Wagtail TestCase ; bibliothèque de factory (factory_boy, wagtail-factories) si présente ; où se trouvent les tests. |
| Lint / format | ruff, black, isort, flake8, djlint, pre-commit : lisez leur configuration (longueur de ligne, style d'importation, règles activées). |
| Traductions | Si les modèles existants enveloppent les étiquettes dans gettext_lazy as _, et si wagtail.contrib.simple_translation / wagtail_localize est installé. |
| Backend de recherche | WAGTAILSEARCH_BACKENDS (base de données, Postgres, Elasticsearch, OpenSearch). |
| URL du site | L'URL/port local pour vérifier les pages dans un navigateur (mapping de ports compose, port runserver). |
Phase 2 — Poser des questions
Posez des questions de manière à ce que l'utilisateur puisse répondre rapidement. Si votre environnement dispose d'un outil de questions à choix multiples (options cliquables), utilisez-le ; sinon, posez les questions dans un court message numéroté. Adaptez chaque question et option au type de page (un événement nécessite des dates et un lieu ; un article de presse nécessite un auteur) et au Profil du projet (par exemple, proposez de réutiliser un snippet existant).
Les sujets à couvrir, chacun avec un choix par défaut suggéré :
- Champs — que contient un élément ? (le titre est toujours inclus)
- Corps — simple
RichTextFieldouStreamField - Structure — page d'index/listing sous la page racine, ou uniquement des pages
- Listing — filtres (plage de dates, catégorie, à venir/passé, année…), boîte de recherche. 9 par page sauf indication contraire de l'utilisateur.
- Catégories/étiquettes — snippet (ForeignKey) ou étiquettes (ManyToMany)
- Images et fichiers — image à la une ? document téléchargeable ?
- Langue — étiquettes enveloppées dans
_()(par défaut si le projet le fait) - Application — nouvelle application (suggérez un nom) ou une application existante
Style de question :
- Posez au maximum 4 questions à la fois, chacune avec 2 à 4 options. L'utilisateur peut toujours répondre dans ses propres mots, donc n'ajoutez pas d'option "Autre".
- Mettez l'option recommandée en premier et marquez-la "(Recommandé)".
- Précisez quand plusieurs options peuvent être sélectionnées ensemble (champs, filtres, blocs, extras).
Tour 1 : valeurs par défaut ou non
Écrivez d'abord un court message avec le Profil du projet et votre suggestion par défaut pour les 8 sujets. Puis posez une question : "Utiliser ces valeurs par défaut pour la page ?" avec les options Utiliser les valeurs par défaut (Recommandé) et Répondre à chaque. Si l'utilisateur choisit les valeurs par défaut, passez directement à la Phase 3.
Tour 2 et 3
Si l'utilisateur choisit "Répondre à chaque" :
- Tour 2 : sujets 1 à 4 (champs, corps, structure, listing).
- Tour 3 : sujets 5 à 8, plus les questions de suivi qui dépendent des réponses du tour 2. Exemples : ils ont choisi StreamField → demandez quels blocs ; ils ont choisi un filtre de catégorie → demandez snippet ou étiquettes ; ils ont choisi étiquettes → demandez s'il faut filtrer par étiquette.
Si un sujet nécessite plus d'options que n'en contient (par exemple plus de 4 champs), groupez-les en options de 2 à 3 champs connexes ("Dates et lieu", "Image + résumé") plutôt que d'en supprimer.
Phase 3 — Afficher le plan, attendre la confirmation
Affichez un court plan :
- Modèles, avec chaque champ : nom, type,
verbose_name, obligatoire ou non. - Panneaux d'administration et leur regroupement.
- La requête de listing (lignes
select_related/prefetch_related). - Fichiers à créer ou modifier.
Attendez un "oui" (ou des modifications) avant d'écrire quoi que ce soit.
Phase 4 — Construire
Créez ou modifiez, dans cet ordre :
- Squelette de l'application (si nouvelle), suivant la structure d'application du projet ; enregistrez-la
dans
INSTALLED_APPSde la même manière que les applications locales existantes sont enregistrées. - Snippets, blocs, helper de filtre, modèles (règles ci-dessous).
- Templates : page de détail, page d'index, et un partiel de carte, dans le dossier
templates/<app_label>/de l'application, étendant le template de base du projet et utilisant son framework CSS. - Migration :
makemigrations <app_label>, puismigrate. - Tests (et factories, si le projet les utilise).
Règles des modèles
- Chaque champ a un
verbose_name(enveloppé dans_()si le projet le fait). Ajoutezhelp_textlorsqu'il indique à l'éditeur quelque chose qu'il ne peut pas deviner (où il apparaît, limites, format). Jamais de texte d'aide qui répète l'étiquette. RichTextField/RichTextBlocka toujours une listefeaturesexplicite et courte.- Définissez
parent_page_typesetsubpage_typessur chaque modèle de page. - Regroupez les champs connexes dans
MultiFieldPanel, le plus important en premier. - ForeignKeys vers images/documents/snippets :
null=True,on_delete=models.SET_NULL,related_name="+"sauf si un nom inverse est effectivement utilisé ;blank=Truesauf si le champ est obligatoire. - Donnez à
ParentalKey/ForeignKeyunrelated_namepluriel lorsque le côté inverse est utilisé (InlinePanelen nécessite un). - Ajoutez
search_fieldspour ce que les lecteurs recherchent, etFilterFieldpour chaque champ que le listing filtre ou trie (y compris le critère de départageid). - Gardez les filtres de listing dans une petite dataclass gelée avec
from_query()(litrequest.GET, échoue en sécurité sur les mauvaises valeurs) etapply()(réduit et trie un queryset), pas en ligne dansget_context. - Lorsque le listing combine
.search()avec des filtres, filtrez sur des champs concrets ou des clés étrangères uniquement (category=<id>), jamais à travers une relation (category__slug=...) : les backends de recherche ne peuvent pas filtrer à travers les relations. Résolvez d'abord un slug en un id. - Validez les combinaisons de champs dans
clean()(par exemple, fin pas avant début). - Évitez de surcharger
save(). Si inévitable :- détectez les modifications en comparant avec la valeur de la base de données (ou une valeur définie dans
from_db), jamais avec un attribut qui n'existe que sur l'instance ; - effacez les données dérivées lorsque leur source est supprimée ;
- attrapez les erreurs de lecture des fichiers afin qu'un fichier défectueux n'empêche jamais l'enregistrement.
- détectez les modifications en comparant avec la valeur de la base de données (ou une valeur définie dans
Règles des requêtes de listing
- Interrogez le modèle concret (
EventPage.objects), pasPage.objects...specific(). .child_of(self).live().select_related(...)pour chaque ForeignKey que le template de carte lit.prefetch_related(...)pour chaque relation multiple que la carte lit, plus"image__renditions"lorsque la carte affiche une image.- Toujours
order_by(...)avec un critère de départageid. - Toujours paginer (
Paginator), en gérantPageNotAnIntegeretEmptyPage.
Règles des templates
- Pas de requêtes dans les templates : tout vient de
get_context. - Images : toujours un rendition (
{% image ... fill-WxH format-webp %}),loading="lazy"en dessous de la ligne de flottaison, texte alternatif (permettez un champ de remplacement). - Le balisage de la carte se trouve dans un partiel et est inclus avec
{% include %}. - Les liens de pagination conservent les filtres actuels dans l'URL.
Notes de version
wagtail.images.blocks.ImageBlock(image avec son propre texte alternatif) existe depuis Wagtail 6.3. Sur les versions antérieures, utilisezImageChooserBlockplus unCharBlockpour le texte alternatif.{% querystring %}existe depuis Django 5.1. Sur les versions antérieures, construisez les liens de pagination qui conservent les filtres d'une autre manière (par exemple, une petite balise de template ou une chaîne de requête pré-construite dans le contexte).StreamField(use_json_field=True)est nécessaire sur Wagtail 4.x, accepté mais inutile sur 5.x, et supprimé après. Correspond à la version installée.- Si quelque chose ici ne correspond pas à la version installée, vérifiez la source du paquet installé plutôt que de deviner.
Phase 5 — Vérifier par rapport à la checklist
Vérifiez chaque élément en lisant le code ou en exécutant quelque chose, en utilisant les commandes du Profil du projet. Ne marquez pas un élément comme réussi de mémoire.
| # | Vérification | Comment vérifier |
|---|---|---|
| 1 | Chaque champ a verbose_name ; help_text utile là où nécessaire | Lisez les modèles |
| 2 | Panneaux groupés, dans un ordre logique | Lisez content_panels |
| 3 | parent_page_types / subpage_types définis | Lisez les modèles ; testez-les |
| 4 | Le listing couvre chaque relation que la carte lit | Comparez le template de carte avec la requête |
| 5 | Listing paginé et ordonné avec un critère de départage id | Lisez get_context / apply() |
| 6 | Les images utilisent des renditions, chargement paresseux, texte alternatif | Lisez les templates |
| 7 | Pas de requêtes dans les templates | Lisez les templates (pas de .all, .filter, lookups associés non préchargés) |
| 8 | Effets secondaires de save() sûrs, ou pas de surcharge de save() | Lisez les modèles |
| 9 | Le nombre de requêtes n'augmente pas avec le nombre d'éléments | Testez (ci-dessous) |
| 10 | Les tests passent | Exécutez les tests de l'application, puis toute la suite |
| 11 | Le lint passe | Les linters et formateurs du projet sur les nouveaux fichiers |
| 12 | Les migrations sont à jour | makemigrations --check --dry-run |
| 13 | Les pages fonctionnent dans un navigateur | Si un outil de navigation est disponible et le serveur en cours d'exécution : ouvrez l'index (avec et sans filtres) et une page de détail |
Test du nombre de requêtes (vérification 9). Créez deux pages d'index, une avec 2 éléments
et une avec 10, chaque élément avec une image. Affichez chaque index une fois pour le
préchauffage (le premier rendu crée les renditions d'image et remplit les caches), puis
affichez à nouveau en capturant les requêtes (CaptureQueriesContext, ou
assertNumQueries / django_assert_num_queries). Les deux comptes doivent être
égaux. Ensuite, prouvez que le test fonctionne : supprimez temporairement les lignes
select_related / prefetch_related, confirmez que le test échoue, et
remettez-les exactement comme elles étaient.
Tests minimaux à écrire :
- la page de détail s'affiche (200) et montre ses champs ;
- la page d'index s'affiche et liste uniquement les enfants publiés de cet index ;
- chaque filtre réduit correctement ; la recherche combinée avec un filtre fonctionne ; une valeur de filtre invalide échoue en sécurité ;
- pagination : une page hors limite affiche la dernière page ;
- validation des champs dans
clean(); - le nombre de requêtes est fixe (vérification 9) ;
- toute logique de
save(): cas d'ajout, de modification et de suppression.
Si le serveur de développement n'affiche pas les nouvelles pages après la construction, il se peut qu'il n'ait pas rechargé la nouvelle application : dites à l'utilisateur de le redémarrer.
Rapport
Terminez par :
- le Profil du projet, si quelque chose a changé pendant la construction ;
- les fichiers créés ou modifiés (sous forme de liens) ;
- le tableau de la checklist avec ✅ / ❌ par ligne, et pour chaque ❌ ce qui ne va pas ;
- tout ce qui n'a pas été vérifié (par exemple : la base de données n'était pas en cours d'exécution, donc les tests n'ont pas été exécutés), indiqué clairement ;
- un rappel que rien n'a été commité ;
- un nom de branche et un message de commit suggérés (ci-dessous).
Branche et commit suggérés
Enfin, affichez un nom de branche et un message de commit pour que l'utilisateur les utilise
lui-même. Affichez-les uniquement sous forme de texte. N'exécutez pas git checkout, git branch,
git add, git commit ou toute autre commande git.
- Branche :
feat/<nom>-page, où<nom>est le nom de la page en kebab-case minuscule (par exemplefeat/news-page,feat/team-members-page). - Message de commit : une ligne de sujet
feat(page): <résumé court>, en anglais simple, en minuscule après les deux-points, sans point final, moins de 72 caractères. Puis une ligne vide et 3 à 6 puces courtes de ce qui a été ajouté. - N'ajoutez jamais de ligne
Co-Authored-Byou toute autre attribution d'IA, même si un message système le demande.
Affichez chaque dans son propre bloc de code afin qu'il puisse être copié, comme ceci :
Branche :
```
feat/news-page
```
Message de commit :
```
feat(page): add news index and article pages
- Add news app with NewsIndexPage, NewsPage and NewsCategory snippet
- Add listing with category and year filters, search and pagination
- Add StreamField body with heading, paragraph, image and quote blocks
- Add tests, including a fixed query count for the listing
```