Alterações na lista de tópicos futuras - como preparar temas e plugins

[david (David Taylor)]

Como parte de nossa busca contínua para padronizar os sistemas de renderização no código do Discourse, estamos substituindo a implementação da lista de tópicos.

Anteriormente, isso usava uma abordagem de ‘raw handlebars’ (.hbr) e podia ser personalizado por meio de substituições de template e raw-plugin-outlets. A nova implementação da lista de tópicos usa componentes Glimmer modernos e foi construída do zero para ser personalizável de maneiras sustentáveis.

A nova implementação já está disponível por meio da configuração glimmer_topic_list_mode.

• disabled: usa a lista de tópicos legada “raw handlebars”.
• auto: detectará a compatibilidade de seus plugins e temas atuais. Se algum for incompatível, usará o sistema legado; caso contrário, usará a nova implementação.
• enabled: usará a nova implementação da lista de tópicos. Se você tiver plugins ou temas incompatíveis, seu site poderá quebrar.

Já atualizamos a maioria de nossos temas e plugins oficiais para serem compatíveis com o novo menu. No entanto, se você usa plugins, temas ou componentes de tema de terceiros que personalizam a lista de tópicos, será necessário atualizá-los.

Avisos serão exibidos no console do navegador identificando a origem da incompatibilidade.

Cronograma de Implementação

Estas são estimativas aproximadas sujeitas a alterações

Q4 2024:

• implementação principal concluída
• atualização de temas/plugins oficiais (em andamento)
• habilitado no Meta
• publicado conselhos de atualização

Q1 2025:

• atualização de temas/plugins oficiais

• glimmer_topic_list_mode definido como auto; mensagens de depreciação no console habilitadas

• depreciações acionarão um banner de aviso para administradores para quaisquer problemas restantes

• plugins e temas de terceiros devem ser atualizados

• 1º de março - habilitação da nova lista de tópicos para todos os sites. O padrão para a configuração do site será alterado para enabled, mas ainda será possível retornar para ‘disabled’.

Q2 2025

• após 1º de abril - remoção final do modo legado e código associado

O que isso significa para mim?

Se seu plugin ou tema tiver arquivos ‘raw handlebars’ (nomeados .hbr ou .raw.hbs), eles precisarão ser atualizados para compatibilidade com a nova versão. Arquivos .hbs regulares para componentes/rotas Ember não são afetados por esta alteração.

Atualizações também serão necessárias se você usar modifyClass em component:topic-list ou component:topic-list-item.

Se o seu site tiver alguma dessas personalizações incompatíveis, mensagens de aviso serão exibidas no console do desenvolvedor do navegador, incluindo informações sobre qual tema/plugin é a causa.

Quais são as substituições?

Alguns dos antigos raw-plugin-outlets foram convertidos para Plugin Outlets regulares. Eles podem ser atualizados de forma 1:1.

Personalizações mais avançadas precisarão ser avaliadas caso a caso. A nova lista de tópicos possui várias novas APIs para personalização fácil e robusta. Saiba mais aqui:

Customizing the topic list

The topic-list is one of the most-used and most-customized user-interfaces in Discourse. There are many different tools available to theme and plugin developers to achieve this customization, each with their own advantages, disadvantages and maintenance considerations. CSS-based Customization The safest and most common customization method is CSS. As with any other Discourse customization: the more complex your changes, the more maintenance is likely to be required in your theme or plugin. Gen…

Aqui estão alguns exemplos:

• discourse-assign introduz uma nova coluna para uma lista de tópicos específica

• discourse-calendar usa um dos novos plugin outlets para exibir o badge da data do evento

• discourse-solved usa um novo valueTransformer para substituir o modifyClass anterior

E quanto a outras personalizações?

Se sua personalização não puder ser alcançada usando as novas APIs que introduzimos, por favor, nos informe criando um novo tópico Dev para discutir.

Sou um autor de plugin/tema. Como atualizo um tema/plugin para suportar a lista de tópicos antiga e nova durante a transição?

Os novos plugin outlets são renderizados em ambas as implementações, antiga e nova, da lista de tópicos. Então: quando você tiver implementado o novo, simplesmente exclua o conector raw-plugin-outlet antigo.

Para personalizações baseadas em DAG que substituem template-overrides ou outlets não modernizados, você precisará manter ambas as implementações durante o período de transição.

Depois que seu tema/plugin suportar ambas as implementações, antiga e nova, você poderá adicionar este comentário mágico no topo de todos os seus arquivos .hbr:

{{!-- has-modern-replacement --}}

Isso silenciará as mensagens de depreciação e permitirá que a nova implementação seja usada quando estiver em modo “auto”.

[pfaffman (Jay Pfaffman)]

@david

Se o seu plugin ou tema tiver algum arquivo ‘raw handlebars’ (nomeado .hbr ou .raw.hbs), ele precisará ser atualizado para compatibilidade com a nova versão.

Desculpe ser chato, mas isso realmente não significa algo mais como “se o seu plugin ou tema tiver algum arquivo ‘raw handlebars’ que tenha algo a ver com a lista de tópicos, então eles precisam ser atualizados”

Meus arquivos raw handlebars que têm a ver com outros modelos continuarão bem, certo? Ou os arquivos raw handlebars estão desaparecendo completamente? (Acho que eles são necessários para modelos/rotas adicionais, certo?)

[david (David Taylor)]

“Raw handlebars” significa nossos modelos específicos do discourse, que têm a extensão de arquivo .hbr (ou historicamente .raw.hbs). Usamos esse sistema apenas para a lista de tópicos e alguns internos de ‘autocompletar’.

