Guide du module Glossaire pour Larapen

Un add-on de glossaire optimisé pour le SEO pour Larapen, avec navigation A–Z, catégories, recherche et balisage de données structurées pour les définitions et les termes techniques.

Cas d’utilisation

Site de documentation technique

Vous gérez un site de produit logiciel et souhaitez aider les utilisateurs à comprendre le jargon technique.

• Créez des catégories comme “Programmation”, “Réseaux”, “Sécurité”.
• Ajoutez des termes avec des définitions courtes et du contenu étendu avec des exemples de code.
• Utilisez les abréviations (par ex., API, DNS, SSL) pour une référence rapide.
• Le balisage de données structurées aide les moteurs de recherche à afficher les définitions dans les extraits enrichis.

Base de connaissances sectorielle

Vous maintenez un site web professionnel dans la finance, la santé ou les services juridiques et avez besoin d’un glossaire de termes du secteur.

• Regroupez les termes par domaine (par ex., “Comptabilité”, “Fiscalité”, “Conformité”).
• Fournissez des définitions claires et traduisibles en plusieurs langues.
• Utilisez le mode d’affichage paginé pour les glossaires comportant des centaines d’entrées.

Site web éducatif

Une école ou une plateforme de formation souhaite que les étudiants puissent rechercher rapidement des concepts.

• Les étudiants parcourent par lettre ou recherchent des termes.
• Les termes connexes sont liés entre eux pour un apprentissage plus approfondi.
• Les compteurs de vues aident à identifier les termes les plus consultés.

Prérequis

• Larapen CMS v1.0.0 ou ultérieur
• PHP 8.3+
• MySQL 8.0+

Installation

Étape 1 : Téléverser l’add-on

Dans le panneau d’administration, allez dans Admin → Extensions → Add-ons et cliquez sur le bouton Télécharger un add-on. Sélectionnez le fichier ZIP de l’add-on : le système le décompresse automatiquement et l’add-on apparaît dans la liste des add-ons installés.

Étape 2 : Activer l’add-on

Repérez Système de Glossaire dans la liste et cliquez sur Activer. Ses migrations, ses seeders (le cas échéant) et ses permissions sont mis en place automatiquement.

Étape 3 : Configurer

Naviguez vers Admin → Glossaire → Paramètres pour configurer le slug d’URL public, le nombre de termes par page et le comportement des termes associés. Voir Configuration.

Code d’achat (clé de licence)

Système de Glossaire est vendu comme un produit séparé, il possède donc son propre code d’achat (clé de licence), distinct du code d’achat de l’application principale et de celui de chaque autre add-on. Il vous est demandé lorsque vous activez Système de Glossaire dans Panneau d’administration → Add-ons.

Nos produits sont vendus sur trois plateformes. La façon dont vous recevez un code d’achat dépend de l’endroit où vous avez acheté le produit.

1. Boutique bedigit.com (achat sur le site)

• Dès que le statut de paiement de la commande devient Payée, une clé de licence est générée automatiquement pour chaque article sous licence de la commande (une clé par unité achetée : acheter 3 unités donne 3 clés distinctes).
• Elle est envoyée par e-mail à l’adresse utilisée pour la commande, soit dans un e-mail de licence dédié, soit dans l’e-mail de confirmation de commande. Vérifiez votre boîte de réception et votre dossier spam / courrier indésirable.
• La clé reste disponible dans votre compte sous Mon compte → Mes licences. Les clés sont masquées dans la liste ; ouvrez la page de détail de la licence pour afficher et copier la clé complète, voir les domaines sur lesquels elle est activée, et désactiver un domaine pour libérer un emplacement d’activation.
• La facture correspondante se trouve sous Mon compte → Mes commandes.

2. Gumroad

