Charger le CSS d'un module PrestaShop : hooks, chemins et bonnes pratiques

Pourquoi le CSS de mon module PrestaShop ne se charge pas ?

C'est l'un des problèmes les plus fréquents rencontrés par les développeurs de modules PrestaShop : le CSS est bien présent dans le dossier du module, le code semble correct, mais les styles ne s'appliquent tout simplement pas en front-office.

Dans 90 % des cas, l'origine du problème se situe à l'un de ces trois niveaux :

1. **Le hook `displayHeader` n'est pas enregistré** lors de l'installation du module
2. **Le chemin du fichier CSS est incorrect** ou entre en conflit avec une surcharge du thème
3. **Un problème de permissions** empêche la lecture du fichier

Voyons comment diagnostiquer et résoudre chacun de ces cas.

Étape 1 : Enregistrer le hook header à l'installation

Le hook displayHeader (ou header en version courte) est le point d'injection qui permet à PrestaShop d'inclure vos fichiers CSS et JavaScript dans le de la page. Si ce hook n'est pas enregistré lors de l'installation du module, vos assets ne seront jamais chargés.

Voici la méthode install() correcte :

public function install()
{
    if (Shop::isFeatureActive()) {
        Shop::setContext(Shop::CONTEXT_ALL);
    }

    return parent::install()
        && $this->registerHook('displayHeader')
        && $this->registerHook('displayHome')
        && Configuration::updateValue('MON_MODULE_CONFIG', 'valeur_defaut');
}

Points importants

• **`Shop::setContext(Shop::CONTEXT_ALL)`** garantit que le module s'installe sur toutes les boutiques en mode multiboutique. Sans cette ligne, le hook ne sera enregistré que pour la boutique active.
• Utilisez les noms de hooks complets (`displayHeader` plutôt que `header`) pour plus de clarté, bien que PrestaShop accepte les deux.
• L'opérateur `&&` chaîne les conditions : si l'une échoue, l'installation est annulée proprement.

Astuce : Si votre module est déjà installé sans le hook, vous pouvez l'ajouter sans réinstaller via le back-office : Modules → votre module → Configurer → onglet "Hooks" (ou via la page Apparence → Positions).

Étape 2 : Déclarer le CSS dans hookDisplayHeader

Une fois le hook enregistré, il faut implémenter la méthode correspondante pour injecter vos fichiers CSS :

public function hookDisplayHeader($params)
{
    $this->context->controller->addCSS($this->_path . 'views/css/monmodule.css');
}

Charger le CSS uniquement sur certaines pages

Il est souvent inutile (et contre-performant) de charger le CSS d'un module sur toutes les pages. Voici comment restreindre le chargement à des pages spécifiques :

public function hookDisplayHeader($params)
{
    $controller = Dispatcher::getInstance()->getController();

    // Charger uniquement sur la page d'accueil
    if ($controller === 'index') {
        $this->context->controller->addCSS($this->_path . 'views/css/monmodule.css');
        $this->context->controller->addJS($this->_path . 'views/js/monmodule.js');
    }
}

Les noms de contrôleurs courants :

PageNom du contrôleur Accueil`index` Produit`product` Catégorie`category` Panier`cart` Commande`order` CMS`cms`

Version PrestaShop 8.x

Sur PrestaShop 8.x, la méthode reste identique mais la structure de dossiers recommandée a évolué. Placez vos assets dans views/css/ et views/js/ :

public function hookDisplayHeader($params)
{
    $this->context->controller->registerStylesheet(
        'monmodule-style',
        'modules/' . $this->name . '/views/css/monmodule.css',
        ['media' => 'all', 'priority' => 150]
    );
}

La méthode registerStylesheet() offre un contrôle plus fin sur la priorité de chargement et le type de média. Elle est disponible depuis PrestaShop 1.7 et reste la méthode recommandée sur la version 8.x. La méthode addCSS() fonctionne toujours mais est considérée comme un raccourci legacy.

Étape 3 : Vérifier l'arborescence et les chemins

Un piège classique : PrestaShop permet aux thèmes de surcharger les fichiers CSS d'un module. Si un dossier portant le nom de votre module existe dans le thème, PrestaShop chargera le CSS depuis le thème plutôt que depuis le module.

Le mécanisme de surcharge CSS

PrestaShop cherche les fichiers dans cet ordre :

1. `themes/votre-theme/modules/monmodule/views/css/monmodule.css`
2. `modules/monmodule/views/css/monmodule.css`

Si le fichier existe dans le thème (même vide ou obsolète), c'est celui-là qui sera utilisé.

Solution

Si votre CSS ne s'affiche pas correctement :

1. Vérifiez s'il existe un dossier `themes/votre-theme/modules/monmodule/`
2. Si oui, **supprimez-le ou renommez-le** pour forcer le chargement depuis le module
3. Videz le cache PrestaShop (Paramètres avancés → Performances → Vider le cache)
4. Réinstallez le module si nécessaire

L'arborescence idéale pour un module autonome :

modules/monmodule/
├── monmodule.php
├── views/
│   ├── css/
│   │   └── monmodule.css
│   ├── js/
│   │   └── monmodule.js
│   └── templates/
│       └── hook/
│           └── displayHome.tpl
└── config.xml

Étape 4 : Vérifier les permissions fichiers

Sur un serveur Linux, des permissions incorrectes peuvent empêcher Apache/Nginx de lire vos fichiers CSS :

# Vérifier les permissions actuelles
ls -la modules/monmodule/views/css/

# Corriger les permissions si nécessaire
chmod 755 modules/monmodule/views/css/
chmod 644 modules/monmodule/views/css/monmodule.css

Les dossiers doivent être en 755 et les fichiers en 644. Évitez le 777 qui pose des problèmes de sécurité.

Diagnostic rapide : checklist de dépannage

Si votre CSS ne se charge toujours pas, parcourez cette liste dans l'ordre :

• [ ] Le hook `displayHeader` est-il enregistré ? (vérifier dans Apparence → Positions)
• [ ] La méthode `hookDisplayHeader()` existe-t-elle dans votre fichier module principal ?
• [ ] Le chemin passé à `addCSS()` est-il correct ? (`$this->_path` pointe vers `/modules/monmodule/`)
• [ ] Le fichier CSS existe-t-il physiquement à l'emplacement indiqué ?
• [ ] Y a-t-il une surcharge dans le dossier du thème ?
• [ ] Le cache PrestaShop est-il vidé ?
• [ ] La concaténation CSS (CCC) est-elle désactivée pendant le développement ?
• [ ] Les permissions fichiers sont-elles correctes ?
• [ ] Inspectez le code source HTML : le `` vers votre CSS apparaît-il dans le `` ?

Bonnes pratiques pour les assets de modules

1. **Préfixez vos classes CSS** avec le nom du module pour éviter les conflits (`.monmodule-slider`, `.monmodule-wrapper`)
2. **Ne chargez jamais de CSS globalement** si votre module n'intervient que sur certaines pages
3. **Utilisez `registerStylesheet()`** sur PrestaShop 1.7+ pour un meilleur contrôle
4. **Minifiez vos fichiers** en production
5. **Testez avec le cache désactivé** pendant le développement, puis activé avant la mise en production