# Personnaliser LearnDash sans toucher au plugin : surcharger les templates de cours depuis le thème

> LearnDash impose ses propres gabarits d'affichage, mais accepte qu'un thème les surcharge proprement. Voici la méthode pas à pas, sans toucher un seul fichier du plugin.

- Auteur : WordPress Développement
- Publié le : 2023-07-16
- Mis à jour le : 2023-07-16
- Catégorie : Thèmes
- URL : https://www.wpmoderne.fr/themes/theme-learndash-surcharger-templates-cours/

## L’essentiel

- LearnDash cherche d'abord les templates dans le dossier du thème actif
- La structure de dossiers à respecter est learndash/course/
- Un template surchargé garde la compatibilité avec les futures mises à jour du plugin

`learndash-front-end/themes/legacy/course/course.php` : ce chemin, copié tel quel depuis le dossier du plugin vers celui du thème actif, est la première étape de toute personnalisation sérieuse d'un parcours LearnDash. Comprendre pourquoi ce chemin précis fonctionne, et pas un autre, évite des heures de tâtonnement.

LearnDash embarque son propre système de résolution de templates, inspiré de la hiérarchie de templates WordPress mais appliqué à ses propres écrans : page de cours, liste de leçons, quiz, certificat. Ce mécanisme cherche d'abord un fichier correspondant dans le thème actif avant de retomber sur celui fourni par le plugin — à condition de respecter une arborescence précise.

## Comprendre la hiérarchie de résolution LearnDash

Quand LearnDash doit afficher la page d'un cours, il appelle en interne une fonction de résolution qui construit un chemin de recherche du plus spécifique au plus générique. Concrètement, pour un template de type `course`, LearnDash cherche, dans cet ordre :

1. `wp-content/themes/mon-theme/learndash/course/course.php`
2. `wp-content/themes/mon-theme/learndash/legacy/course/course.php` selon la version d'affichage configurée
3. le template par défaut fourni dans `wp-content/plugins/sfwd-lms/themes/legacy/course/course.php`

Le dossier racine `learndash` à la base du thème n'est pas une convention arbitraire : c'est la valeur par défaut du filtre interne que LearnDash utilise pour construire ses chemins de recherche, comparable au rôle de `woocommerce/` à la racine d'un thème pour WooCommerce.

> L'essentiel à retenir : LearnDash cherche d'abord les templates dans le dossier du thème actif ; La structure de dossiers à respecter est learndash/course/ ; Un template surchargé garde la compatibilité avec les futures mises à jour du plugin

## Étape 1 : identifier le template source à copier

Avant de surcharger quoi que ce soit, il faut localiser le fichier d'origine dans le plugin, généralement sous `wp-content/plugins/sfwd-lms/themes/ld30/` pour le thème d'affichage moderne de LearnDash, ou `themes/legacy/` pour l'ancien rendu. La commande suivante liste rapidement les templates disponibles pour les cours :

```
find wp-content/plugins/sfwd-lms/themes/ld30/course -name "*.php"
```

## Étape 2 : reproduire l'arborescence exacte dans le thème

Le fichier doit être copié à l'identique dans le thème, en conservant la structure de sous-dossiers :

```
mkdir -p wp-content/themes/mon-theme/learndash/ld30/course
cp wp-content/plugins/sfwd-lms/themes/ld30/course/course.php \
   wp-content/themes/mon-theme/learndash/ld30/course/course.php
```

Une erreur fréquente consiste à copier le fichier directement à la racine du dossier `learndash/` du thème, sans respecter le sous-dossier `ld30/course/`. LearnDash ne le détecte alors jamais, et continue silencieusement d'utiliser le template d'origine du plugin — sans message d'erreur, ce qui rend le diagnostic difficile pour qui ne connaît pas cette hiérarchie précise.

## Étape 3 : personnaliser sans casser les hooks internes

Le template copié contient généralement des appels à des fonctions LearnDash comme `learndash_get_course_meta_setting()` ou des hooks d'action comme `do_action( 'learndash-course-before' )`. Ces appels doivent rester en place, même si l'affichage autour est entièrement réécrit, car ce sont eux qui permettent à d'autres extensions LearnDash (add-ons de gamification, de reporting) de continuer à s'exécuter correctement :

```
<?php
/**
 * Template personnalisé : en-tête de cours
 * Copié depuis sfwd-lms/themes/ld30/course/course.php
 */
do_action( 'learndash-course-before', $course_id, $user_id );
?>

<div class="mon-theme-course-header">
    <h1><?php the_title(); ?></h1>
    <?php if ( learndash_course_steps_remaining( $course_id, $user_id ) > 0 ) : ?>
        <p class="progression">
            <?php echo esc_html( learndash_course_progress( [
                'user_id'   => $user_id,
                'course_id' => $course_id,
                'array'     => false,
            ] ) ); ?>
        </p>
    <?php endif; ?>
</div>

<?php do_action( 'learndash-course-after', $course_id, $user_id ); ?>
```

## Cas particulier : les templates de quiz et de certificat

Les quiz suivent la même logique mais avec un dossier racine différent, `learndash/quiz/`, et introduisent une contrainte supplémentaire : certains rendus de quiz reposent sur des scripts JavaScript embarqués côté plugin qui ciblent des classes CSS précises. Renommer ou supprimer ces classes dans un template surchargé casse la mécanique de soumission des réponses. Il est donc préférable, pour les quiz, de personnaliser l'habillage visuel via CSS plutôt que de réécrire la structure HTML du template.

## Pourquoi ne jamais toucher aux fichiers du plugin

Modifier directement un fichier sous `wp-content/plugins/sfwd-lms/` fonctionne le temps d'une démonstration, mais toute mise à jour du plugin écrase ces modifications sans avertissement. La surcharge par le thème, à l'inverse, survit aux mises à jour : LearnDash continue de chercher en priorité dans le thème, et n'utilisera le fichier du plugin mis à jour que pour les templates non surchargés.

> Un template LearnDash surchargé depuis le thème doit rester le plus proche possible de l'original du plugin : seule l'habillage change, jamais la logique métier des hooks internes.

## Pour aller plus loin

Cette méthode couvre l'affichage des parcours et des quiz ; elle ne traite ni la création de contenus pédagogiques ni la configuration des règles de progression, qui relèvent de l'interface d'administration LearnDash elle-même. Une fois la surcharge en place, il reste utile de documenter, dans un fichier `readme.txt` du thème, la liste exacte des templates modifiés et leur version d'origine, pour faciliter la maintenance lors des futures montées de version de LearnDash.