Menu

Français,

Templates

Tutoriel : rendre administrable la photo de chaque carte d'une section dans EmDash

Tiré du code d'un vrai thème : un sous-champ image dans un repeater, une migration rejouable, et la photo du thème en repli quand le champ est vide.

La côte ouest d'Oahu vue du ciel : une plage dorée, le lagon et la montagne au soleil couchant.

Aloha Pixel7 min de lecture

L’accueil de notre thème Aloha a trois cartes de promesse, chacune avec sa photographie. Jusqu’au 13 novembre 2026, un éditeur pouvait changer leurs titres et leurs textes depuis le back office EmDash, pas leurs photos. Le correctif est sorti avec notre socle 3.38.0. C’est un petit changement en trois parties, et chaque partie est une erreur possible sur votre propre thème :

  1. le schéma de la base doit avoir un champ pour la photo ;
  2. l’écran du back office doit montrer ce champ ;
  3. le composant doit le lire, et garder la photo du thème quand il est vide.

Tout le code ci-dessous vient du thème et de son socle, raccourci seulement là où c’est indiqué.

Le point de départ

Dans nos thèmes, les blocs d’une page vivent dans une collection sections. Un bloc fait d’éléments répétés (promesses, étapes, témoignages, logos) range ses éléments dans un seul champ repeater, arguments. Chaque élément a déjà ses sous-champs : titre, texte, icône, lien, ancre.

La photo a sa place là, à côté du titre du même élément. Pas dans une nouvelle collection : l’éditeur règle une carte à un seul endroit.

En base, un repeater est une colonne JSON côté contenu, et sa liste de sous-champs est décrite dans la définition du champ : la colonne validation de _emdash_fields, sous la clé subFields. Ajouter un sous-champ n’ajoute aucune colonne. Seule cette description change.

Partie 1 : le schéma, pour les nouveaux sites et les anciens

Les nouveaux sites reçoivent le sous-champ par la graine. Mais une graine s’applique une seule fois, à une base vide, pendant l’installation ; la documentation d’EmDash le dit clairement, ce n’est pas un système de migration. Chaque site installé avant le changement doit recevoir le sous-champ dans sa base en service.

Le sous-champ est défini une fois, avec le même identifiant, le même libellé et le même type que dans les graines qui l’ont déjà :

export const SOUS_CHAMP_PHOTO = { slug: "image", label: "Photo (vide : celle du thème)", type: "image" } as const;

Une fonction écrit ensuite le SQL qui l’ajoute. L’essentiel est la garde. La mise à jour ne touche qu’un champ qui est un repeater de la collection nommée, dont la description porte une liste de sous-champs, et où aucun sous-champ ne s’appelle déjà image :

const leChamp = `slug = ${q(champ)} AND type = 'repeater' AND collection_id IN (SELECT id FROM _emdash_collections WHERE slug = ${q(collection)})`;
const sansPhoto = `json_valid(validation) AND json_type(validation, '$.subFields') = 'array' AND NOT EXISTS (SELECT 1 FROM json_each(validation, '$.subFields') WHERE json_extract(value, '$.slug') = ${q(SOUS_CHAMP_PHOTO.slug)})`;

L’écriture ajoute le sous-champ par json_insert(validation, '$.subFields[#]', ...) sous ces conditions. Jouée deux fois, la seconde ne touche aucune ligne. C’est ce qui permet de la passer sur tous les sites sans vérifier à la main lesquels en ont besoin.

Une seconde instruction, sous la même garde, avance la date updated_at de la collection. Notre frontal lit le schéma avec la version du contenu : les pages gardées se rendent donc à neuf.

Un script l’enveloppe, avec trois modes : --verifier n’écrit rien et sort en code 1 s’il manque un champ photo, --essai affiche le SQL sans le passer, et par défaut il lit l’état, passe le SQL gardé, puis relit. Nous prenons un signet Time Travel de D1 avant de le lancer sur une base de production. Le 13 novembre 2026, il a trouvé le sous-champ absent de deux de nos bases de démo et l’a ajouté ; aucun contenu n’a été touché.

Les règles vivent dans un module qui n’importe ni Astro ni EmDash. Son self-check joue 28 contrôles, dont la migration passée deux fois sur une vraie base SQLite.

Partie 2 : montrer le champ dans l’écran du bloc

