Questa guida spiega come incorporare e visualizzare un elenco di argomenti Discourse su siti web esterni utilizzando JavaScript, consentendoti di mostrare contenuti del forum, come discussioni o annunci, su blog, siti web o piattaforme di contenuti esterne.
Livello utente richiesto: Amministratore
Riepilogo
Incorporare gli argomenti di Discourse su siti web esterni ti permette di visualizzare elenchi di argomenti dal tuo forum Discourse direttamente su altri siti. Questa integrazione aiuta a generare traffico verso il tuo forum e mantiene il tuo pubblico coinvolto con i contenuti della tua comunità. Gli argomenti incorporati appaiono come un widget JavaScript che si integra con la struttura DOM del tuo sito, rendendo più semplice la personalizzazione tramite CSS.
Abilitare l’incorporamento degli argomenti
Per configurare l’incorporamento degli argomenti sul tuo sito esterno:
- Vai su Admin > Avanzate > Incorporamento e passa alla scheda Impostazioni. Abilita l’impostazione del sito
embed_topics_list
- Aggiungi lo script di incorporamento alla sezione head HTML del tuo sito esterno:
<script src="https://discourse.example.com/javascripts/embed-topics.js"></script>
Sostituisci discourse.example.com con l’URL effettivo del tuo forum Discourse.
- Posiziona l’elemento dell’elenco degli argomenti dove desideri visualizzare gli argomenti (ad esempio in un post del blog o su una pagina individuale del sito):
<d-topics-list discourse-url="https://discourse.example.com" category="1234" per-page="5"></d-topics-list>
- Se stai incorporando argomenti su un dominio diverso dal tuo sito Discourse, aggiungi il dominio del tuo sito esterno a Admin > Avanzate > Incorporamento > Host
Ad esempio, se il tuo sito Discourse si trova su yourdiscourseforum.com e desideri incorporare argomenti su yourexternalsite.com, devi aggiungere yourexternalsite.com alla tua lista di Host consentiti.
Non è possibile incorporare argomenti da un sito Discourse privato che richiede l’accesso.
Parametri di configurazione
L’elemento d-topics-list supporta i seguenti attributi per personalizzare la visualizzazione degli argomenti:
discourse-url- L’URL del tuo sito Discourse (obbligatorio)template- Opzioni di stile di visualizzazione:basic(predefinito) - Mostra i titoli degli argomenti come collegamenticomplete- Mostra titolo, nome utente, avatar, data di creazione, ora dell’ultima risposta, numero di like, numero di risposte e immagine in evidenza/miniatura
per-page- Numero di argomenti da visualizzare (limitato dall’impostazione del sito nascostaembed_topic_limit_per_page, predefinito 200)category- ID categoria per filtrare gli argomenti da una categoria specificatags- Filtra gli argomenti per tag specificiallow-create- Se impostato su true, mostra un pulsante “Nuovo argomento”embed-class- Aggiunge una classe CSS personalizzata al contenitore dell’elenco degli argomenti incorporati (solo caratteri alfanumerici, trattini e trattini bassi)top-period- Mostra gli argomenti principali di un periodo di tempo specifico:allyearlyquarterlymonthlyweeklydaily
Puoi combinare più parametri per affinare la visualizzazione del tuo elenco di argomenti. Ad esempio:
<d-topics-list
discourse-url="https://discourse.example.com"
category="5"
tags="announcements"
per-page="10"
template="complete">
</d-topics-list>
Personalizzazione dell’aspetto
Puoi stilizzare gli argomenti incorporati utilizzando SCSS personalizzato nel pannello Admin > Aspetto > Temi e componenti. Clicca sul tuo tema corrente o predefinito e clicca su Modifica codice. Puoi quindi selezionare Show_advanced e scegliere CSS incorporato per aggiungere il tuo codice personalizzato:
Ecco un esempio di SCSS per creare un layout a griglia:
.topics-list {
display: grid;
grid-template-columns: repeat(2, 1fr);
.topic-list-item {
.main-link {
border: 1px dotted gray;
padding: 0;
}
.topic-column-wrapper {
flex-direction: column-reverse;
.topic-column.details-column {
width: 100%;
}
.topic-column.featured-image-column .topic-featured-image img {
max-width: initial;
max-height: initial;
width: 100%;
}
}
}
}
Best practice
- Utilizza filtri di categoria e tag significativi per mostrare contenuti pertinenti per il tuo pubblico
- Imposta un valore appropriato per
per-pageper evitare di sovraccaricare i visitatori - Testa i tuoi argomenti incorporati su diverse dimensioni dello schermo per garantire un design responsivo
- Considera l’uso del template
completeper un migliore impatto visivo quando lo spazio lo consente - Rivedi regolarmente la tua lista di Host consentiti per assicurarti che solo domini autorizzati possano incorporare i tuoi argomenti
Problemi comuni e soluzioni
Argomenti non visualizzati su dominio esterno
Problema: Gli argomenti incorporati appaiono come una casella vuota o grigia quando visualizzati su un dominio esterno.
Soluzione: Aggiungi il dominio esterno agli Host del tuo sito Discourse in Admin > Avanzate > Incorporamento > Host. Assicurati di includere il sottodominio corretto (ad esempio, se il tuo sito utilizza www.example.com, aggiungi www.example.com invece di solo example.com).
Errori di caricamento dello script
Problema: Lo script di incorporamento non riesce a caricarsi o restituisce errori di connessione.
Soluzione:
- Verifica che l’URL di Discourse nella sorgente dello script sia corretto e accessibile
- Controlla che l’impostazione del sito
embed_topics_listsia abilitata - Assicurati che il tuo sito Discourse non richieda l’accesso per gli argomenti pubblici
Comportamento nel contesto SameSite
In contesti SameSite in cui il sito di incorporamento e il forum condividono un dominio padre, Discourse rispetta lo stato di accesso e visualizza i risultati di conseguenza. Gli utenti loggati potrebbero vedere contenuti da categorie sicure a cui gli utenti anonimi non hanno accesso.
Domande frequenti
D: Posso incorporare argomenti da un sito Discourse privato?
R: No, l’incorporamento degli argomenti funziona solo con siti Discourse pubblici. I siti privati che richiedono l’accesso non possono essere incorporati.
D: Posso incorporare più elenchi di argomenti sulla stessa pagina?
R: Sì, puoi includere più elementi <d-topics-list> sulla stessa pagina con parametri diversi per visualizzare varie raccolte di argomenti.
D: Come incorporo argomenti con immagini in evidenza?
R: Utilizza il parametro template="complete" nel tuo elemento <d-topics-list> per visualizzare argomenti con miniature e immagini in evidenza.
D: Posso modificare dove si aprono i collegamenti agli argomenti?
R: Di default, i collegamenti agli argomenti si aprono nella finestra padre. Puoi modificare questo comportamento tramite personalizzazioni CSS o JavaScript.
