Este guia explica como incorporar e exibir uma lista de tópicos do Discourse em sites externos usando JavaScript, permitindo que você exiba conteúdo do fórum, como discussões ou anúncios, em blogs, sites ou plataformas de conteúdo externas.
Nível de usuário necessário: Administrador
Resumo
Incorporar tópicos do Discourse em sites externos permite exibir listas de tópicos do seu fórum Discourse diretamente em outros sites. Essa integração ajuda a direcionar tráfego para o seu fórum e mantém seu público engajado com o conteúdo da sua comunidade. Os tópicos incorporados aparecem como um widget JavaScript que se integra à estrutura DOM do seu site, facilitando a personalização via CSS.
Habilitar incorporação de tópicos
Para configurar a incorporação de tópicos no seu site externo:
- Navegue até o painel de administração do Discourse e clique em
site_settings. Procure e habilite a configuração de siteembed_topics_list.
- Adicione o script de incorporação à seção
<head>do HTML do seu site externo:
<script src="https://discourse.example.com/javascripts/embed-topics.js"></script>
Substitua discourse.example.com pelo URL real do seu fórum Discourse.
- Coloque o elemento da lista de tópicos onde você deseja exibir os tópicos (como em uma postagem de blog ou em uma página de site individual):
<d-topics-list discourse-url="https://discourse.example.com" category="1234" per-page="5"></d-topics-list>
- Se você estiver incorporando tópicos em um domínio diferente do seu site Discourse, adicione o domínio do seu site externo em Admin > Avançado > Incorporação > Hosts.
Por exemplo, se o seu site Discourse estiver localizado em seufórumdiscourse.com e você quiser incorporar tópicos em seusiteexterno.com, você precisa adicionar seusiteexterno.com à sua lista de Hosts Permitidos.
Você não pode incorporar tópicos de um site Discourse privado que exija login.
Parâmetros de configuração
O elemento d-topics-list suporta os seguintes atributos para personalizar a exibição dos seus tópicos:
discourse-url- O URL do seu site Discourse (obrigatório)template- Opções de estilo de exibição:basic(padrão) - Exibe informações mínimas do tópicocomplete- Exibe título, nome de usuário, avatar, data de criação e miniatura
per-page- Número de tópicos a serem exibidoscategory- ID da categoria para filtrar tópicos de uma categoria específicatags- Filtrar tópicos por tags específicasallow-create- Quando definido comotrue, exibe um botão “Novo Tópico”top_period- Exibir os tópicos mais populares de um período específico:allyearlyquarterlymonthlyweeklydaily
Você pode combinar vários parâmetros para refinar a exibição da sua lista de tópicos. Por exemplo:
<d-topics-list
discourse-url="https://discourse.example.com"
category="5"
tags="announcements"
per-page="10"
template="complete">
</d-topics-list>
Personalizando a aparência
Você pode estilizar os tópicos incorporados usando SCSS personalizado no seu painel Admin > Personalizar > Temas. Clique no seu tema atual ou padrão e clique em Editar Código. Você pode então selecionar Show_advanced e escolher Embedded CSS para adicionar seu código personalizado:
Aqui está um exemplo de SCSS para criar um layout de grade:
.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%;
}
}
}
}
Melhores práticas
- Use filtros de categoria e tag significativos para exibir conteúdo relevante para seu público
- Defina um valor apropriado para
per-pagepara evitar sobrecarregar os visitantes - Teste seus tópicos incorporados em diferentes tamanhos de tela para garantir um design responsivo
- Considere usar o template
completepara um melhor apelo visual quando o espaço permitir - Revise regularmente sua lista de Hosts Permitidos para garantir que apenas domínios autorizados possam incorporar seus tópicos
Problemas comuns e soluções
Tópicos não são exibidos no domínio externo
Problema: Os tópicos incorporados aparecem como uma caixa em branco ou cinza quando visualizados em um domínio externo.
Solução: Adicione o domínio externo aos Admin > Personalizar > Incorporação > Hosts Permitidos do seu site Discourse. Certifique-se de incluir o subdomínio correto (por exemplo, se o seu site usa www.example.com, adicione www.example.com em vez de apenas example.com).
Erros de carregamento de script
Problema: O script de incorporação falha ao carregar ou retorna erros de conexão.
Solução:
- Verifique se o URL do Discourse na sua fonte de script está correto e acessível
- Verifique se a configuração de site
embed_topics_listestá habilitada - Certifique-se de que seu site Discourse não exija login para tópicos públicos
Comportamento do contexto SameSite
Em contextos SameSite onde o site de incorporação e o fórum compartilham um domínio pai, o Discourse respeita o status de login e exibe os resultados de acordo. Usuários logados podem ver conteúdo de categorias seguras que usuários anônimos não podem acessar.
FAQs
P: Posso incorporar tópicos de um site Discourse privado?
R: Não, a incorporação de tópicos só funciona com sites Discourse públicos. Sites privados que exigem login não podem ser incorporados.
P: Posso incorporar várias listas de tópicos na mesma página?
R: Sim, você pode incluir vários elementos <d-topics-list> na mesma página com parâmetros diferentes para exibir várias coleções de tópicos.
P: Como incorporo tópicos com imagens em destaque?
R: Use o parâmetro template="complete" no seu elemento <d-topics-list> para exibir tópicos com miniaturas e imagens em destaque.
P: Posso alterar onde os links dos tópicos são abertos?
R: Por padrão, os links dos tópicos são abertos na janela pai. Você pode modificar esse comportamento por meio de personalização CSS ou JavaScript.
