Customize the theme templates

The theme templates decide the HTML of every public page: header, menus, post, lists, product page. Editing them opens up everything custom CSS can't do, at the cost of maintenance on every update. This lesson details the files in app/theme, the variables they receive, the security constraints and this academy's own example.

Custom CSS or theme templates?

Always start with the lightest solution. Custom CSS covers the vast majority of tweaks, and <body> carries classes that let you target a context without touching PHP: theme-<name>, hdr-center, cards-list, then is-post, is-page, is-wide, is-list, is-shop, is-product, is-search or is-404 depending on the page.

The files in app/theme

The CSS variables in theme.css (--bg, --bg-soft, --card, --text, --muted, --line, --radius, --shadow, --text-w, --wide-w) and those computed from the settings (--accent, --on-accent, --link, --font, --font-head) remain your best handle: use them in your templates to follow the theme, dark mode and the chosen color.

How does a template receive its data?

Theme::render($view, $v) first runs the view's template (single, list…), puts its HTML in $v['content'], then runs layout.php with the same array. The skeleton therefore sees all the page's variables: $v['item'] or $v['translations'] are available in a post's header. For a page in French, Theme::typography() finally adds the non-breaking spaces.

Theme::partial($name, $v) includes app/theme/<name>.php in an isolated function, where only $v is visible. This lets you split your theme into small files (Theme::partial('lang-switch', $v)), knowing that each new file will show up among the integrity check's “Unknown files”.

Example: show a post's translations in the header, based on the links created in the editor.

<?php // layout.php, inside <header> (add "use Eclair\Content;" at the top of the file) ?>
<?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 ?>

The style for .lang-switch goes in custom CSS or in theme.css, never in a style attribute.

CSP constraints

Public pages are served with a strict Content-Security-Policy, computed by Security::headers(). It applies to your templates like everything else:

• Scripts: script-src 'self'. No inline <script>, no onclick attribute, no javascript: link. A .js file served by your domain is still allowed.
• Styles: style-src 'self' plus the sha256 hash of Éclair's CSS. The only accepted <style> tag is the one in layout.php, filled by Theme::css(). A second <style> block or a style="" attribute is blocked.
• Fonts and resources: default-src 'self'. A font loaded from a third-party service is refused: host it on your domain, as art directions do in media/fonts/.
• Frames: only the youtube-nocookie.com and player.vimeo.com players are allowed.

Template performance

For a cached page, a template only runs on the first display; after that, the static cache serves the page. That's no reason to make it heavier. Read lists from the index (Content::index(), Content::published()) rather than opening each piece of content, keep Media::picture() for images (dimensions, WebP srcset, lazy loading) and prefer native HTML elements, <details> or the popover attribute, to JavaScript. Every KB added to theme.css is sent with every page, since the CSS is inlined in the HTML.

Also keep the Blocks::ea() calls in single.php (data-ef attributes): they only appear in the admin preview and let Visual mode edit the title, the featured image and “Key takeaways” in place.

Updates, integrity and manifest.php

The update procedure deletes app/, then replaces it: your theme templates disappear with it. Get organized from day one.

1. Keep your modified templates in a Git repository, outside the live site.
2. After each update, compare the original templates of the old and new versions, to spot a new variable or a fix.
3. Carry those changes over to your files, test locally, then upload them again.
4. Run Security › File integrity › Scan now: only your files should appear among the modified or unknown ones.

# What changed in the original templates between two versions
diff -ru eclair-1.7.0/eclair/app/theme eclair-1.8.0/eclair/app/theme

The integrity check compares each file with its fingerprint in app/manifest.php. A list that matches your changes is normal; an unexpected file deserves an investigation. For a fleet of sites, a sturdier option is to maintain your own copy of the repository and produce your archive with php tools/build.php: its manifest carries your templates' fingerprints, and the check stays clean. The public rendering tests in tests/run.php will then flag your changes. That's expected, since they compare against the original rendering.

This academy's example

Éclair Academy is built with Éclair 1.8 and customized theme templates. The standard theme shares the same menus across all languages; our templates add four behaviors while respecting the constraints described above (no inline script, no style attribute, rendering cached as usual).

• Menus filtered by language: a single main menu holds the links for all three languages; Academy::menu() only keeps those whose URL belongs to the page's language (French at the root, /en/… and /es/…). An emoji at the start of a label, as in “🧭 Paths”, becomes a line-drawn icon in the mobile menu.
• Language switcher: it relies on the translations linked in the editor ($v['translations']) and leads to the same page in the other language, or to that language's home page if the page isn't translated.
• Full-screen mobile menu without JavaScript: a popovertarget="site-menu" button opens <nav id="site-menu" popover>, which the browser handles on its own (Escape key, click outside). On large screens, the CSS puts the menu back in the header.
• Automatic lesson navigation: Academy::stations() reads the first numbered list on the path's page. The order of its links gives each lesson's number, the line map and the “Previous lesson” and “Next lesson” links. To reorder a path, you simply edit that list in the editor.

The core of the filtering takes just a few lines:

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

/** Menu items in the page's language; external links show everywhere. */
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;
}

To keep the Security page green, the academy's build script recalculates the fingerprint of these six files in app/manifest.php (the first 32 characters of their SHA-256, like the original manifest). After an Éclair update, you just copy these files again from the academy's archive, then clear the cache.

Key points

• Try custom CSS first: it's stored in data/ and survives updates.
• The theme templates receive everything in $v, and layout.php sees the same variables as the view.
• Escape every value with e() and build URLs with path_to().
• The CSP forbids inline scripts and styles: CSS goes in the theme's stylesheets, behavior in native HTML.
• A modified template is replaced on every update: keep it under version control and compare it with each new version.

Going further

• Custom CSS: everything you can do without touching PHP.
• Build a multilingual site: the linked translations the language switcher relies on.
• Performance: staying at 100 out of 100: measure the effect of your templates.
• Advanced security and maintenance: the update procedure and the integrity check.
• MDN: the Popover API, for a menu without JavaScript.
• OWASP: Content Security Policy Cheat Sheet.

All the lessons of this path