Schede di visualizzazione al passaggio del mouse per gli argomenti

[denvergeeks]

	Riepilogo	Mostra schede argomento altamente personalizzabili come suggerimenti al passaggio del mouse sui collegamenti agli argomenti
	Anteprima	Github Readme
	Repository	https://github.com/denvergeeks/discourse-topic-hover-cards
	Guida all’installazione	Come installare un tema o un componente tema
	Nuovo a Discourse Themes?	Guida per principianti all’uso dei temi Discourse

Installa questo componente tema

Schede di anteprima avanzate per i collegamenti interni agli argomenti tra argomenti, risposte, elenchi di argomenti, homepage delle categorie, Categorie Doc, bacheche Kanban e argomenti suggeriti.

Quando gli utenti passano il mouse su un collegamento a un argomento (o toccano su mobile), appare una scheda con l’immagine in miniatura, il titolo, l’estratto, la categoria, i tag e le statistiche principali dell’argomento.

Caratteristiche

• Schede al passaggio del mouse per i collegamenti interni agli argomenti in:
  • Corpo dell’argomento (post originale)
  • Risposte
  • Elenchi standard di argomenti (/latest, /top, /tags, elenchi di argomenti per categoria, ecc.)
  • Elenchi di argomenti nell’homepage delle categorie (Categorie + Ultime, Solo categorie e layout correlati)
  • Visualizzazioni delle Categorie Doc
  • Visualizzazioni di bacheche in stile Kanban
  • Argomenti suggeriti
• Layout responsivo:
  • Scheda desktop con densità e posizionamento dell’immagine in miniatura configurabili
  • Anteprima a foglio inferiore su mobile con apertura al tocco
• Contenuto configurabile:
  • Immagine in miniatura
  • Badge della categoria
  • Tag
  • Titolo
  • Estratto (pulito da immagini/lightbox)
  • Autore originale
  • Data di pubblicazione
  • Visualizzazioni, risposte, like, ultima attività
• Disattivazione per utente tramite un campo utente personalizzato
• Modalità di debug riservata agli amministratori per la risoluzione sicura dei problemi

Impostazioni

Layout e tempistiche

• card_width
  Qualsiasi valore di larghezza CSS (per desktop), ad esempio 32rem, 420px, 40vw, clamp(20rem, 40vw, 36rem).

• card_max_height
  Qualsiasi valore di altezza massima CSS, ad esempio 10rem, 480px, 50vh, min(60vh, 32rem).

• card_delay_ms
  Ritardo prima di mostrare la scheda al passaggio del mouse, in millisecondi (predefinito: 300).

• enable_on_mobile
  Se abilitato, il tocco su un collegamento interno a un argomento supportato mostra un foglio di anteprima per mobile.

• mobile_width_percent
  Larghezza del foglio di anteprima inferiore su mobile come percentuale della larghezza della finestra di visualizzazione (predefinito: 100).

• mobile_thumbnail_height
  Altezza dell’immagine in miniatura in pixel per l’anteprima mobile.

Densità

• density
  Densità desktop: default, cozy o compact.

• density_mobile
  Densità mobile: default, cozy o compact.

Queste sono parallele ai pattern di “Densità” di Discourse e semplicemente regolano il padding e l’altezza delle righe.

Immagine in miniatura e posizionamento

• show_thumbnail / show_thumbnail_mobile
  Mostra/nascondi l’immagine dell’argomento (se presente) su desktop e mobile.

• thumbnail_placement
  Come viene posizionata l’immagine in miniatura su desktop:

  • top
  • left
  • right
  • bottom
    Su mobile, l’immagine in miniatura viene sempre visualizzata nella parte superiore della scheda.

• image_size_percent
  Per i layout desktop left e right, controlla la larghezza dell’immagine in miniatura come percentuale della larghezza della scheda al passaggio del mouse.

Campi per finestra di visualizzazione

Per ogni blocco sottostante, hai sia interruttori desktop che 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
  Numero di righe per l’estratto (CSS line-clamp).

• show_op / show_op_mobile
  Mostra avatar e nome utente dell’autore originale.

• 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