Notre back office ne montre, pour chaque bloc, que les champs qui changent quelque chose sur la page. Cette carte est relevée par une sonde qui modifie chaque champ par l’API et compare le HTML public. Un champ absent de la carte est caché dans l’écran du bloc.

La sonde ne pouvait pas voir la photo, puisque aucun composant ne la lisait encore. La carte reçoit donc le sous-champ à la main pour le bloc qui l’emploie désormais, avec un commentaire qui le dit :

// Ajoute a la main le 13 novembre 2026 (socle 3.38.0) : "arguments.image" pour
// "promesses", dont chaque carte lit desormais sa photo (Benefits.astro).

et, dans la liste des champs du bloc promesses, "arguments.image" avec le libellé "Photo (vide : celle du thème)". Le libellé dit à l’éditeur ce que fait un champ vide.

Si votre thème montre tous les champs d’une collection, cette partie ne vous concerne pas. S’il les filtre, comme le nôtre, c’est l’étape facile à oublier : le schéma est juste, le composant aussi, et l’éditeur ne voit toujours rien.

Partie 3 : la lire dans le composant, avec un repli

Deux petites fonctions du socle. La première rend la ligne d’un rang donné dans les arguments d’une section :

export function argumentDe(page: Page, slug: string, rang: number): Record<string, unknown> {
  const lignes = donneesDe(page, slug).arguments;
  return Array.isArray(lignes) ? ((lignes[rang] as Record<string, unknown> | undefined) ?? {}) : {};
}

La seconde rend la photo de cet élément, ou null :

export function photoDeLElement(page: Page, slug: string, rang: number): Media | null {
  const photo = media(argumentDe(page, slug, rang).image);
  return photo?.src ? photo : null;
}

media() ramène ce que la médiathèque range à une valeur qui a un src exploitable. Une valeur vide, ou d’une autre forme, donne null. Cette règle compte : tout ce qui n’est pas un vrai fichier retombe sur le thème.

Dans le composant, Benefits.astro, chaque carte reçoit les deux photos :

photo: photos[index % photos.length],
// La photo choisie dans le back office pour cette carte, ou null : celle du depot.
photoChoisie: photoDeLElement(Astro, "promesses", index),

et le gabarit choisit :

{benefit.photoChoisie ? (
  <PhotoDuMoteur
    media={benefit.photoChoisie}
    class="absolute inset-0 size-full object-cover"
    widths={[480, 720, 1000, 1600]}
    sizes={index === 0 ? "(min-width: 64rem) 60vw, 100vw" : "(min-width: 64rem) 30vw, 100vw"}
  />
) : (
  <PhotoDuTheme photo={benefit.photo} alt="" ... />
)}

(raccourci : les props de PhotoDuTheme sont omises.)

PhotoDuMoteur rend une image de la médiathèque comme le thème rend les siennes : plusieurs largeurs par astro:assets, du WebP, le point focal quand la médiathèque en a un, et la même classe que la photo remplacée. La grande carte demande des images plus larges que les deux petites, d’où sizes qui dépend du rang.

Champ vide, le composant rend la photo du dépôt, et le HTML est identique, octet pour octet, à celui d’avant. C’est la propriété à garder : livrer la fonction ne change rien pour un site qui ne s’en sert pas.

Ce qu’il faut vérifier

Avant de dire que c’est fini :

  • passer le script du schéma en mode vérification sur chaque base : aucun champ manquant ;
  • le repasser en mode écriture : il doit dire qu’il n’a rien à faire ;
  • dans le back office, ouvrir le bloc, poser une photo sur un élément, publier, recharger la page publique ;
  • vider le champ et comparer le HTML à une copie prise avant : identique ;
  • regarder la page en visiteur, sans session, pour ne pas lire un aperçu d’édition.

Pourquoi trois parties et pas une

Chaque partie échoue en silence quand elle est seule. Un schéma sans le composant range des photos que personne ne voit. Un composant sans le schéma lit null pour toujours. Les deux sans la carte des champs laissent l’éditeur sans case à remplir. Écrire les trois comme un seul changement, avec la règle du repli dans chacune, c’est ce qui permet de le livrer à tous les sites d’un coup.

C’est dans la 6.5.0 des sept thèmes (notes de version). Les trois cartes photo se voient sur la démo Aloha, et la page d’Aloha dit ce que contient le thème. Ce que voit ensuite l’éditeur, expliqué pour un client, est sur le site de l’agence : modifier son site avec EmDash.

À lire aussi

Tous les articles