Hover-Karten für Themen

[denvergeeks]

	Zusammenfassung	Zeigt Tooltipp-ähnliche Popups beim Überfahren (oder Tippen auf mobilen Geräten) interner Topic-Links an, um eine schnelle Vorschau des verlinkten Topics zu zeigen.
	Vorschau	Github Readme
	Repository	https://github.com/denvergeeks/discourse-topic-hover-cards
	Installationsanleitung	Wie man ein Theme oder eine Theme-Komponente installiert
	Neu bei Discourse Themes?	Einsteigerleitfaden zur Verwendung von Discourse Themes

Dieses Theme-Komponente installieren

Reiche Hover-Vorschau-Karten für interne Topic-Links in Topics, Antworten, Topic-Listen, den Kategorien-Startseiten, Dokumentationskategorien, Kanban-Boards und vorgeschlagenen Topics. Für Desktop und/oder Mobilgeräte. Siteweit und hochgradig konfigurierbar.

Funktionen

• Kann siteweit für alle internen Topic-Links aktiviert werden oder nur für solche, die in einem oder mehreren Bereichen erscheinen, darunter:
  • Topic-Text (ursprünglicher Beitrag)
  • Antworten
  • Standard-Topic-Listen (/latest, /top, /tags, Kategorien-Topic-Listen usw.)
  • Topic-Listen auf der Kategorien-Startseite (Kategorien + Neueste, Nur Kategorien und verwandte Layouts)
  • Ansichten von Dokumentationskategorien
  • Kanban-Board-Ansichten
  • Vorgeschlagene Topics
• Responsives Layout:
  • Desktop-Karte mit konfigurierbarer Dichte und Platzierung des Thumbnails
  • Mobile Bottom-Sheet-Vorschau mit Tippen zum Öffnen
• Konfigurierbarer Inhalt:
  • Thumbnail-Bild
  • Kategorie-Abzeichen
  • Tags
  • Titel
  • Auszug (bereinigt von Bildern/Lightboxen)
  • Ursprünglicher Poster
  • Veröffentlichungsdatum
  • Aufrufe, Antworten, Likes, letzte Aktivität
• Benutzerweites Opt-Out über ein benutzerdefiniertes Benutzerfeld
• Nur für Administratoren zugänglicher Debug-Modus zur sicheren Fehlerbehebung

Einstellungen

Layout & Timing

• card_width
  Jeder CSS-Weitenwert (für Desktop), z. B. 32rem, 420px, 40vw, clamp(20rem, 40vw, 36rem).

• card_max_height
  Jeder CSS-max-height-Wert, z. B. 10rem, 480px, 50vh, min(60vh, 32rem).

• card_delay_ms
  Verzögerung vor dem Anzeigen der Hover-Karte in Millisekunden (Standard: 300).

• enable_on_mobile
  Wenn aktiviert, zeigt ein Tippen auf einen unterstützten internen Topic-Link eine mobile Vorschau-Sheet am unteren Bildschirmrand an.

• mobile_width_percent
  Breite der mobilen Bottom-Sheet-Vorschau als Prozentsatz der Viewport-Breite (Standard: 100).

• mobile_thumbnail_height
  Thumbnail-Höhe in Pixeln für die mobile Vorschau.

Dichte

• density
  Desktop-Dichte: default, cozy oder compact.

• density_mobile
  Mobile Dichte: default, cozy oder compact.

Diese entsprechen den Discourse-„Dichte“-Mustern und passen lediglich die Abstände und Zeilenhöhen an.

Thumbnail & Platzierung

• show_thumbnail / show_thumbnail_mobile
  Topic-Bild (falls vorhanden) auf Desktop und Mobilgeräten anzeigen/ausblenden.

• thumbnail_placement
  Wie das Thumbnail auf Desktop positioniert wird:

  • top
  • left
  • right
  • bottom
    Auf Mobilgeräten wird das Thumbnail immer oben in der Karte gerendert.

• image_size_percent
  Steuert die Thumbnail-Größe als Prozentsatz der gerenderten Hover-Kartengröße.

Felder pro Viewport

Für jeden folgenden Block haben Sie sowohl Desktop- als auch Mobile-Schalter:

• 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
  Anzahl der Zeilen für den Auszug (verwendet CSS line-clamp).

• show_op / show_op_mobile
  Zeigt Avatar und Benutzername des ursprünglichen Posters an.

• 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

Wo Hover-Karten erscheinen

• enable_on_topics
  Topic-Links im ursprünglichen Beitrag.

• enable_on_replies
  Topic-Links in Antworten.

• enable_on_topic_lists
  Topic-Links in Standard-Topic-Listen, z. B. /latest, /top, Kategorien-Topic-Listen.