• Un achat sur Gumroad produit deux e-mails distincts : le reçu Gumroad (envoyé par Gumroad, donnant accès aux fichiers) et un e-mail de clé de licence (envoyé par bedigit.com) qui contient votre code d’achat.
• L’e-mail de clé de licence est généré dès que Gumroad nous notifie la vente, il arrive donc normalement quelques secondes après le paiement. Ici aussi, vérifiez votre boîte de réception et votre dossier spam / courrier indésirable.
• Lorsque le produit Gumroad utilise la fonctionnalité de clés de licence propre à Gumroad, la même clé apparaît aussi dans votre reçu Gumroad et sous Bibliothèque → votre achat sur gumroad.com.
• Utilisez la même adresse e-mail sur bedigit.com que sur Gumroad : vos clés sont alors liées automatiquement à votre compte et listées sous Mon compte → Mes licences, même si vous vous inscrivez après l’achat. Vous pouvez aussi ajouter une clé Gumroad manuellement depuis Mon compte → Mes licences Gumroad.

3. Envato Market (CodeCanyon)

• Les codes d’achat Envato sont délivrés et fournis par Envato Market, jamais envoyés par e-mail par nous, il n’y a donc rien à chercher dans votre dossier de spam : vous récupérez le code depuis votre compte Envato.
• Connectez-vous à votre compte Envato / CodeCanyon, ouvrez la page Downloads, trouvez l’article et choisissez License certificate & purchase code dans le menu déroulant Download. Le code est inscrit dans ce certificat.
• Un code d’achat Envato ressemble à 12345678-90ab-cdef-1234-567890abcdef (8-4-4-4-12 caractères). Il ne change jamais, et le renouvellement du support de l’article n’en délivre pas de nouveau.
• Article officiel Envato : Where Is My Purchase Code?

Configuration

Les valeurs par défaut de configuration sont définies dans config/glossary.php et peuvent être remplacées depuis le panneau d’administration dans Admin → Glossaire → Paramètres (stockées dans la table settings, groupe glossary).

Valeurs par défaut du fichier de configuration

Admin : termes

La page des Termes (Glossaire → Tous les termes) est l’interface principale de gestion des entrées du glossaire.

Liste des termes

Un tableau paginé (20 par page par défaut) affichant :

• Lettre : la première lettre du terme, affichée sous forme de badge
• Terme : le nom du terme avec un aperçu tronqué de la définition en dessous
• Catégorie : badge de la catégorie assignée (ou tiret si non catégorisé)
• Abréviation : affichée en code inline (par ex., API, CSS)
• Statut : badge coloré (Brouillon/Publié/Archivé)
• Vues : compteur de vues front-end

Actions par terme : Modifier, Supprimer (avec confirmation).

Filtrage

La liste prend en charge trois contrôles de filtrage :

• Recherche : champ de texte qui recherche dans les noms de termes, les définitions et les abréviations
• Filtre de statut : menu déroulant pour filtrer par Brouillon, Publié ou Archivé
• Filtre de catégorie : menu déroulant pour filtrer par catégorie de glossaire

Création & modification de termes

Le formulaire de création/modification est organisé en sections :

Contenu (traduisible)

Un sélecteur de langue permet de basculer entre les langues actives. Pour chaque langue :

• Terme : le nom du terme (requis pour la langue par défaut)
• Slug : slug adapté aux URL (généré automatiquement si laissé vide)
• Définition : texte de définition courte (requis pour la langue par défaut)
• Contenu étendu : explication plus longue, exemples ou contenu riche

SEO & méta (traduisible)

• Titre méta : jusqu’à 70 caractères
• Description méta : jusqu’à 160 caractères

Barre latérale de publication

• Statut : Brouillon, Publié ou Archivé
• Catégorie : sélectionner parmi les catégories du glossaire (optionnel)
• Abréviation : forme courte ou acronyme (par ex., API, CSS, ML) : jusqu’à 50 caractères

Admin : catégories

La page des Catégories (Glossaire → Catégories) gère les catégories du glossaire en utilisant le système de catégories unifié du noyau.

Liste des catégories

Un tableau paginé affichant les catégories avec des indicateurs d’imbrication :

