Chapitre 8.2 — Tutoriel : créer theme_maboite, enfant de Boost, de A à Z

public/theme/maboite/
├── version.php
├── config.php
├── lib.php
├── settings.php
├── scss/
│   ├── preset/
│   │   └── default.scss
│   ├── pre.scss
│   └── post.scss
├── pix/
│   ├── logo.svg
│   ├── logo-compact.svg
│   └── favicon.ico
├── fonts/
│   ├── Inter-Regular.woff2
│   ├── Inter-Medium.woff2
│   └── Inter-Bold.woff2
└── lang/
    └── en/
        └── theme_maboite.php

<?php
// public/theme/maboite/version.php
defined('MOODLE_INTERNAL') || die();
 
$plugin->component = 'theme_maboite';
$plugin->version   = 2026070800;
$plugin->requires  = 2026042000;      // Moodle 5.2
$plugin->maturity  = MATURITY_STABLE;
$plugin->release   = 'v1.0';
$plugin->dependencies = [
    'theme_boost' => 2026042000,      // on dépend du thème parent
];

<?php
// public/theme/maboite/config.php
defined('MOODLE_INTERNAL') || die();
 
$THEME->name = 'maboite';
 
// Héritage de Boost : on récupère tout (layouts, templates, renderers, SCSS).
$THEME->parents = ['boost'];
 
$THEME->sheets = [];              // pas de CSS statique : tout en SCSS
$THEME->editor_sheets = [];
 
// SCSS principal : callback qui assemble preset + Boost (lib.php).
$THEME->scss = function($theme) {
    return theme_maboite_get_main_scss_content($theme);
};
 
// Étages pre et extra du pipeline (ch. 8.1 §5).
$THEME->prescsscallback   = 'theme_maboite_get_pre_scss';
$THEME->extrascsscallback = 'theme_maboite_get_extra_scss';
 
// Réglages hérités de Boost.
$THEME->layouts = [];             // hérite des layouts de Boost
$THEME->requiredblocks = '';
$THEME->addblockposition = BLOCK_ADDBLOCK_POSITION_FLATNAV;
 
// Surcharge des renderers (ch. 8.3).
$THEME->rendererfactory = 'theme_overridden_renderer_factory';
 
$THEME->iconsystem = \core\output\icon_system::FONTAWESOME;
$THEME->haseditswitch = true;
$THEME->usefallback = true;
 
// Autorise le dark mode fourni par Boost.
$THEME->enable_dock = false;

<?php
// public/theme/maboite/lib.php
defined('MOODLE_INTERNAL') || die();
 
/**
 * SCSS principal : le preset choisi + le SCSS de Boost.
 *
 * @param theme_config $theme
 * @return string
 */
function theme_maboite_get_main_scss_content($theme): string {
    global $CFG;
 
    $scss = '';
    $filename = !empty($theme->settings->preset) ? $theme->settings->preset : 'default.scss';
    $presetfile = "{$CFG->dirroot}/theme/maboite/scss/preset/{$filename}";
 
    // On repart du SCSS de Boost (variables + Bootstrap + composants Moodle).
    $boost = "{$CFG->dirroot}/theme/boost/scss/";
    $scss .= file_get_contents("{$boost}/preset/default.scss"); // base Boost
 
    // Puis notre preset (surcharges de haut niveau).
    if (is_readable($presetfile)) {
        $scss .= "\n" . file_get_contents($presetfile);
    }
 
    return $scss;
}
 
/**
 * Pre-SCSS : VARIABLES injectées AVANT le preset (surcharge Bootstrap).
 * C'est ici qu'on branche la couleur de marque sur $primary.
 *
 * @param theme_config $theme
 * @return string
 */
