Cartes contextuelles des sujets

[denvergeeks]

	Résumé	Affiche des cartes de sujet hautement personnalisables sous forme d’infobulles au survol des liens de sujet
	Aperçu	Lisez le README sur GitHub
	Dépôt	https://github.com/denvergeeks/discourse-topic-hover-cards
	Guide d’installation	Comment installer un thème ou un composant de thème
	Nouveau sur les thèmes Discourse ?	Guide pour débutants sur l’utilisation des thèmes Discourse

Installez ce composant de thème

Cartes d’aperçu enrichies au survol pour les liens de sujets internes à travers les sujets, les réponses, les listes de sujets, la page d’accueil des catégories, les catégories de documentation, les tableaux Kanban et les sujets suggérés.

Lorsque les utilisateurs survolent un lien de sujet (ou touchent sur mobile), une carte apparaît avec la vignette du sujet, le titre, l’extrait, la catégorie, les étiquettes et les statistiques clés.

Fonctionnalités

• Cartes au survol pour les liens de sujets internes dans :
  • Le corps du sujet (premier message)
  • Les réponses
  • Les listes de sujets standards (/latest, /top, /tags, listes de sujets par catégorie, etc.)
  • Les listes de sujets de la page d’accueil des catégories (Catégories + Derniers, uniquement catégories, et mises en page connexes)
  • Les vues des catégories de documentation
  • Les vues de tableaux de style Kanban
  • Les sujets suggérés
• Mise en page adaptative :
  • Carte pour bureau avec densité et placement de vignette configurables
  • Aperçu en feuille inférieure pour mobile avec ouverture au toucher
• Contenu configurable :
  • Image de vignette
  • Badge de catégorie
  • Étiquettes
  • Titre
  • Extrait (nettoyé des images/lightboxes)
  • Auteur original
  • Date de publication
  • Vues, réponses, likes, dernière activité
• Désactivation par utilisateur via un champ utilisateur personnalisé
• Mode de débogage réservé aux administrateurs pour un dépannage sécurisé

Paramètres

Mise en page et temporisation

• card_width
  Toute valeur CSS de largeur (pour bureau), par ex. 32rem, 420px, 40vw, clamp(20rem, 40vw, 36rem).

• card_max_height
  Toute valeur CSS de hauteur maximale, par ex. 10rem, 480px, 50vh, min(60vh, 32rem).

• card_delay_ms
  Délai avant l’affichage de la carte au survol, en millisecondes (par défaut : 300).

• enable_on_mobile
  Lorsqu’activé, toucher un lien de sujet interne pris en charge affiche une feuille d’aperçu mobile.

• mobile_width_percent
  Largeur de la feuille d’aperçu mobile en pourcentage de la largeur de la fenêtre (par défaut : 100).

• mobile_thumbnail_height
  Hauteur de la vignette en pixels pour l’aperçu mobile.

Densité

• density
  Densité pour bureau : default, cozy ou compact.

• density_mobile
  Densité pour mobile : default, cozy ou compact.

Ces paramètres sont parallèles aux modèles de « Densité » de Discourse et ajustent simplement les espacements et les hauteurs de ligne.

Vignette et placement

• show_thumbnail / show_thumbnail_mobile
  Afficher/masquer l’image du sujet (le cas échéant) sur bureau et mobile.

• thumbnail_placement
  Façon dont la vignette est positionnée sur bureau :

  • top
  • left
  • right
  • bottom
    Sur mobile, la vignette est toujours rendue en haut de la carte.

• image_size_percent
  Pour les mises en page left et right sur bureau, contrôle la largeur de la vignette en pourcentage de la largeur de la carte au survol.

Champs par fenêtre

Pour chaque bloc ci-dessous, vous disposez de bascules pour bureau et mobile :

• show_category / show_category_mobile

• show_tags / show_tags_mobile

• show_title / show_title_mobile

• show_excerpt / show_excerpt_mobile

• excerpt_length / excerpt_length_mobile
  Nombre de lignes pour l’extrait (CSS line-clamp).

• show_op / show_op_mobile
  Affiche l’avatar et le nom d’utilisateur de l’auteur original.

• show_publish_date / show_publish_date_mobile

• show_views / show_views_mobile

• show_reply_count / show_reply_count_mobile

• show_likes / show_likes_mobile

• show_activity / show_activity_mobile

