Esta guía explica cómo incrustar y mostrar una lista de temas de Discourse en sitios web externos usando JavaScript, permitiéndote exhibir 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 te permite mostrar listas de temas de tu foro de Discourse directamente en otros sitios. Esta integración ayuda a dirigir tráfico a tu foro y mantiene a tu audiencia comprometida con el contenido de tu comunidad. Los temas incrustados aparecen como un widget de JavaScript que se integra con la estructura DOM de tu sitio, facilitando la personalización mediante CSS.
Habilitar la incrustación de temas
Para configurar la incrustación de temas en tu sitio externo:
- Navega a Admin > Avanzado > Incrustación y cambia a la pestaña Configuración. Habilita la configuración del sitio
embed_topics_list.
- Agrega el script de incrustación a la sección
<head>del HTML de tu sitio externo:
<script src="https://discourse.example.com/javascripts/embed-topics.js"></script>
Reemplaza discourse.example.com con la URL real de tu foro de Discourse.
- Coloca el elemento de lista de temas donde quieras mostrar los temas (por ejemplo, en una entrada de blog o en una página individual del sitio):
<d-topics-list discourse-url="https://discourse.example.com" category="1234" per-page="5"></d-topics-list>
- Si estás incrustando temas en un dominio diferente al de tu sitio de Discourse, agrega el dominio de tu sitio externo a Admin > Avanzado > Incrustación > Hosts.
Por ejemplo, si tu sitio de Discourse está ubicado en tuforo.com y quieres incrustar temas en tusitioexterno.com, debes agregar tusitioexterno.com a tu lista de Hosts permitidos.
No puedes 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 tus temas:
discourse-url- La URL de tu sitio de Discourse (obligatorio)template- Opciones de estilo de visualización:basic(predeterminado) - Muestra los títulos de los temas como enlacescomplete- Muestra título, nombre de usuario, avatar, fecha de creación, hora de la última respuesta, número de me gusta, número de respuestas e imagen destacada/vignette
per-page- Número de temas a mostrar (limitado por la configuración oculta del sitioembed_topic_limit_per_page, predeterminado 200)category- 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”embed-class- Agrega una clase CSS personalizada al contenedor de la lista de temas incrustados (solo alfanuméricos, guiones y guiones bajos)top-period- Mostrar los mejores temas de un período de tiempo específico:allyearlyquarterlymonthlyweeklydaily
Puedes combinar múltiples parámetros para refinar la visualización de tu lista de temas. Por ejemplo:
<d-topics-list
discourse-url="https://discourse.example.com"
category="5"
tags="anuncios"
per-page="10"
template="complete">
</d-topics-list>
Personalizar la apariencia
Puedes estilizar los temas incrustados usando SCSS personalizado en tu panel Admin > Apariencia > Temas y componentes. Haz clic en tu tema actual o predeterminado y luego en Editar código. Luego, puedes seleccionar Show_advanced y elegir CSS incrustado para agregar tu código personalizado:
Aquí tienes 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
- Usa filtros de categoría y etiquetas significativos para mostrar contenido relevante para tu audiencia.
- Establece un valor
per-pageadecuado para no abrumar a los visitantes. - Prueba tus temas incrustados en diferentes tamaños de pantalla para asegurar un diseño responsivo.
- Considera usar la plantilla
completepara un mejor atractivo visual cuando el espacio lo permita. - Revisa regularmente tu lista de Hosts permitidos para asegurar que solo los dominios autorizados puedan incrustar tus temas.
Problemas comunes y soluciones
Los temas no se muestran en un dominio externo
Problema: Los temas incrustados aparecen como un cuadro en blanco o gris cuando se ven en un dominio externo.
Solución: Agrega el dominio externo a Admin > Avanzado > Incrustación > Hosts de tu sitio de Discourse. Asegúrate de incluir el subdominio correcto (por ejemplo, si tu sitio usa www.ejemplo.com, agrega www.ejemplo.com en lugar de solo ejemplo.com).
Errores de carga del script
Problema: El script de incrustación falla al cargar o devuelve errores de conexión.
Solución:
- Verifica que la URL de Discourse en el origen de tu script sea correcta y accesible.
- Comprueba que la configuración del sitio
embed_topics_listesté habilitada. - Asegúrate de que tu sitio de Discourse no requiera inicio de sesión para temas públicos.
Comportamiento en contextos 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 iniciados pueden ver contenido de categorías seguras a las que los usuarios anónimos no tienen acceso.
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 pueden ser incrustados.
P: ¿Puedo incrustar múltiples listas de temas en la misma página?
R: Sí, puedes incluir múltiples elementos <d-topics-list> en la misma página con diferentes parámetros para mostrar diversas colecciones de temas.
P: ¿Cómo incrusto temas con imágenes destacadas?
R: Usa el parámetro template="complete" en tu elemento <d-topics-list> para mostrar temas con miniaturas e imágenes destacadas.
P: ¿Puedo cambiar dónde se abren los enlaces de los temas?
R: Por defecto, los enlaces de los temas se abren en la ventana principal. Puedes modificar este comportamiento mediante personalización con CSS o JavaScript.
