Menu

English,

Templates

Tutorial: make the photo of each card of a section editable in EmDash

From the code of a real theme: add an image sub-field to a repeater, migrate live databases safely, and render the editor photo with the theme photo as fallback.

The west coast of Oahu from the air: a golden beach, the lagoon and the mountain at sunset.

Aloha Pixel6 min read

The home page of our Aloha theme has three promise cards, each with its own photograph. Until 13 November 2026, an editor could change their titles and texts from the EmDash back office, but not their photos. The fix shipped in our core 3.38.0. It is a small change with three parts, and each part is a mistake you can make on your own theme:

  1. the database schema must have a field for the photo;
  2. the back office screen must show that field;
  3. the component must read it, and keep the theme photo when it is empty.

All the code below is from the theme and its core, shortened only where marked.

The starting point

In our themes, the blocks of a page live in a collection called sections. A block made of repeated items (promises, steps, testimonials, logos) keeps its items in one repeater field, arguments. Each item already has sub-fields: title, text, icon, link, anchor.

The photo belongs there, next to the title of the same item. Not in a new collection: the editor changes a card in one place.

In the database, a repeater is a JSON column on the content side, and its list of sub-fields is described in the field definition: the validation column of _emdash_fields, under the key subFields. Adding a sub-field adds no column. Only that description changes.

Part 1: the schema, for new and existing sites

New sites get the sub-field from the seed. But a seed is applied once, to an empty database, during setup; the EmDash documentation is explicit that it is not a migration system. Every site installed before the change needs the sub-field added to its live database.

We define the sub-field once, with the same slug, label and type as the seeds that already have it:

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

Then a function writes the SQL that adds it. The important part is the guard. The update only touches a field that is a repeater of the named collection, whose description holds a list of sub-fields, and where no sub-field is already called 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)})`;

The write appends the sub-field with json_insert(validation, '$.subFields[#]', ...) under those conditions. Run twice, the second run touches no row. That is what lets us run it on every site without first checking by hand which ones need it.

A second statement, under the same guard, moves the updated_at of the collection forward. Our front Worker reads the schema with the content version, so this makes cached pages render fresh.

A script wraps it with three modes: --verifier writes nothing and exits with code 1 if a photo field is missing, --essai prints the SQL without running it, and the default reads the state, applies the guarded SQL, then reads again. We take a D1 Time Travel bookmark before running it on a production database. On 13 November 2026 it found the sub-field missing on two of our demo databases and added it; no content was touched.

The rules live in a module that imports neither Astro nor EmDash. Its self-check runs 28 controls, including the migration played twice on a real SQLite database.

Part 2: show the field in the block screen

Our back office shows, for each block, only the fields that change something on the page. That map is generated by a probe that changes each field through the API and compares the public HTML. A field missing from the map is hidden in the block screen.

The probe could not see the photo, since no component read it yet. So the map gets the sub-field by hand for the block that now uses it, with a comment saying so:

// 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).

and in the list of fields of the promesses block, "arguments.image" with the label "Photo (vide : celle du thème)". The label tells the editor what an empty field does.

If your theme shows all fields of a collection, you skip this part. If it filters them, as ours does, this is the step that is easy to forget: the schema is right, the component is right, and the editor still sees nothing.

Part 3: read it in the component, with a fallback

Two small helpers in the core. The first returns the row of a given rank in the arguments of a 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) ?? {}) : {};
}

The second returns the photo of that item, or 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() normalises what the media library stores into something with a usable src. A value that is empty, or of another shape, gives null. That rule matters: anything that is not a real file falls back to the theme.

In the component, Benefits.astro, each card gets both 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),

and the template picks one:

{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="" ... />
)}

(shortened: the props of PhotoDuTheme are elided.)

PhotoDuMoteur renders a media library image the way the theme renders its own: several widths through astro:assets, WebP, the focal point when the library has one, and the same class as the photo it replaces. The large card asks for wider images than the two small ones, which is why sizes depends on the rank.

With the field empty, the component renders the repository photo, and the HTML is byte for byte what it was before. That is the property to keep: shipping the feature changes nothing for a site that does not use it.

What to check

Before you call it done:

  • run the schema script in verification mode on every database: no missing field;
  • run it again in write mode: it must report nothing to do;
  • in the back office, open the block, set a photo on one item, publish, reload the public page;
  • empty the field again and compare the HTML with a copy taken before: identical;
  • check the page as a visitor, without a session, so you are not looking at an edit preview.

Why three parts and not one

Each part fails silently on its own. A schema without the component stores photos nobody sees. A component without the schema reads null forever. Both without the field map leave the editor with no input. Writing the three as one change, with the fallback rule stated in each, is what makes it safe to ship to every site at once.

This is in the 6.5.0 release of all seven themes (release notes). You can see the three photo cards on the Aloha demo, and the Aloha page lists what the theme includes. What the editor then sees, explained for a client, is on our agency site: editing your site with EmDash.

Keep reading

All articles