Dove appaiono le schede al passaggio del mouse

• enable_on_topics
  Collegamenti agli argomenti nel post originale.

• enable_on_replies
  Collegamenti agli argomenti nelle risposte.

• enable_on_topic_lists
  Collegamenti agli argomenti negli elenchi standard di argomenti, ad esempio /latest, /top, elenchi di argomenti per categoria.

• enable_on_category_homepage_topic_lists
  Collegamenti agli argomenti negli elenchi “Ultime attività” o equivalenti nell’homepage delle categorie:

  • Categorie + Ultime attività
  • Solo categorie
  • Varianti correlate visualizzate in / o /categories, a seconda di come è configurata la tua homepage.

• enable_on_doc_categories
  Collegamenti agli argomenti nelle visualizzazioni delle Categorie Doc (se applicabile).

• enable_on_kanban_boards
  Collegamenti agli argomenti visualizzati nei layout di bacheche in stile Kanban (se applicabile).

• enable_on_suggested_topic_links
  Collegamenti nella sezione “Argomenti suggeriti”.

---

Disattivazione per utente

Puoi consentire a singoli utenti di disattivare le schede al passaggio del mouse utilizzando un campo utente personalizzato. Questo utilizza il meccanismo standard delle impostazioni del tema e l’accesso ai dati dell’utente corrente descritti nelle guide per sviluppatori.

• user_preference_field_name
  La chiave utilizzata per rilevare la disattivazione per l’utente corrente. Può essere:
  • una chiave di campo personalizzato diretta, ad esempio disable_topic_hover_cards
  • un ID numerico, ad esempio 1
  • una chiave user_field_X, ad esempio user_field_1

Come funziona la corrispondenza

1. Il componente controlla prima i custom_fields e user_fields dell’utente corrente per:
   • la user_preference_field_name configurata
   • lo stesso valore convertito tra 1 e user_field_1 quando appropriato
2. Se non viene trovata alcuna corrispondenza e l’utente corrente è del personale (amministratore/moderatore) e
   resolve_user_field_id_for_admins è abilitato, il componente chiama:
   • /admin/config/user-fields.json
     per mappare il valore configurato (nome del campo o user_field_X) al suo ID numerico.
3. Con l’ID numerico, controlla:
   • user_fields[id]
   • user_fields['user_field_' + id]
   • custom_fields[id]
   • custom_fields['user_field_' + id]

Qualsiasi valore vero in queste posizioni (ad esempio 1, true, yes, on, checked) disattiva le schede al passaggio del mouse per quell’utente.

Impostazioni per questo comportamento

• resolve_user_field_id_for_admins
  Se abilitato (consigliato), gli amministratori possono configurare il campo sia per nome che per user_field_X, e il componente risolverà e corrisponderà automaticamente l’ID numerico.

• debug_mode
  Se abilitato, registra informazioni dettagliate sul rilevamento nella console del browser per il personale, inclusi:

  • quali chiavi sono state controllate
  • dove è stata trovata una corrispondenza (utente corrente vs record utente completo)
  • l’ID numerico del campo utente risolto, se presente

---

Debug

Se le schede al passaggio del mouse non appaiono dove ti aspetti, utilizza la modalità di debug integrata:

1. Abilita debug_mode nelle impostazioni di questo componente.
2. Apri la console degli strumenti di sviluppo del browser.
3. Passa il mouse o tocca un collegamento a un argomento rilevante.

Vedrai messaggi simili a:

• Hover cards initialized – conferma l’inizializzazione e le posizioni abilitate.
• Resolved admin user-field mapping – conferma la mappatura del nome/chiave del campo utente configurato a un ID numerico (per il personale).
• No disable field match found anywhere – conferma che le schede al passaggio del mouse non vengono soppresse per l’utente corrente.

Per eseguire il debug dove dovrebbe apparire la scheda, verifica che:

• il tuo collegamento di destinazione sia un collegamento interno a un argomento (/t/...) che topicIdFromHref() può analizzare
• il flag di posizione rilevante sia abilitato:
  • 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]

Potresti aggiungere un link di anteprima funzionante o alcuni screenshot per mostrare come appare?