new-page

Construit un nouveau type de page Wagtail (page de détail plus une éventuelle page d'index/listing) dans tout projet Django + Wagtail. Apprend la configuration du projet, pose les bonnes questions à l'utilisateur, affiche un plan à confirmer, le construit, puis le vérifie par rapport à une checklist de performance et de qualité.

Qu'est-ce que new-page ?

Cette compétence (skill) permet de créer de nouveaux types de pages Wagtail de manière structurée et fiable, adaptée à tout projet Django + Wagtail. Elle analyse d'abord la configuration du projet (commandes, paramètres, structure des applications, etc.), puis interroge l'utilisateur avec des questions à choix multiples pour définir les champs, le contenu, l'organisation, le listing et les fonctionnalités (catégories, images, etc.). Un plan détaillé est présenté à l'utilisateur pour confirmation avant toute écriture de code. La construction génère les modèles, les templates, les migrations et les tests, en suivant les règles de qualité du projet (verbose_name, help_text, parent_page_types, search_fields, etc.). Enfin, une checklist automatisée vérifie chaque aspect : champs, panels, requêtes optimisées, rendu des images, tests, lint, etc. Cette compétence fonctionne avec Claude Code, Cursor et d'autres agents IA, et garantit que le code produit respecte les conventions du projet et les bonnes pratiques Wagtail.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MohammedAlrowais/wagtail-new-page-skill/tree/main/new-page

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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émentComment le trouver
Comment exécuter les commandesFichier 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écutionSi les commandes échouent à se connecter, dites à l'utilisateur quoi démarrer ; ne démarrez pas de services de longue durée sans demander.
ParamètresLe 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 applicationsOù 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 racineLe 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éutiliserAutres 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.
TemplatesLe template de base et ses noms de blocs (content, main, title, ...), et le framework CSS utilisé (Bootstrap, Tailwind, CSS simple).
Testspytest (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 / formatruff, black, isort, flake8, djlint, pre-commit : lisez leur configuration (longueur de ligne, style d'importation, règles activées).
TraductionsSi les modèles existants enveloppent les étiquettes dans gettext_lazy as _, et si wagtail.contrib.simple_translation / wagtail_localize est installé.
Backend de rechercheWAGTAILSEARCH_BACKENDS (base de données, Postgres, Elasticsearch, OpenSearch).
URL du siteL'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é :

  1. Champs — que contient un élément ? (le titre est toujours inclus)
  2. Corps — simple RichTextField ou StreamField
  3. Structure — page d'index/listing sous la page racine, ou uniquement des pages
  4. Listing — filtres (plage de dates, catégorie, à venir/passé, année…), boîte de recherche. 9 par page sauf indication contraire de l'utilisateur.
  5. Catégories/étiquettes — snippet (ForeignKey) ou étiquettes (ManyToMany)
  6. Images et fichiers — image à la une ? document téléchargeable ?
  7. Langue — étiquettes enveloppées dans _() (par défaut si le projet le fait)
  8. 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 :

  1. Squelette de l'application (si nouvelle), suivant la structure d'application du projet ; enregistrez-la dans INSTALLED_APPS de la même manière que les applications locales existantes sont enregistrées.
  2. Snippets, blocs, helper de filtre, modèles (règles ci-dessous).
  3. 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.
  4. Migration : makemigrations <app_label>, puis migrate.
  5. 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). Ajoutez help_text lorsqu'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 / RichTextBlock a toujours une liste features explicite et courte.
  • Définissez parent_page_types et subpage_types sur 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=True sauf si le champ est obligatoire.
  • Donnez à ParentalKey/ForeignKey un related_name pluriel lorsque le côté inverse est utilisé (InlinePanel en nécessite un).
  • Ajoutez search_fields pour ce que les lecteurs recherchent, et FilterField pour chaque champ que le listing filtre ou trie (y compris le critère de départage id).
  • Gardez les filtres de listing dans une petite dataclass gelée avec from_query() (lit request.GET, échoue en sécurité sur les mauvaises valeurs) et apply() (réduit et trie un queryset), pas en ligne dans get_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.

Règles des requêtes de listing

  • Interrogez le modèle concret (EventPage.objects), pas Page.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épartage id.
  • Toujours paginer (Paginator), en gérant PageNotAnInteger et EmptyPage.

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, utilisez ImageChooserBlock plus un CharBlock pour 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érificationComment vérifier
1Chaque champ a verbose_name ; help_text utile là où nécessaireLisez les modèles
2Panneaux groupés, dans un ordre logiqueLisez content_panels
3parent_page_types / subpage_types définisLisez les modèles ; testez-les
4Le listing couvre chaque relation que la carte litComparez le template de carte avec la requête
5Listing paginé et ordonné avec un critère de départage idLisez get_context / apply()
6Les images utilisent des renditions, chargement paresseux, texte alternatifLisez les templates
7Pas de requêtes dans les templatesLisez les templates (pas de .all, .filter, lookups associés non préchargés)
8Effets secondaires de save() sûrs, ou pas de surcharge de save()Lisez les modèles
9Le nombre de requêtes n'augmente pas avec le nombre d'élémentsTestez (ci-dessous)
10Les tests passentExécutez les tests de l'application, puis toute la suite
11Le lint passeLes linters et formateurs du projet sur les nouveaux fichiers
12Les migrations sont à jourmakemigrations --check --dry-run
13Les pages fonctionnent dans un navigateurSi 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 exemple feat/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-By ou 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
```

Skills associés