Este guia explica como incorporar e exibir uma lista de tópicos do Discourse em sites externos usando JavaScript, permitindo que você mostre 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 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 por meio de CSS.
Habilitar incorporação de tópicos
Para configurar a incorporação de tópicos no seu site externo:
- Acesse Admin > Avançado > Incorporação e alterne para a aba Configurações. Habilite a configuração do site
embed_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 pela URL real do seu fórum Discourse.
- Coloque o elemento da lista de tópicos onde deseja exibi-los (como em uma postagem de blog ou em uma página individual do site):
<d-topics-list discourse-url="https://discourse.example.com" category="1234" per-page="5"></d-topics-list>
- Se 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 seu site Discourse estiver localizado em yourdiscourseforum.com e você quiser incorporar tópicos em yourexternalsite.com, precisará adicionar yourexternalsite.com à sua lista de Hosts Permitidos.
Você não pode incorporar tópicos de um site Discourse privado que exige 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- A URL do seu site Discourse (obrigatório)template- Opções de estilo de exibição:basic(padrão) - Mostra os títulos dos tópicos como linkscomplete- Mostra título, nome de usuário, avatar, data de criação, hora da última resposta, número de curtidas, número de respostas e imagem em destaque/miniatua
per-page- Número de tópicos a exibir (limitado pela configuração do site ocultaembed_topic_limit_per_page, padrão 200)category- ID da categoria para filtrar tópicos de uma categoria específicatags- Filtrar tópicos por tags específicasallow-create- Quando definido como true, mostra um botão “Novo Tópico”embed-class- Adiciona uma classe CSS personalizada ao contêiner da lista de tópicos incorporada (apenas caracteres alfanuméricos, hífens e sublinhados)top-period- Mostrar os principais tópicos 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 painel Admin > Aparência > Temas e Componentes. Clique no seu tema atual ou padrão e clique em Editar Código. Em seguida, selecione Show_advanced e escolha CSS Incorporado para adicionar seu código personalizado:
Aqui está um exemplo de SCSS para criar um layout em 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 não sobrecarregar os visitantes - Teste seus tópicos incorporados em diferentes tamanhos de tela para garantir design responsivo
- Considere usar o modelo
completepara melhor apelo visual quando houver espaço disponível - 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 exibidos em 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 Hosts do seu site Discourse em Admin > Avançado > Incorporação > Hosts. Certifique-se de incluir o subdomínio correto (por exemplo, se seu site usa www.example.com, adicione www.example.com em vez de apenas example.com).
Erros de carregamento do script
Problema: O script de incorporação falha ao carregar ou retorna erros de conexão.
Solução:
- Verifique se a URL do Discourse na origem do seu script está correta e acessível
- Confirme se a configuração do site
embed_topics_listestá habilitada - Garanta 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 têm acesso.
Perguntas frequentes
P: Posso incorporar tópicos de um site Discourse privado?
R: Não, a incorporação de tópicos funciona apenas 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 abrem?
R: Por padrão, os links dos tópicos abrem na janela pai. Você pode modificar esse comportamento por meio de personalização com CSS ou JavaScript.
