Desenvolvimento de Temas de Discurso e Componentes do Tema

Documentação Guias do Desenvolvedor
, ,
1

Discourse Themes and Theme Components can be used to customize the look, feel and functionality of Discourse’s frontend. This section of the developer guides aims to provide all the reference materials you need to develop simple themes for a single site, right up to complex open-source theme components.

This introduction aims to provide a map of all the tools and APIs for theme development. If you prefer a step-by-step tutorial for theme development, jump straight to:

Themes vs. Theme Components

Discourse Themes can be used to customize the frontend user experience using CSS and JavaScript. Each theme has its own git repository, and community admins can generally install and manage them via the Discourse admin panel, even on shared hosting platforms.

Theme Components are themes which are intended for use alongside other Theme Components, as part of an overall Theme. From a development point of view, Theme Components and Themes are almost identical. In these guides, the phrase “Theme” and “Theme Component” are used interchangeably.

Prerequisites

Firstly, make sure you understand how to use existing themes and theme components in Discourse. Using ready-made themes is the quickest and safest way to customize your community. If you need more, then it’s time to consider writing your own theme.

As part of Discourse’s overall architecture, Discourse Themes are built using standard HTML, CSS, JavaScript technologies, and make use of Ember concepts for more advanced UIs. These reference guides assume a base-level understanding of these technologies, and link out to external references where possible.

Discourse is a fast-moving project, and as such any custom theme will require maintenance over time. Make sure you consider this as part of your planning & development processes.

Getting Started

Frontend Customization

More!

Check out the rest of the Developer Guides !

This document is version controlled - suggest changes on github.

142 curtidas
136

Muitos links e referências antigos e/ou quebrados na seção The PluginApi - modifyClass()…\n\n[quote="Discourse, post:1, topic:93648"]\nhttps://github.com/discourse/discourse/blob/main/app/assets/javascripts/discourse/app/controllers/composer.js#L578\n[/quote]\n\nEste arquivo mudou tanto que checkReplyLength nem existe mais…\n\nE mais adiante na mesma seção:\n[quote="Discourse, post:1, topic:93648"]\nhttps://github.com/discourse/discourse/blob/master/app/assets/javascripts/discourse/app/components/discovery-categories.js\n[/quote]\n\nEste link resulta apenas em um erro de "404 - Página não encontrada"…\n\nDesisti de usar esta documentação depois disso…

4 curtidas
137

Uma postagem foi dividida em um novo tópico: Modelo ou widget de cartão de usuário?

138

A documentação parece um pouco desatualizada nesta parte.. (também api.modifyClass reclama sobre pluginId ausente). Como posso executar um script quando about-page é carregado? Este não parece funcionar (sem erros, no entanto). Tive resultados mistos com alguns outros componentes. Obrigado.

<script type="text/discourse-plugin" version="0.11.1">

api.modifyClass("component:about-page", {
  pluginId: 'discourse-about-theme',

  didInsertElement() {
    this._super(...arguments);
    console.log("Welcome to the about page!");
  }

});

</script>
1 curtida
139

Olá :wave: about-page agora está em .gjs, o que também significa que não pode mais ser modificado dessa forma. Se você quiser fazer alterações, terá que usar um dos conectores disponíveis nessa página.

Você pode verificar isso facilmente com o Componente de tema de locais de saída de plugin ou verificar no arquivo <PluginOutlet>.

4 curtidas
142

Muito obrigado. Faz sentido. Usei um conector em vez disso, funciona bem.

2 curtidas
143

Este guia ainda está preciso? Li tudo para tentar criar um componente de tema e depois olhei os componentes de tema de exemplo e nenhum deles usa as instruções que deveriam. Por exemplo, ao olhar o componente de tema discourse-brand-header, parece que ele foi reestruturado de usar coisas como api.createwidget no header.html para usar um código totalmente diferente com inicializadores, Componentes etc. Código extremamente complexo. O guia fala sobre usar o método da API com widgets, mas é isso que nenhum dos componentes usa. Existe um guia atualizado ou algo para usar Componentes?

Editar: Supostamente a API de widgets está desaparecendo, mas existem guias sobre o que usar em vez disso? Todo o guia aqui parece ser baseado em código que está obsoleto?

3 curtidas
144

É verdade. O guia deveria ser atualizado. No entanto, algumas partes ainda são bastante relevantes, como a estrutura de arquivos, etc.

2 curtidas
145

Sim, parece que SCSS é relevante, mas, caso contrário, parece que todos os componentes de tema de exemplo usam Componentes e foram refatorados para uma base de código totalmente diferente do que é ensinado aqui. Percorri todos os componentes que eles vinculam na seção Plugin API e cada um deles foi refatorado de uma maneira totalmente diferente do que é ensinado aqui no guia. Widgets não são mais usados. São todos Componentes. Existe um guia sobre como realmente usar corretamente os novos Componentes, já que os Widgets estão desaparecendo?

2 curtidas
146

Então me deparei com esta postagem, por exemplo, agora mesmo: Upcoming Header Changes - Preparing Themes and Plugins - então eles refatoraram tudo de widgets legados para componentes Glimmer? Mas este tutorial é todo sobre widgets legados. O que são componentes Glimmer exatamente e existem guias? Sinto-me sortudo por ter descoberto isso cedo, antes de começar a desenvolver com widgets legados. Talvez adicionar uma nota neste guia de que widgets são legados e não devem mais ser usados?

2 curtidas
147

Ok, entendi que Glimmer são novos componentes Ember. Mas, dei uma olhada no código do TOC do Discourse e, nossa… o que antes tinha tipo 10 linhas de código agora tem centenas de linhas em vários arquivos com classes complexas, decoradores etc. Imagino que Ember teve um momento React e decidiu que vamos complicar tudo novamente. Parece que os componentes de tema não são mais fáceis, com uma API de widget simples, mas exigem codificação extensiva…

2 curtidas
148

@ddsgad sim, você está certo, a maior parte deste guia está extremamente desatualizada. Tenho trabalhado em melhorias gerais na documentação recentemente e espero atualizar/substituir este nas próximas semanas.

Como você mencionou, exemplos do mundo real como o DiscoTOC podem ser uma boa referência. E aqui estão alguns guias específicos que estão mais atualizados:

Para informações gerais sobre Ember e seus componentes, recomendo consultar os guias do Ember.

6 curtidas
149

Obrigado por esses links. Muito útil. Atualmente, basicamente personalizamos coisas em um tópico do Discourse (primeira postagem) para criar designs melhores, então conseguimos fazer tudo com JavaScript puro (querySelectorAll etc.) e SCSS, então acho que continuaremos com isso por enquanto.

3 curtidas
150

O tutorial longo e desatualizado no OP foi substituído por informações introdutórias/de orientação mais gerais, incluindo um link para um tutorial de 7 etapas totalmente novo, que segue padrões de desenvolvimento de temas muito mais modernos.

4 curtidas
151

Eu li tudo, gostei! Bem explicado e uma ótima introdução!

3 curtidas
152

Adoro estes guias! Finalmente decifrei api.decorateCookedElement, obrigado novamente pela documentação útil!

4 curtidas