• Nom : avec indentation pour les catégories imbriquées
• Slug : affiché en code inline
• Statut : badge Actif ou Inactif

Actions par catégorie : Modifier, Supprimer (avec confirmation).

Création & modification de catégories

Les catégories utilisent les form requests du noyau StoreCategoryRequest / UpdateCategoryRequest. Toutes les catégories du glossaire sont stockées dans la table categories avec categorizable_type = 'glossary'.

Les champs de catégorie incluent le nom, le slug, la description, le titre méta et la description méta traduisibles, plus une catégorie parente optionnelle pour l’imbrication.

Admin : paramètres

La page des paramètres (Glossaire → Paramètres) configure le comportement d’affichage front-end.

Mode d’affichage

Deux modes d’affichage mutuellement exclusifs, sélectionnables via des cartes radio stylisées :

• Groupé par lettre : tous les termes chargés en une fois, organisés sous des en-têtes A–Z. Idéal pour les glossaires de petite à moyenne taille (moins de ~200 termes).
• Liste paginée : termes chargés page par page avec des contrôles de pagination. Recommandé pour les glossaires volumineux comportant de nombreuses entrées.

Éléments par page

Sélecteur déroulant avec les options : 10, 15, 20, 30, 50, 100. Contrôle la pagination en mode paginé, les résultats de recherche, le filtrage par lettre et le filtrage par catégorie.

Les paramètres sont stockés dans la table settings (groupe : glossary) et remplacent les valeurs par défaut dans config/glossary.php.

Front-end : index du glossaire

La page d’index du glossaire est le point d’entrée principal pour les visiteurs, disponible à /{locale}/glossary.

Mise en page

• Barre de navigation A–Z : une bande de lettres alphabétiques en haut. Les lettres ayant des termes publiés sont cliquables ; les lettres sans termes sont grisées. Un lien “Tous” affiche tous les termes.
• Barre de recherche : recherche en texte intégral dans les noms de termes, les définitions et les abréviations.
• Filtre par catégorie : menu déroulant ou barre latérale optionnel pour filtrer par catégorie.

Mode groupé

Lorsque glossary_display_mode = 'grouped', tous les termes publiés sont chargés en une fois et affichés sous des en-têtes de sections alphabétiques (A, B, C…). Chaque terme affiche son nom, une définition tronquée, l’abréviation (le cas échéant) et le badge de catégorie.

Mode paginé

Lorsque glossary_display_mode = 'paginated', les termes sont paginés selon le paramètre glossary_per_page. Les liens de pagination Laravel standard apparaissent en bas.

Recherche

Lorsqu’une requête de recherche est soumise, le système retourne toujours des résultats paginés, quel que soit le mode d’affichage configuré. La recherche correspond aux noms de termes, aux définitions et aux abréviations dans la locale actuelle.

Front-end : filtrage par lettre

Cliquer sur une lettre dans la navigation A–Z redirige vers /{locale}/glossary/letter/{letter}.

Cette page affiche tous les termes publiés commençant par la lettre sélectionnée, paginés selon le paramètre de nombre par page. La barre de navigation A–Z reste visible, avec la lettre active mise en évidence.

Seuls les caractères alphanumériques uniques sont acceptés (validés par la contrainte de route [A-Za-z0-9]).

Front-end : filtrage par catégorie

Les pages de catégories sont disponibles à /{locale}/glossary/category/{slug}.

Le slug de catégorie est traduisible : chaque langue peut avoir son propre slug adapté aux URL. Le contrôleur résout la catégorie par slug dans la locale actuelle et affiche tous les termes de cette catégorie, paginés. Les URL alternatives sont partagées pour le sélecteur de langue.

Front-end : page de détail du terme

Chaque terme dispose d’une page dédiée à /{locale}/glossary/{slug}.

Contenu de la page