Outros arquivos .hbs (por exemplo, para componentes Ember ou rotas) não são afetados.

Atualizarei o OP para deixar isso mais claro. Obrigado @pfaffman!

Editar: aqui vamos nós:

@david

Se seu plugin ou tema tiver algum arquivo de ‘raw handlebars’ (nomeado .hbr ou .raw.hbs), eles precisarão ser atualizados para compatibilidade com a nova versão. Arquivos .hbs regulares para componentes/rotas Ember não são afetados por esta alteração.

[pfaffman (Jay Pfaffman)]

@david

“Raw handlebars” significa nossos templates específicos do Discourse, que têm a extensão de arquivo .hbr (ou historicamente .raw.hbs).

Ah. Você realmente tentou deixar claro. Você declarou explicitamente as extensões. Acho que não dá para deixar mais claro. Acho que desta vez a culpa é minha.

Mas talvez adicionar a frase extra teria me ajudado a conseguir ler.

[Don]

Obrigado por compartilhar. Tenho medo disso há muito tempo e está chegando… Não parecerá uma corrida fácil… Mas o transformador de valor provavelmente facilitará.

[merefield (Robert)]

Acredito que GitHub - discourse/discourse-topic-excerpts: Add topic excerpts to all topics in the topic list ainda não foi atualizado?

[david (David Taylor)]

Sim, ainda temos muitos temas/plugins oficiais pendentes de atualização. Vou estender esse item para o Q1 no OP

[merefield (Robert)]

Obrigado! Estou gostando da experiência do desenvolvedor até agora! Avisarei se o TLP levantar algum problema quando eu chegar a isso.

[david (David Taylor)]

Legal! A topic-list-thumbnails oficial é uma das que terminamos de atualizar, então pode servir como uma referência útil.

[david (David Taylor)]

@merefield

Acredito que GitHub - discourse/discourse-topic-excerpts: Add topic excerpts to all topics in the topic list ainda não foi atualizado?

@david

Sim, ainda temos muitos temas/plugins oficiais pendentes de atualização

Ah, foi mal! @isaac atualizou o topic-excerpts na semana passada: DEV: Update plugin for `glimmer-topic-list` (#34) · discourse/discourse-topic-excerpts@0dd3c6c · GitHub

Então deve estar funcionando bem com a nova lista de tópicos

[merefield (Robert)]

Estou recebendo:

Ambas as versões estão atualizadas

[merefield (Robert)]

@david

discourse-assign introduz uma nova coluna para uma lista de tópicos específica.

Ao adicionar uma coluna, qual é a maneira estratégica de adicionar um cabeçalho de coluna classificável?

usando:

api.registerValueTransformer("topic-list-header-sortable-column"

além do outro transformador?

      api.registerValueTransformer(
        "topic-list-columns",

não parece fazer isso por conta própria?

[david (David Taylor)]

@merefield

Estou recebendo:

cc @isaac. Se eu tivesse que adivinhar: talvez a nova lógica precise ser atualizada para lidar com tópicos não categorizados?

@merefield

qual é a maneira estratégica de adicionar um cabeçalho de coluna classificável?

O transformador que você encontrou serve para substituir a classificabilidade de colunas existentes (por exemplo, nós o fazemos no discourse-calendar para impedir que outros métodos de classificação sejam usados quando você está na visualização cronológica de tópicos)

Se você estiver adicionando uma nova coluna, então você deve ser capaz de definir seu cabeçalho usando o componente SortableColumn. por exemplo, aqui está um no core:

app/assets/javascripts/discourse/app/components/topic-list/header/activity-cell.gjs

app/assets/javascripts/discourse/app/components/topic-list/list.gjs

(uma coisa que é realmente legal sobre a nova API é que todas as colunas principais são definidas usando a mesma API que você usa de temas/plugins!)

[merefield (Robert)]

@david

as colunas principais são definidas usando a mesma API que você usa de temas/plugins!

sim, notei isso quando fiz uma pesquisa de código, legal!

[isaac (Isaac Janzen)]

@david

cc @isaac. Se eu tivesse que adivinhar: talvez a nova lógica precise ser atualizada para lidar com tópicos não categorizados?

Fixed

[merefield (Robert)]

Q: É possível atribuir um Componente completo a uma Célula, não apenas um <template>?

Por exemplo, e se eu quisesse exibir um botão transparente em uma célula que exigisse uma lógica mínima de javascript?

[david (David Taylor)]

@merefield

P: É possível atribuir um Componente completo a uma Célula, não apenas um <template>?

Sim! Tecnicamente, uma tag <template> simples está tecnicamente criando um "Componente Apenas de Template". Semelhante ao tipo de componente que você obtém quando coloca um arquivo .hbs simples no diretório components/.

Portanto, sim, importar e passar uma classe de componente normal funcionará da mesma forma. Funcionará até mesmo com componentes clássicos! (embora, obviamente, recomendemos o uso dos componentes Glimmer mais modernos).

[merefield (Robert)]

isso é totalmente incrível!

isso muda… muita coisa!

[merefield (Robert)]

Pergunta boba, talvez.

Mas como aplicar alterações em… tópico-lista móvel?

[david (David Taylor)]

Para dispositivos móveis, temos vários novos pontos de conexão de plugin (incluindo pontos de conexão de wrapper).

Ou, alternativamente, você pode usar um valueTransformer para forçar a visualização desktop em todos os lugares (fazemos isso para topic-thumbnails).

Estou planejando escrever um guia mais detalhado de "como personalizar a lista de tópicos" em Documentation > Developer Guides na próxima semana, então com certeza incluirei essas informações lá.