Schede di evidenziazione degli argomenti

[denvergeeks]

	Riepilogo	Fornisce popup in stile tooltip quando si passa il mouse sopra (o si tocca su mobile) i collegamenti interni ai topic per mostrare un’anteprima rapida del contenuto del topic collegato.
	Anteprima	Github Readme
	Repository	https://github.com/denvergeeks/discourse-topic-hover-cards
	Guida all’installazione	Come installare un tema o un componente del tema
	Nuovo a Discourse Themes?	Guida per principianti all’uso di Discourse Themes

Installa questo componente del tema

Ricche carte di anteprima hover per collegamenti interni ai topic in tutti i topic, le risposte, le liste dei topic, le home page delle categorie, le categorie di documentazione, le board Kanban e i topic suggeriti. Per Desktop e/o Mobile. A livello di sito e altamente configurabile.

Caratteristiche

• Può essere attivato a livello di sito per tutti i collegamenti interni ai topic, oppure solo per quelli che appaiono in una o più aree tra cui:
  • Corpo del topic (post originale)
  • Risposte
  • Liste standard dei topic (/latest, /top, /tags, liste dei topic per categoria, ecc.)
  • Liste dei topic nella home page delle categorie (Categorie + Ultime, Solo Categorie e layout correlati)
  • Visualizzazioni delle Categorie di Documentazione
  • Visualizzazioni delle board in stile Kanban
  • Topic suggeriti
• Layout responsivo:
  • Scheda desktop con densità e posizionamento dell’immagine in miniatura configurabili
  • Anteprima mobile a foglio inferiore 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, mi piace, ultima attività
• Disattivazione per utente tramite un campo utente personalizzato
• Modalità di debug riservata solo 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 hover, in millisecondi (predefinito: 300).

• enable_on_mobile
  Se abilitato, il tocco su un collegamento interno al topic supportato mostra un foglio di anteprima mobile fissato alla parte inferiore dello schermo.

• mobile_width_percent
  Larghezza del foglio di anteprima mobile come percentuale della larghezza della 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.

Questi sono paralleli ai pattern di “Densità” di Discourse e regolano semplicemente i padding e gli interlinea.

Miniatura e posizionamento

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

• thumbnail_placement
  Come è posizionata la miniatura su desktop:

  • top
  • left
  • right
  • bottom
    Su mobile, la miniatura viene sempre visualizzata nella parte superiore della scheda.

• image_size_percent
  Controlla la dimensione della miniatura come percentuale della dimensione della scheda hover renderizzata.

Campi per visualizzazione

Per ogni blocco seguente, 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 (utilizza 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 hover

• enable_on_topics
  Collegamenti ai topic nel post originale.

• enable_on_replies
  Collegamenti ai topic nelle risposte.

• enable_on_topic_lists
  Collegamenti ai topic nelle liste standard dei topic, ad esempio /latest, /top, liste dei topic per categoria.

• enable_on_category_homepage_topic_lists
  Collegamenti ai topic nelle liste “ultimi topic” o equivalenti nella home page delle categorie:

  • Categorie + Ultime
  • Solo Categorie
  • Varianti correlate visualizzate in / o /categories, a seconda di come è configurata la tua home page.

• enable_on_doc_categories
  Collegamenti ai topic nelle visualizzazioni delle Categorie di Documentazione (quando applicabile).

• enable_on_kanban_boards
  Collegamenti ai topic renderizzati nei layout delle board in stile Kanban (quando applicabile).

• enable_on_suggested_topic_links
  Collegamenti nella sezione “Topic suggeriti”.

---

Disattivazione per utente

Puoi consentire a singoli utenti di disabilitare le schede hover 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 nell’utente corrente. Può essere:
  • una chiave diretta di campo personalizzato, 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:
   • il user_preference_field_name configurato
   • lo stesso valore convertito tra 1 e user_field_1 quando appropriato
2. Se non viene trovata alcuna corrispondenza e l’utente corrente è 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 truthy in queste posizioni (ad esempio 1, true, yes, on, checked) disabilita le schede hover 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 con 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, tra cui:

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

---

Debug

Se le schede hover non appaiono dove ti aspetti, usa la modalità di debug integrata:

1. Abilita debug_mode nelle impostazioni di questo componente.
2. Apri la console degli strumenti per sviluppatori del browser.
3. Passa il mouse o tocca un collegamento al topic 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 hover non vengono soppresse per l’utente corrente.

Per debuggare dove dovrebbe apparire la scheda, verifica che:

• il tuo link di destinazione sia un collegamento interno al topic (/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

Impostazioni pianificate e funzionalità da aggiungere:

• Tag esclusi
• Tag inclusi
• Classi escluse
• Classi incluse
• Escludi OneBox e altri per impostazione predefinita
• Suggerimenti??

[chapoi]

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