• Badge de lettre : indicateur de lettre en grand format
• Titre du terme (h1)
• Abréviation : affichée si définie (avec icône de hachage)
• Badge de catégorie : lien cliquable vers la page de catégorie
• Définition : le texte de définition principal
• Contenu étendu : explication plus longue, exemples ou contenu riche
• Termes connexes : jusqu’à 5 termes de la même catégorie, liés pour une exploration approfondie

Fil d’Ariane

Fil d’Ariane complet : Accueil → Glossaire → Lettre → Catégorie (si assignée) → Terme.

Compteur de vues

Chaque fois qu’une page de détail de terme est chargée, le view_count est incrémenté. Ce compteur est visible dans la liste d’administration et peut être affiché sur le front-end.

Sélecteur de langue

Les URL alternatives sont partagées pour le sélecteur de langue, en utilisant le slug traduisible du terme dans chaque langue via share_alternate_urls().

SEO & données structurées

Balises méta

Chaque page génère des balises méta appropriées via SeoService::getMetaTags() :

• Page d’index : utilise le titre et la description du glossaire configurés
• Page de lettre : “Glossaire : Lettre {letter}”
• Page de catégorie : utilise le titre/la description méta de la catégorie (retombe sur le nom)
• Détail du terme : utilise le titre méta du terme (retombe sur “{term} : Définition & Signification”) et la description méta (retombe sur la définition tronquée, 160 caractères)

Données structurées

La page de détail du terme prend en charge le balisage de données structurées Schema.org DefinedTerm, qui aide les moteurs de recherche à comprendre et potentiellement à afficher les définitions sous forme d’extraits enrichis dans les résultats de recherche.

Mise à jour

Il existe deux façons de mettre cet add-on à jour : via le panneau d’administration (recommandé) ou en remplaçant manuellement les fichiers.

Méthode 1 : Téléversement via le panneau d’administration (recommandé)

1. Téléchargez le dernier fichier .zip de cet add-on.
2. Allez dans Panneau d’administration → Add-ons et cliquez sur le bouton Téléverser.
3. Sélectionnez ou faites glisser le fichier .zip dans la zone de téléversement.
4. Une invite de confirmation affichera les numéros de version actuelle et nouvelle. Cliquez sur Remplacer pour continuer.
5. Allez dans Panneau d’administration → Mise à jour du système (/admin/update) pour appliquer les migrations de base de données en attente.

Méthode 2 : Remplacement manuel des fichiers

Étape 1 : Remplacer les fichiers

Remplacez le répertoire de l’add-on par la nouvelle version.

Étape 2 : Exécuter les migrations

php artisan migrate

Les migrations en attente ne s’exécutent qu’une seule fois : la commande peut être relancée sans risque.

Étape 3 : Recompiler les ressources

Étape 4 : Vider les caches

php artisan config:clear
php artisan route:clear
php artisan view:clear

Étape 5 : Vérifier

Visitez Admin → Glossaire → Tous les termes et la page front-end du glossaire pour confirmer que tout fonctionne correctement.

Désinstallation

Éteindre un add-on sans rien perdre, c’est le désactiver : allez dans Panneau d’administration → Add-ons, trouvez Glossary System et cliquez sur Désactiver.

• Ses routes, ses vues, ses entrées de menu d’administration et ses permissions cessent d’être enregistrées, et ses pages publiques ne répondent plus.
• Ses tables de base de données et toutes les données qu’elles contiennent sont conservées, et ses fichiers restent dans extensions/addons/glossary/. Rien n’est supprimé.
• Le code d’achat enregistré lors de l’activation est conservé lui aussi : réactiver l’add-on ne le redemande pas.
• La désactivation est refusée tant qu’un autre add-on actif dépend de celui-ci : désactivez d’abord cet add-on.

Cliquez sur Activer sur la même carte pour le rallumer. Les migrations en attente sont rejouées, les assets republiés, et l’add-on reprend exactement là où il s’était arrêté.

Suppression

La suppression est définitive et détruit les données de l’add-on. Le bouton Supprimer n’apparaît que sur un add-on désactivé : la suppression se fait donc toujours en deux temps :