function theme_maboite_get_pre_scss($theme): string {
    $scss = '';
 
    // Couleur de marque (réglage admin) → variable Bootstrap $primary.
    $brand = get_config('theme_maboite', 'brandcolor');
    if (!empty($brand)) {
        $scss .= '$primary: ' . $brand . ";\n";
    }
 
    // Fonte de marque.
    $scss .= '$font-family-sans-serif: "Inter", system-ui, -apple-system, sans-serif;' . "\n";
    $scss .= '$border-radius: 0.5rem;' . "\n";
 
    // Boîte « SCSS brut avant » laissée à l'admin (rawscsspre).
    $rawpre = get_config('theme_maboite', 'scsspre');
    if (!empty($rawpre)) {
        $scss .= "\n" . $rawpre;
    }
 
    return $scss;
}
 
/**
 * Extra-SCSS : RÈGLES injectées APRÈS le preset (surcharges finales).
 *
 * @param theme_config $theme
 * @return string
 */
function theme_maboite_get_extra_scss($theme): string {
    // @font-face pour héberger Inter localement + règles maison.
    $fontface = theme_maboite_get_fontface_scss();
 
    $extra = $fontface . "\n" . file_get_contents(
        $GLOBALS['CFG']->dirroot . '/theme/maboite/scss/post.scss'
    );
 
    // Boîte « SCSS brut après » laissée à l'admin (rawscss).
    $rawpost = get_config('theme_maboite', 'scss');
    if (!empty($rawpost)) {
        $extra .= "\n" . $rawpost;
    }
 
    return $extra;
}
 
/**
 * Génère les @font-face pointant vers les woff2 hébergés dans le thème.
 */
function theme_maboite_get_fontface_scss(): string {
    global $CFG;
    $base = "{$CFG->wwwroot}/theme/maboite/fonts";
    return "
@font-face {
    font-family: 'Inter';
    src: url('{$base}/Inter-Regular.woff2') format('woff2');
    font-weight: 400; font-style: normal; font-display: swap;
}
@font-face {
    font-family: 'Inter';
    src: url('{$base}/Inter-Medium.woff2') format('woff2');
    font-weight: 500; font-style: normal; font-display: swap;
}
@font-face {
    font-family: 'Inter';
    src: url('{$base}/Inter-Bold.woff2') format('woff2');
    font-weight: 700; font-style: normal; font-display: swap;
}
";
}

// public/theme/maboite/scss/preset/default.scss
// Ajustements structurels qui ne sont pas de simples variables.
// (Le gros vient de Boost, chargé avant dans lib.php.)
 
.navbar {
    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
}

// public/theme/maboite/scss/post.scss
 
// Le logo dans la barre de navigation.
.navbar-brand img {
    max-height: 36px;
    width: auto;
}
 
// Footer aux couleurs de marque.
#page-footer {
    background: $primary;   // $primary est disponible ici (compilé après Bootstrap)
    color: #fff;
 
    a { color: rgba(255, 255, 255, 0.85); }
    a:hover { color: #fff; }
}
 
// Page de connexion : carte centrée, fond de marque.
body.pagelayout-login {
    background: linear-gradient(135deg, $primary 0%, darken($primary, 15%) 100%);
 
    .card {
        border: none;
        border-radius: 1rem;
        box-shadow: 0 10px 40px rgba(0, 0, 0, 0.2);
    }
}

// public/theme/maboite/scss/pre.scss
// Variables statiques supplémentaires (non issues des réglages).
$enable-rounded: true;
$link-decoration: none;

<?php
// public/theme/maboite/settings.php
defined('MOODLE_INTERNAL') || die();
 
