Personnaliser les gabarits du thème

Les gabarits du thème décident du HTML de chaque page publique : en-tête, menus, article, listes, fiche produit. Les modifier ouvre tout ce que le CSS personnalisé ne permet pas, au prix d'une maintenance à chaque mise à jour. Cette leçon détaille les fichiers d'app/theme, les variables reçues, les contraintes de sécurité et l'exemple de cette académie.

CSS personnalisé ou gabarits du thème ?

Commence toujours par la solution la plus légère. Le CSS personnalisé couvre la grande majorité des retouches, et le <body> porte des classes qui permettent de cibler un contexte sans toucher au PHP : theme-<nom>, hdr-center, cards-list, puis is-post, is-page, is-wide, is-list, is-shop, is-product, is-search ou is-404 selon la page.

Les fichiers d'app/theme

Les variables CSS de theme.css (--bg, --bg-soft, --card, --text, --muted, --line, --radius, --shadow, --text-w, --wide-w) et celles calculées depuis les réglages (--accent, --on-accent, --link, --font, --font-head) restent ta meilleure prise : utilise-les dans tes gabarits pour suivre le thème, le mode sombre et la couleur choisie.

Comment un gabarit reçoit ses données ?

Theme::render($vue, $v) exécute d'abord le gabarit de la vue (single, list…), place son HTML dans $v['content'], puis exécute layout.php avec le même tableau. Le squelette voit donc toutes les variables de la page : $v['item'] ou $v['translations'] sont disponibles dans l'en-tête d'un article. Pour une page en français, Theme::typography() ajoute enfin les espaces insécables.

Theme::partial($nom, $v) inclut app/theme/<nom>.php dans une fonction isolée : seul $v y est visible. Tu peux ainsi découper ton thème en petits fichiers (Theme::partial('lang-switch', $v)), en sachant que chaque nouveau fichier apparaîtra parmi les « fichiers inconnus » du contrôle d'intégrité.

Exemple : afficher les traductions d'un article dans l'en-tête, à partir des liens créés dans l'éditeur.

<?php // layout.php, dans <header> (ajoute « use Eclair\Content; » en tête du fichier) ?>
<?php if (!empty($v['translations'])): ?>
  <nav class="lang-switch" aria-label="<?= e(Theme::t('read_in', $lang)) ?>">
    <?php foreach ($v['translations'] as $code => $t): ?>
      <a href="<?= e(path_to(Content::path($t))) ?>" hreflang="<?= e($code) ?>" lang="<?= e($code) ?>"<?= $t['id'] === ($v['id'] ?? '') ? ' aria-current="true"' : '' ?>><?= e(strtoupper($code)) ?></a>
    <?php endforeach ?>
  </nav>
<?php endif ?>

Le style de .lang-switch va dans le CSS personnalisé ou dans theme.css, jamais dans un attribut style.

Les contraintes de la CSP

Les pages publiques sont servies avec une Content-Security-Policy stricte, calculée par Security::headers(). Elle s'applique à tes gabarits comme au reste :

• Scripts : script-src 'self'. Aucun <script> en ligne, aucun attribut onclick, aucun lien javascript:. Un fichier .js servi par ton domaine reste permis.
• Styles : style-src 'self' plus l'empreinte sha256 du CSS d'Éclair. La seule balise <style> acceptée est celle de layout.php, remplie par Theme::css(). Un second bloc <style> ou un attribut style="" sont bloqués.
• Polices et ressources : default-src 'self'. Une police chargée depuis un service tiers est refusée : héberge-la sur ton domaine, comme les directions artistiques le font dans media/fonts/.
• Cadres : seuls les lecteurs youtube-nocookie.com et player.vimeo.com sont autorisés.

Performance des gabarits

Pour une page mise en cache, un gabarit ne s'exécute qu'au premier affichage : la suite est servie par le cache statique. Ce n'est pas une raison pour l'alourdir. Lis les listes dans l'index (Content::index(), Content::published()) plutôt que d'ouvrir chaque contenu, garde Media::picture() pour les images (dimensions, srcset WebP, chargement différé) et préfère les éléments HTML natifs, <details> ou l'attribut popover, à du JavaScript. Chaque Ko ajouté à theme.css est envoyé avec chaque page, puisque le CSS est inséré dans le HTML.

Garde aussi les appels Blocks::ea() de single.php (attributs data-ef) : ils n'apparaissent que dans l'aperçu de l'administration et permettent au mode Visuel de modifier sur place le titre, l'image à la une et « L'essentiel ».

Mises à jour, intégrité et manifest.php

La procédure de mise à jour supprime app/ puis le remplace : tes gabarits disparaissent avec lui. Organise-toi dès le premier jour.