1. Désactivez Glossary System (voir Désinstallation).
2. Cliquez sur Supprimer sur sa carte et confirmez la demande.

Le panneau d’administration, en une seule passe :

• exécute le hook de désinstallation de l’add-on, s’il en fournit un, tant que son code est encore sur le disque ;
• révoque les permissions déclarées dans son addon.json ;
• annule ses migrations, ce qui supprime ses tables de base de données et toutes les lignes qu’elles contiennent, et purge ses entrées de la table migrations, afin qu’une réinstallation ultérieure reparte de zéro ;
• supprime ses assets publiés : public/addons/glossary/, public/vendor/glossary/ et storage/app/public/addons/glossary/ ;
• supprime le dossier de l’add-on extensions/addons/glossary/ ;
• supprime sa ligne dans la table addons (le code d’achat enregistré disparaît avec elle) et vide le cache de l’application.

La suppression est refusée, avec un message explicatif et avant toute destruction, lorsque l’add-on est encore actif, lorsqu’un autre add-on actif en dépend, ou lorsque l’utilisateur du serveur web (PHP) ne peut pas supprimer extensions/addons/glossary/. Dans ce dernier cas, donnez à cet utilisateur le droit d’écriture sur le dossier et sur son parent, puis réessayez.

Supprimer le dossier en FTP ou en SSH n’est pas équivalent : les tables de l’add-on, ses entrées dans la table migrations et sa ligne addons restent en place, et sa carte reste dans la liste. Utilisez plutôt Supprimer dans le panneau d’administration.

Dépannage

La page du glossaire affiche “Aucun terme trouvé”

• Assurez-vous qu’au moins un terme a le statut Publié et une date published_at dans le passé.
• Les termes en Brouillon et Archivés ne sont pas affichés sur le front-end.
• Si vous utilisez le filtrage par catégorie, vérifiez que la catégorie a des termes publiés assignés.

La navigation A–Z n’affiche aucune lettre cliquable

La navigation par lettre ne met en évidence que les lettres ayant au moins un terme publié. Ajoutez et publiez des termes pour remplir la navigation.

La page de détail du terme retourne une erreur 404

• Le terme doit être publié (statut = published et published_at ≤ now()).
• Vérifiez que le slug correspond à la locale actuelle. Chaque langue a son propre slug traduisible.
• Vérifiez que le slug n’entre pas en conflit avec d’autres routes (par ex., letter ou category).

Les catégories n’apparaissent pas dans le filtre

• Les catégories doivent avoir is_active = true dans la table des catégories.
• Les catégories doivent avoir categorizable_type = 'glossary'.
• Assurez-vous de créer les catégories via Admin → Glossaire → Catégories, et non via le gestionnaire de catégories d’un autre add-on.

La lettre n’est pas dérivée automatiquement correctement

La colonne letter est dérivée du premier caractère du nom du terme (en utilisant la traduction anglaise, ou la première locale disponible). Si le terme commence par un caractère non-ASCII, la lettre peut ne pas correspondre à A–Z. Les termes commençant par des chiffres utilisent le chiffre comme lettre.

Erreur de manifeste Vite : “Unable to locate file”

Si vous voyez cette erreur pour les fichiers SCSS du glossaire, recompilez le manifeste Vite :

Ceci est requis après l’ajout de nouveaux fichiers SCSS ou JS dans les répertoires de ressources du thème.

Les paramètres ne prennent pas effet

• Videz le cache de configuration : php artisan config:clear
• Les paramètres enregistrés dans le panneau d’administration (stockés dans la table settings) remplacent les valeurs par défaut dans config/glossary.php.
• Vérifiez que le groupe de paramètres est glossary dans la base de données.

La recherche ne retourne aucun résultat

La recherche correspond au nom du terme et à la définition de la locale actuelle, plus le champ d’abréviation (qui n’est pas traduisible). Assurez-vous que la requête de recherche correspond au contenu dans la langue active.