Système de Glossaire

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 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 Industrielle

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 : Placer l’Add-on

Copiez ou créez un lien symbolique du dossier glossary dans le répertoire "extensions/addons" de votre Larapen :

Étape 2 : Activer l’Add-on

Allez dans Admin → Add-ons → Add-ons Installés et activez Système de Glossaire.

Étape 3 : Exécuter les Migrations

Cela crée la table glossary_terms. Les catégories sont stockées dans la table categories du noyau avec categorizable_type = 'glossary'.

Étape 4 : Définir les Permissions

L’add-on enregistre 10 permissions (voir Permissions). Assignez-les aux rôles administrateurs via Admin → Utilisateurs → Rôles & Permissions.

Étape 5 : Configurer (Optionnel)

Naviguez vers Admin → Glossaire → Paramètres pour choisir le mode d’affichage et le nombre d’éléments par page. Les valeurs par défaut fonctionnent immédiatement. Voir Configuration.

Étape 6 : Compiler les Ressources du Thème

Si votre thème actif inclut des fichiers SCSS spécifiques au glossaire, recompilez le manifeste Vite :

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).

Paramètre	Description	Par défaut
glossary_display_mode	Mode d’affichage front-end : grouped (tous les termes groupés par lettre) ou paginated (liste paginée).	grouped
glossary_per_page	Nombre de termes par page en mode paginé, résultats de recherche, filtrage par lettre et filtrage par catégorie.	20

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 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 avec 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, définitions et 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, définitions et 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/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

Étape 1 : Remplacer les Fichiers

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

Étape 2 : Exécuter les Migrations

Étape 3 : Recompiler les Ressources

Étape 4 : Vider les Caches

Étape 5 : Vérifier

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

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.