1. Range tes gabarits modifiés dans un dépôt Git, hors du site en ligne.
2. Après chaque mise à jour, compare les gabarits d'origine de l'ancienne et de la nouvelle version, pour repérer une variable ajoutée ou un correctif.
3. Reporte ces changements dans tes fichiers, teste en local, puis renvoie-les.
4. Lance Sécurité › Intégrité des fichiers › Analyser maintenant : seuls tes fichiers doivent apparaître parmi les modifiés ou les inconnus.

# Ce qui a changé dans les gabarits d'origine entre deux versions
diff -ru eclair-1.7.0/eclair/app/theme eclair-1.8.0/eclair/app/theme

Le contrôle d'intégrité compare chaque fichier à son empreinte dans app/manifest.php. Une liste conforme à tes modifications est normale ; un fichier inattendu mérite une enquête. Pour un parc de sites, une variante plus robuste consiste à entretenir ta propre copie du dépôt et à produire ton archive avec php tools/build.php : son manifeste porte les empreintes de tes gabarits, et le contrôle reste propre. Les tests de rendu public de tests/run.php signaleront alors tes changements : c'est attendu, ils comparent au rendu d'origine.

L'exemple de cette académie

Éclair Academy est construite avec Éclair 1.8 et des gabarits du thème personnalisés. Le thème standard partage les mêmes menus entre toutes les langues ; nos gabarits ajoutent quatre comportements, en respectant les contraintes décrites plus haut (aucun script en ligne, aucun attribut style, rendu mis en cache comme d'habitude).

• Menus filtrés par langue : un seul menu principal contient les liens des trois langues ; Academy::menu() ne garde que ceux dont l'adresse appartient à la langue de la page (le français à la racine, /en/… et /es/…). Un émoji en tête de libellé, comme « 🧭 Parcours », devient une icône dessinée dans le menu mobile.
• Sélecteur de langue : il s'appuie sur les traductions reliées dans l'éditeur ($v['translations']) et mène à la même page dans l'autre langue, ou à l'accueil de cette langue si la page n'est pas traduite.
• Menu mobile plein écran sans JavaScript : un bouton popovertarget="site-menu" ouvre <nav id="site-menu" popover>, que le navigateur gère seul (touche Échap, clic à l'extérieur). Sur grand écran, le CSS remet le menu dans l'en-tête.
• Navigation de leçon automatique : Academy::stations() lit la première liste numérotée de la page du parcours ; l'ordre de ses liens donne le numéro de chaque leçon, le plan de la ligne et les liens « Leçon précédente » et « Leçon suivante ». Pour réordonner un parcours, on modifie simplement cette liste dans l'éditeur.

Le cœur du filtrage tient en quelques lignes :

<?php
// app/theme/academy.php (extrait)
public static function langOf(string $path): string
{
    foreach (['en', 'es'] as $code) {
        if ($path === '/' . $code || str_starts_with($path, '/' . $code . '/')) {
            return $code;
        }
    }
    return 'fr';
}

/** Éléments d'un menu dans la langue de la page ; les liens externes s'affichent partout. */
public static function menu(array $items, string $lang): array
{
    $out = [];
    foreach ($items as $item) {
        $path = (string) ($item['path'] ?? '');
        if ($path !== '' && self::langOf($path) !== $lang) {
            continue;
        }
        [$icon, $label] = self::splitIcon((string) $item['label']);
        $out[] = $item + ['icon' => $icon, 'text' => $label];
    }
    return $out;
}

Pour que la page Sécurité reste au vert, le script de construction de l'académie recalcule l'empreinte de ces six fichiers dans app/manifest.php (les 32 premiers caractères de leur SHA-256, comme le manifeste d'origine). Après une mise à jour d'Éclair, il suffit de recopier ces fichiers depuis l'archive de l'académie, puis de vider le cache.

À retenir

• Essaie d'abord le CSS personnalisé : il est rangé dans data/ et survit aux mises à jour.
• Les gabarits du thème reçoivent tout dans $v, et layout.php voit les mêmes variables que la vue.
• Échappe chaque valeur avec e() et construis les adresses avec path_to().
• La CSP interdit scripts et styles en ligne : le CSS va dans les feuilles du thème, le comportement dans le HTML natif.
• Un gabarit modifié est remplacé à chaque mise à jour : versionne-le et compare-le aux nouvelles versions.

Pour aller plus loin

• Le CSS personnalisé : tout ce qu'on peut faire sans toucher au PHP.
• Créer un site multilingue : les traductions reliées sur lesquelles s'appuie le sélecteur de langue.
• Performance : garder 100 sur 100 : mesurer l'effet de tes gabarits.
• Sécurité avancée et maintenance : la procédure de mise à jour et le contrôle d'intégrité.
• MDN : l'API Popover, pour un menu sans JavaScript.
• OWASP : aide-mémoire sur la Content Security Policy.

Toutes les leçons du parcours