• enable_on_category_homepage_topic_lists
  Topic-Links in den „Neuesten Topics“ oder entsprechenden Listen auf der Kategorien-Startseite:

  • Kategorien + Neueste Topics
  • Nur Kategorien
  • Verwandte Varianten, die unter / oder /categories gerendert werden, je nach Konfiguration Ihrer Startseite.

• enable_on_doc_categories
  Topic-Links in Ansichten von Dokumentationskategorien (falls zutreffend).

• enable_on_kanban_boards
  Topic-Links, die in Kanban-Board-Layouts gerendert werden (falls zutreffend).

• enable_on_suggested_topic_links
  Links im Abschnitt „Vorgeschlagene Topics“.

---

Benutzerweites Opt-Out

Sie können einzelnen Benutzern ermöglichen, Hover-Karten über ein benutzerdefiniertes Benutzerfeld zu deaktivieren. Dies verwendet den Standard-Theme-Einstellungsmechanismus und den Zugriff auf aktuelle Benutzerdaten, wie in den Entwicklerleitfäden beschrieben.

• user_preference_field_name
  Der Schlüssel, der verwendet wird, um das Opt-Out des aktuellen Benutzers zu erkennen. Dies kann sein:
  • ein direkter benutzerdefinierter Feldschlüssel, z. B. disable_topic_hover_cards
  • eine numerische ID, z. B. 1
  • ein user_field_X-Schlüssel, z. B. user_field_1

Wie die Übereinstimmung funktioniert

1. Die Komponente überprüft zunächst die custom_fields und user_fields des aktuellen Benutzers auf:
   • den konfigurierten user_preference_field_name
   • denselben Wert, der zwischen 1 und user_field_1 konvertiert wird, falls angemessen
2. Wenn keine Übereinstimmung gefunden wird und der aktuelle Benutzer ein Mitarbeiter (Administrator/Moderator) ist und
   resolve_user_field_id_for_admins aktiviert ist, ruft die Komponente auf:
   • /admin/config/user-fields.json
     um den konfigurierten Wert (Feldname oder user_field_X) seiner numerischen ID zuzuordnen.
3. Mit der numerischen ID wird überprüft:
   • user_fields[id]
   • user_fields['user_field_' + id]
   • custom_fields[id]
   • custom_fields['user_field_' + id]

Jeder wahrhafte Wert in diesen Positionen (z. B. 1, true, yes, on, checked) deaktiviert Hover-Karten für diesen Benutzer.

Einstellungen für dieses Verhalten

• resolve_user_field_id_for_admins
  Wenn aktiviert (empfohlen), können Administratoren das Feld entweder nach Name oder user_field_X konfigurieren, und die Komponente löst die numerische ID automatisch auf und stimmt sie ab.

• debug_mode
  Wenn aktiviert, protokolliert detaillierte Erkennungsinformationen in der Browserkonsole für Mitarbeiter, einschließlich:

  • welche Schlüssel überprüft wurden
  • wo eine Übereinstimmung gefunden wurde (aktueller Benutzer vs. vollständiger Benutzerdatensatz)
  • die aufgelöste numerische Benutzer-Feld-ID, falls vorhanden

---

Fehlerbehebung

Wenn Hover-Karten nicht dort erscheinen, wo Sie sie erwarten, verwenden Sie den integrierten Debug-Modus:

1. Aktivieren Sie debug_mode in den Einstellungen dieser Komponente.
2. Öffnen Sie die Entwicklerkonsole des Browsers.
3. Fahren Sie über einen relevanten Topic-Link oder tippen Sie darauf.

Sie werden Nachrichten ähnlich wie folgende sehen:

• Hover cards initialized – bestätigt die Initialisierung und die aktivierten Orte.
• Resolved admin user-field mapping – bestätigt die Zuordnung Ihres konfigurierten Benutzerfeldnamens/Schlüssels zu einer numerischen ID (für Mitarbeiter).
• No disable field match found anywhere – bestätigt, dass Hover-Karten für den aktuellen Benutzer nicht unterdrückt werden.

Um zu debuggen, wo die Karte erscheinen sollte, stellen Sie sicher, dass:

• Ihr Ziel-Link ein interner Topic-Link (/t/...) ist, den topicIdFromHref() parsen kann
• das relevante Ortsflag aktiviert ist:
  • 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

Geplante Einstellungen und Funktionen, die noch hinzugefügt werden müssen:

• Ausgeschlossene Tags
• Enthaltene Tags
• Ausgeschlossene Klassen
• Enthaltene Klassen
• OneBoxes und andere standardmäßig ausschließen
• Vorschläge??

[chapoi]

Könntest du einen funktionierenden Vorschau-Link oder einige Screenshots hinzufügen, um zu zeigen, wie das aussieht?