Où les cartes au survol apparaissent

• enable_on_topics
  Liens de sujets dans le premier message.

• enable_on_replies
  Liens de sujets dans les réponses.

• enable_on_topic_lists
  Liens de sujets dans les listes standards, par ex. /latest, /top, listes de sujets par catégorie.

• enable_on_category_homepage_topic_lists
  Liens de sujets dans les listes « derniers sujets » ou équivalentes sur la page d’accueil des catégories :

  • Catégories + derniers sujets
  • Uniquement catégories
  • Variantes connexes rendues à / ou /categories, selon la configuration de votre page d’accueil.

• enable_on_doc_categories
  Liens de sujets dans les vues des catégories de documentation (le cas échéant).

• enable_on_kanban_boards
  Liens de sujets rendus dans les mises en page de tableaux de style Kanban (le cas échéant).

• enable_on_suggested_topic_links
  Liens dans la section « Sujets suggérés ».

---

Désactivation par utilisateur

Vous pouvez permettre à des utilisateurs individuels de désactiver les cartes au survol en utilisant un champ utilisateur personnalisé. Cela utilise le mécanisme standard des paramètres de thème et l’accès aux données de l’utilisateur actuel décrits dans les guides pour développeurs.

• user_preference_field_name
  La clé utilisée pour détecter la désactivation chez l’utilisateur actuel. Cela peut être :
  • une clé de champ personnalisé directe, par ex. disable_topic_hover_cards
  • un identifiant numérique, par ex. 1
  • une clé user_field_X, par ex. user_field_1

Fonctionnement de la correspondance

1. Le composant vérifie d’abord les custom_fields et user_fields de l’utilisateur actuel pour :
   • le user_preference_field_name configuré
   • la même valeur convertie entre 1 et user_field_1 si nécessaire
2. Si aucune correspondance n’est trouvée et que l’utilisateur actuel est un membre du personnel (administrateur/modérateur) et que resolve_user_field_id_for_admins est activé, le composant appelle :
   • /admin/config/user-fields.json
     pour mapper la valeur configurée (nom de champ ou user_field_X) à son identifiant numérique.
3. Avec l’identifiant numérique, il vérifie :
   • user_fields[id]
   • user_fields['user_field_' + id]
   • custom_fields[id]
   • custom_fields['user_field_' + id]

Toute valeur vraie à ces positions (par ex. 1, true, yes, on, checked) désactive les cartes au survol pour cet utilisateur.

Paramètres pour ce comportement

• resolve_user_field_id_for_admins
  Lorsqu’activé (recommandé), les administrateurs peuvent configurer le champ par nom ou user_field_X, et le composant résoudra et correspondra automatiquement l’identifiant numérique.

• debug_mode
  Lorsqu’activé, journalise des informations détaillées de détection dans la console du navigateur pour le personnel, notamment :

  • quelles clés ont été vérifiées
  • où une correspondance a été trouvée (utilisateur actuel vs enregistrement complet de l’utilisateur)
  • l’identifiant numérique résolu du champ utilisateur, le cas échéant

---

Débogage

Si les cartes au survol n’apparaissent pas là où vous vous y attendez, utilisez le mode de débogage intégré :

1. Activez debug_mode dans les paramètres de ce composant.
2. Ouvrez la console de développement du navigateur.
3. Survolez ou touchez un lien de sujet pertinent.

Vous verrez des messages similaires à :

• Hover cards initialized – confirme l’initialisation et les emplacements activés.
• Resolved admin user-field mapping – confirme la correspondance du nom/clé de champ utilisateur configuré vers un identifiant numérique (pour le personnel).
• No disable field match found anywhere – confirme que les cartes au survol ne sont pas supprimées pour l’utilisateur actuel.

Pour déboguer où la carte devrait apparaître, vérifiez que :

• votre lien cible est un lien de sujet interne (/t/...) que topicIdFromHref() peut analyser
• le drapeau d’emplacement pertinent est activé :
  • enable_on_topics
  • enable_on_replies
  • enable_on_topic_lists
  • enable_on_category_homepage_topic_lists
  • enable_on_doc_categories
  • enable_on_kanban_boards
  • enable_on_suggested_topic_links

[chapoi]

Pourriez-vous ajouter un lien d’aperçu fonctionnel ou quelques captures d’écran pour montrer à quoi cela ressemble ?