if ($ADMIN->fulltree) {
    $settings = new theme_boost_admin_settingspage_tabs(
        'themesettingmaboite',
        get_string('configtitle', 'theme_maboite')
    );
 
    // --- Onglet « Général » ---
    $page = new admin_settingpage('theme_maboite_general', get_string('generalsettings', 'theme_maboite'));
 
    // 1. Preset picker : choisir le fichier de preset.
    $name = 'theme_maboite/preset';
    $title = get_string('preset', 'theme_maboite');
    $description = get_string('preset_desc', 'theme_maboite');
    $default = 'default.scss';
    $choices = ['default.scss' => 'Default', 'dark.scss' => 'Dark'];
    $setting = new admin_setting_configselect($name, $title, $description, $default, $choices);
    $setting->set_updatedcallback('theme_reset_all_caches'); // recompile au changement
    $page->add($setting);
 
    // 2. Couleur de marque → $primary.
    $name = 'theme_maboite/brandcolor';
    $title = get_string('brandcolor', 'theme_maboite');
    $description = get_string('brandcolor_desc', 'theme_maboite');
    $setting = new admin_setting_configcolourpicker($name, $title, $description, '#5940c1');
    $setting->set_updatedcallback('theme_reset_all_caches');
    $page->add($setting);
 
    // 3. Logo.
    $name = 'theme_maboite/logo';
    $title = get_string('logo', 'theme_maboite');
    $description = get_string('logo_desc', 'theme_maboite');
    $setting = new admin_setting_configstoredfile($name, $title, $description, 'logo',
        0, ['maxfiles' => 1, 'accepted_types' => ['.png', '.svg', '.jpg']]);
    $setting->set_updatedcallback('theme_reset_all_caches');
    $page->add($setting);
 
    $settings->add($page);
 
    // --- Onglet « SCSS avancé » ---
    $page = new admin_settingpage('theme_maboite_scss', get_string('advancedsettings', 'theme_maboite'));
 
    // 4. SCSS brut AVANT (variables).
    $setting = new admin_setting_scsscode('theme_maboite/scsspre',
        get_string('rawscsspre', 'theme_maboite'),
        get_string('rawscsspre_desc', 'theme_maboite'), '', PARAM_RAW);
    $setting->set_updatedcallback('theme_reset_all_caches');
    $page->add($setting);
 
    // 5. SCSS brut APRÈS (règles).
    $setting = new admin_setting_scsscode('theme_maboite/scss',
        get_string('rawscss', 'theme_maboite'),
        get_string('rawscss_desc', 'theme_maboite'), '', PARAM_RAW);
    $setting->set_updatedcallback('theme_reset_all_caches');
    $page->add($setting);
 
    $settings->add($page);
}

<?php
// public/theme/maboite/lang/en/theme_maboite.php
defined('MOODLE_INTERNAL') || die();
 
$string['pluginname']        = 'MaBoîte';
$string['choosereadme']      = 'MaBoîte is a child theme of Boost with brand colours and Inter font.';
$string['configtitle']       = 'MaBoîte settings';
$string['generalsettings']   = 'General';
$string['advancedsettings']  = 'Advanced';
$string['preset']            = 'Theme preset';
$string['preset_desc']       = 'Pick a preset to broadly change the look.';
$string['brandcolor']        = 'Brand colour';
$string['brandcolor_desc']   = 'The primary colour of the site.';
$string['logo']              = 'Logo';
$string['logo_desc']         = 'Logo shown in the navigation bar.';
$string['rawscsspre']        = 'Raw initial SCSS';
$string['rawscsspre_desc']   = 'SCSS injected before everything (variables).';
$string['rawscss']           = 'Raw SCSS';
$string['rawscss_desc']      = 'SCSS injected at the end (rules).';
$string['region-side-pre']   = 'Right';

# 1. Déposer le thème
git clone <repo> public/theme/maboite   # ou copier les fichiers
 
# 2. Installer (détecte le nouveau plugin)
php admin/cli/upgrade.php --non-interactive
 
# 3. Activer le thème : Apparence → Sélecteur de thèmes → « MaBoîte »
#    (ou en CLI :)
php admin/cli/cfg.php --name=theme --set=maboite
 
# 4. Mode dev pour itérer sur le SCSS
#    Apparence → Réglages des thèmes → Activer themedesignermode
#    (ou $CFG->themedesignermode = true; dans config.php)
 
# 5. À chaque changement SCSS, purger si designer mode OFF
php admin/cli/purge_caches.php