Esta guía explica cómo incrustar y mostrar una lista de temas de Discourse en sitios web externos utilizando JavaScript, lo que le permite mostrar contenido del foro como discusiones o anuncios en blogs, sitios web o plataformas de contenido externas.
Nivel de usuario requerido: Administrador
Resumen
Incrustar temas de Discourse en sitios web externos le permite mostrar listas de temas de su foro de Discourse directamente en otros sitios. Esta integración ayuda a dirigir tráfico a su foro y mantiene a su audiencia comprometida con el contenido de su comunidad. Los temas incrustados aparecen como un widget de JavaScript que se integra con la estructura DOM de su sitio, lo que facilita su personalización a través de CSS.
Habilitar la incrustación de temas
Para configurar la incrustación de temas en su sitio externo:
-
Navegue a su panel de administración de Discourse y haga clic en
site_settings. Busque y habilite la configuración del sitioembed_topics_list. -
Agregue el script de incrustación a la sección
<head>de HTML de su sitio externo:<script src="https://discourse.example.com/javascripts/embed-topics.js"></script>Reemplace
discourse.example.comcon la URL real de su foro de Discourse. -
Coloque el elemento de lista de temas donde desee mostrar los temas (por ejemplo, en una publicación de blog o en una página de sitio individual):
<d-topics-list discourse-url="https://discourse.example.com" category="1234" per-page="5"></d-topics-list> -
Si está incrustando temas en un dominio diferente al de su sitio de Discourse, agregue el dominio de su sitio externo a Admin > Avanzado > Incrustación > Hosts.
Por ejemplo, si su sitio de Discourse se encuentra en
yourdiscourseforum.comy desea incrustar temas enyourexternalsite.com, debe agregaryourexternalsite.coma su lista de Hosts permitidos.
No puede incrustar temas de un sitio de Discourse privado que requiera inicio de sesión.
Parámetros de configuración
El elemento d-topics-list admite los siguientes atributos para personalizar la visualización de sus temas:
discourse-url- La URL de su sitio de Discourse (requerido)template- Opciones de estilo de visualización:basic(predeterminado) - Muestra información mínima del temacomplete- Muestra título, nombre de usuario, avatar, fecha de creación y miniatura
per-page- Número de temas a mostrarcategory- ID de categoría para filtrar temas de una categoría específicatags- Filtrar temas por etiquetas específicasallow-create- Cuando se establece entrue, muestra un botón “Nuevo tema”top_period- Mostrar los temas principales de un período de tiempo específico:allyearlyquarterlymonthlyweeklydaily
Puede combinar varios parámetros para refinar la visualización de su lista de temas. Por ejemplo:
<d-topics-list
discourse-url="https://discourse.example.com"
category="5"
tags="announcements"
per-page="10"
template="complete">
</d-topics-list>
Personalización de la apariencia
Puede estilizar los temas incrustados utilizando SCSS personalizado en su panel de Admin > Personalizar > Temas. Haga clic en su tema actual o predeterminado y haga clic en Editar Código. Luego puede seleccionar Show_advanced y elegir CSS incrustado para agregar su código personalizado:
Aquí hay un ejemplo de SCSS para crear un diseño de cuadrícula:
.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%;
}
}
}
}
Mejores prácticas
- Utilice filtros de categorías y etiquetas significativos para mostrar contenido relevante para su audiencia.
- Establezca un valor apropiado de
per-pagepara evitar abrumar a los visitantes. - Pruebe sus temas incrustados en diferentes tamaños de pantalla para garantizar un diseño receptivo.
- Considere usar la plantilla
completepara una mejor apariencia visual cuando el espacio lo permita. - Revise regularmente su lista de Hosts permitidos para asegurarse de que solo los dominios autorizados puedan incrustar sus temas.
Problemas y soluciones comunes
Los temas no se muestran en el dominio externo
Problema: Los temas incrustados aparecen como un cuadro en blanco o gris cuando se ven en un dominio externo.
Solución: Agregue el dominio externo a los Admin > Personalizar > Incrustación > Hosts permitidos de su sitio de Discourse. Asegúrese de incluir el subdominio correcto (por ejemplo, si su sitio usa www.example.com, agregue www.example.com en lugar de solo example.com).
Errores de carga de scripts
Problema: El script de incrustación no se carga o devuelve errores de conexión.
Solución:
- Verifique que la URL de Discourse en la fuente de su script sea correcta y accesible.
- Verifique que la configuración del sitio
embed_topics_listesté habilitada. - Asegúrese de que su sitio de Discourse no requiera inicio de sesión para temas públicos.
Comportamiento del contexto SameSite
En contextos SameSite donde el sitio de incrustación y el foro comparten un dominio principal, Discourse respeta el estado de inicio de sesión y muestra los resultados en consecuencia. Los usuarios conectados pueden ver contenido de categorías seguras a las que los usuarios anónimos no pueden acceder.
Preguntas frecuentes
P: ¿Puedo incrustar temas de un sitio privado de Discourse?
R: No, la incrustación de temas solo funciona con sitios públicos de Discourse. Los sitios privados que requieren inicio de sesión no se pueden incrustar.
P: ¿Puedo incrustar varias listas de temas en la misma página?
R: Sí, puede incluir varios elementos <d-topics-list> en la misma página con diferentes parámetros para mostrar varias colecciones de temas.
P: ¿Cómo incrusto temas con imágenes destacadas?
R: Utilice el parámetro template="complete" en su elemento <d-topics-list> para mostrar temas con miniaturas e imágenes destacadas.
P: ¿Puedo cambiar dónde se abren los enlaces de temas?
R: Por defecto, los enlaces de temas se abren en la ventana principal. Puede modificar este comportamiento a través de la personalización de CSS o JavaScript.
