Thème enfant PrestaShop : résoudre les erreurs JavaScript après installation

Le problème classique : un thème enfant qui casse tout le front-office

Vous venez d'installer un thème enfant sur votre boutique PrestaShop et le résultat est catastrophique : le site est cassé, les sliders ne fonctionnent plus, les interactions sont figées. Ce scénario est bien plus fréquent qu'on ne le pense, et la cause est presque toujours la même : des bibliothèques JavaScript ne sont pas correctement héritées par le thème enfant.

Après plus de dix ans d'interventions sur des boutiques PrestaShop, je peux affirmer que 80 % des problèmes post-installation d'un thème enfant sont liés à des dépendances JS manquantes. Voyons comment diagnostiquer et résoudre ce problème méthodiquement.

Étape 1 : diagnostiquer avec la console JavaScript

La toute première chose à faire face à un thème enfant dysfonctionnel est d'ouvrir la console JavaScript de votre navigateur.

Accéder à la console

• **Chrome / Edge** : `F12` puis onglet "Console"
• **Firefox** : `F12` ou `Ctrl+Shift+K`
• **Safari** : `Cmd+Option+J` (après avoir activé le menu développeur)

Recherchez les erreurs en rouge. Vous verrez typiquement des messages comme :

Uncaught TypeError: $(...).flexisel is not a function
Uncaught ReferenceError: flexisel is not defined

Ce type d'erreur signifie qu'une bibliothèque JavaScript est appelée dans le code mais n'a jamais été chargée. En JavaScript, une seule erreur non interceptée peut bloquer l'exécution de tout le script, ce qui explique pourquoi le site entier semble cassé.

Étape 2 : vérifier les scripts chargés dans le code source

Ouvrez le code source de votre page (Ctrl+U dans la plupart des navigateurs) et recherchez les fichiers JavaScript critiques.

Vérifiez notamment la présence de :

• `theme.js` ou `custom.js` — le script principal du thème
• Les bibliothèques tierces utilisées par vos modules (jQuery plugins, sliders, etc.)
• `jquery.flexisel.js` ou tout autre plugin jQuery spécifique à votre thème

Si un fichier attendu est absent du code source, c'est la confirmation que le thème enfant ne charge pas correctement les assets du thème parent.

Étape 3 : comprendre pourquoi les scripts ne sont pas hérités

Dans PrestaShop 1.7 et 8.x, le mécanisme de thème enfant hérite des templates mais pas automatiquement de tous les assets JavaScript et CSS. Quand un module ou un thème parent enregistre ses scripts via la méthode setMedia(), le thème enfant peut ne pas hériter de ces déclarations si :

1. Le module surcharge `setMedia()` sans appeler `parent::setMedia()`
2. Les chemins des assets sont codés en dur avec le nom du thème parent
3. Le fichier `theme.yml` du thème enfant ne déclare pas correctement les assets parents

Le fichier theme.yml du thème enfant

En PrestaShop 1.7+, le theme.yml du thème enfant doit déclarer le thème parent :

parent: classic
name: mon-theme-enfant
display_name: Mon Thème Enfant
version: 1.0.0

assets:
  use_parent_assets: true

En PrestaShop 8.x, la propriété use_parent_assets est toujours supportée. Assurez-vous qu'elle est bien à true si vous souhaitez hériter des assets du parent.

Étape 4 : solution immédiate — désactiver le code fautif

Si votre site est en production et que vous devez le remettre en état rapidement, la solution d'urgence consiste à commenter l'appel à la bibliothèque manquante dans le fichier JavaScript principal du thème.

Par exemple, si l'erreur concerne flexisel, ouvrez le fichier assets/js/custom.js (ou scripts.js) de votre thème et commentez les lignes qui appellent cette bibliothèque :

// Solution temporaire : commenter l'initialisation de flexisel
// $("#mon-slider").flexisel({
//     visibleItems: 4,
//     animationSpeed: 200,
//     autoPlay: true
// });

Attention : c'est un correctif temporaire. Le slider ou le composant associé ne fonctionnera plus. La vraie solution est de charger correctement la bibliothèque.

Étape 5 : solution définitive — enregistrer les scripts manquants

La bonne approche est d'enregistrer les bibliothèques JavaScript manquantes via la méthode setMedia() de votre module ou de votre thème enfant.

Dans un module PrestaShop

Si la bibliothèque est liée à un module, surchargez la méthode setMedia() du FrontController du module :

public function setMedia()
{
    parent::setMedia();

    // Enregistrer la bibliothèque flexisel
    $this->registerJavascript(
        'flexisel',
        'modules/' . $this->module->name . '/views/js/jquery.flexisel.js',
        ['priority' => 100, 'position' => 'bottom']
    );
}

Dans le thème enfant (PrestaShop 8.x)

En PrestaShop 8.x, vous pouvez déclarer les assets directement dans le theme.yml :

assets:
  use_parent_assets: true
  js:
    all:
      - id: flexisel
        path: assets/js/jquery.flexisel.js
        priority: 100
        position: bottom

Ou via un hook dans un module compagnon :

public function hookActionFrontControllerSetMedia($params)
{
    $this->context->controller->registerJavascript(
        'flexisel',
        'modules/' . $this->name . '/views/js/jquery.flexisel.js',
        [
            'priority' => 100,
            'position' => 'bottom',
            'server' => 'local'
        ]
    );
}

Étape 6 : réinstaller proprement les modules sur le thème enfant

Un problème souvent négligé : les modules doivent être réinstallés (ou au minimum réinitialisés) après l'activation d'un thème enfant. En effet, les hooks et les positions des modules sont liés au thème actif.

Pour réinitialiser les modules sur votre thème enfant :

1. Allez dans **Apparence > Thème et logo**
2. Activez le thème parent, puis réactivez le thème enfant
3. Lors de la réactivation, PrestaShop vous proposera de réinitialiser les positions des modules

Alternativement, via la ligne de commande (PrestaShop 8.x) :

php bin/console prestashop:module reset nom_du_module

Bonnes pratiques pour éviter ces problèmes

1. Testez toujours en environnement de développement

N'installez jamais un thème enfant directement en production. Utilisez un environnement de pré-production pour valider que tous les composants fonctionnent.

2. Vérifiez la compatibilité des bibliothèques jQuery

PrestaShop 8.x utilise jQuery 3.x. Certaines bibliothèques anciennes comme Flexisel n'ont pas été mises à jour pour jQuery 3. Si vous rencontrez des incompatibilités, envisagez des alternatives modernes :

• **Flexisel** → remplacer par **Swiper.js** ou **Splide.js** (sans dépendance jQuery)
• **jQuery UI** → vérifier la compatibilité avec jQuery 3
• **Fancybox 2** → migrer vers **Fancybox 5** ou **GLightbox**

3. Utilisez la méthode registerJavascript

Évitez d'ajouter des balises