Recentemente, trabalhamos na atualização do cabeçalho do Discourse, migrando do sistema de renderização legado ‘widget’ para componentes modernos Glimmer. Essa mudança já está disponível no núcleo do Discourse, por meio da configuração de site glimmer header mode.
Cronograma Aproximado
(estimativas muito preliminares — sujeitas a alterações em qualquer direção)
T1 2024:
-
implementação no núcleo concluída e ativada no Meta -
publicação de orientações sobre atualização; mensagens de descontinuação habilitadas no console
-
início do trabalho para atualizar todos os plugins e temas oficiais e de terceiros
T2 2024:
-
início da ativação da nova implementação do cabeçalho como padrão
-
temas e plugins oficiais e de terceiros prontos para a atualização
-
mensagens de descontinuação passam a acionar um banner de aviso para administradores em caso de problemas remanescentes
T3 2024:
-
tópico de anúncio publicado para maior visibilidade: Preparing your community for behind-the-scenes header changes
-
semana de 5 de agosto de 2024 (v3.4.0.beta1): novo cabeçalho ativado para todos os sites por padrão. Ainda será possível que administradores voltem ao cabeçalho antigo alterando a configuração de site
glimmer header mode. -
semana de 2 de setembro de 2024: remoção final da flag de recurso e do código legado
O Que Isso Significa para Mim?
Se seu plugin ou tema utiliza alguma API de ‘widget’ para personalizar o cabeçalho, essas precisarão ser atualizadas para compatibilidade com o novo cabeçalho.
Como Posso Testar o Novo Cabeçalho?
Na versão mais recente do Discourse, o novo cabeçalho é ativado automaticamente quando todos os seus temas/plugins são compatíveis.
Se seus temas/plugins não forem compatíveis, o cabeçalho legado continuará sendo usado, e um aviso será exibido no console junto às mensagens de descontinuação existentes. Um banner de aviso também será mostrado aos administradores na interface.
No improvável evento de esse sistema automático não funcionar como esperado, você pode substituir temporariamente essa ‘flag de recurso automática’ por meio da configuração de site glimmer header mode. Se fizer isso, por favor, informe-nos o motivo neste tópico.
Preciso Atualizar Meu Plugin/Tema?
Para determinar se sua personalização precisa ser atualizada, verifique se ela usa decorateWidget, changeWidgetSetting, reopenWidget ou attachWidgetAction em qualquer um desses widgets:
- header
- site-header
- header-contents
- header-buttons
- user-status-bubble
- sidebar-toggle
- header-icons
- header-topic-info
- header-notifications
- home-logo
- user-dropdown
ou se utiliza um dos seguintes métodos da API de plugin:
addToHeaderIconsaddHeaderPanel
Todas essas ações agora gerarão mensagens de descontinuação no console. Os IDs de descontinuação são:
discourse.add-header-paneldiscourse.header-widget-overrides
Se você usa mais de um tema na sua instância, certifique-se de verificar todos eles.
Aviso ao administrador
A partir de 20 de junho de 2024, ativamos o aviso ao administrador para as descontinuações acima.
Se sua instância foi implantada após essa data e seus plugins, temas ou componentes de tema atuais acionarem um dos avisos de descontinuação, a seguinte mensagem será exibida apenas para administradores*:
Essa mensagem serve apenas para alertar os administradores de que precisam agir em breve para modernizar as personalizações afetadas: as personalizações antigas continuarão funcionando até que removamos a base de código legado.
Quais São as Substituições?
Cada tema/plugin é diferente, mas aqui estão algumas orientações para os casos de uso mais comuns:
addToHeaderIcons
Para ícones personalizados no cabeçalho, recomendamos remover seu código e instalar o componente oficial de tema Custom Header Links (Icons). Se isso não atender às suas necessidades, veja abaixo detalhes sobre as alterações de código necessárias:
A API de plugin addToHeaderIcons foi descontinuada em favor da nova API headerIcons. Ela permite adicionar, remover ou reordenar ícones no cabeçalho. É necessário passar um Componente.
O componente pode ser passado da seguinte forma:
| Antes | Depois |
|---|---|
| api.addToHeaderIcons(“widget-foo”) | api.headerIcons.add(“foo”, FooIcon) |
| api.decorateWidget(“header-icons:before”, () => return helper.h(“div”, “widget-foo”)) | api.headerIcons.add(“foo”, FooIcon, { before: “search” }) |
| api.decorateWidget(“header-icons:after”, () => return helper.h(“div”, “widget-foo”)) | api.headerIcons.add(“foo”, FooComponent, { after: “search” }) |
Este exemplo usa o Formato de Tag de Template (gjs) do Ember para definir um componente inline e passá-lo à API headerButtons.add:
// .../discourse/api-initializers/add-my-button.gjs
import DButton from "discourse/components/d-button";
import { apiInitializer } from "discourse/lib/api";
export default apiInitializer("1.0", (api) => {
api.headerIcons.add("some-unique-name", <template>
<li><DButton class="icon btn-flat" @href="/u" @icon="address-book" /></li>
</template>);
});
Ou, para um menu suspenso, você pode usar <DMenu em vez de <DButton:
import DButton from "discourse/components/d-button";
import { apiInitializer } from "discourse/lib/api";
import DMenu from "float-kit/components/d-menu";
export default apiInitializer("1.0", (api) => {
api.headerIcons.add("some-unique-name", <template>
<li>
<DMenu class="icon btn-flat" @icon="address-book">
<DButton @translatedLabel="Usuário 1" @href="/u/user1" />
<DButton @translatedLabel="Usuário 2" @href="/u/user2" />
<DButton @translatedLabel="Usuário 3" @href="/u/user3" />
</DMenu>
</li>
</template>);
});
Exemplos de commits de atualização:
discourse-icon-header-linksdecorateWidget("header-buttons:*")
O widget header-buttons foi descontinuado e introduzimos uma nova API de plugin headerButtons. Ela permite adicionar, remover ou reordenar botões no cabeçalho. É necessário passar um Componente.
| Antes | Depois |
|---|---|
| api.decorateWidget(“header-buttons:before”) | api.headerButtons(“button-name”, ButtonComponent, { before: “auth” }) |
| api.decorateWidget(“header-buttons:after”) | api.headerButtons(“button-name”, ButtonComponent, { after: “auth” }) |
changeWidgetSetting(...) para widgets do cabeçalho
changeWidgetSettingpodem ser realizados usando estes componentes de tema:Se esses não se adequarem ao seu caso de uso, continue lendo…
Algumas personalizações nos widgets do cabeçalho usavam a API changeWidgetSetting.
Embora não haja substituição direta para personalizações como a acima, devido ao funcionamento dos campos dos componentes Glimmer, introduzimos uma nova API de plugin no Discourse 3.3.0.beta3 para lidar com alguns desses casos.
registerValueTransformer pode ser usado para substituir valores marcados no código-fonte como substituíveis, uma abordagem semelhante à forma como funcionam as saídas de plugin.
Já adicionamos dois transformadores para os casos de uso mais comuns em nossa base de código:
-
home-logo-href: pode ser usado para substituir a URL no link do logotipo inicial. Veja a seçãohome-logoabaixo para exemplos. -
header-notifications-avatar-size: pode ser usado para alterar o tamanho da imagem carregada para o avatar do usuário no cabeçalho. Exemplo:
O código abaixo:
api.changeWidgetSetting(
"header-notifications",
"avatarSize",
settings.header_avatars_size
);
Seria convertido para:
api.registerValueTransformer(
"header-notifications-avatar-size",
() => settings.header_avatars_size
);
Esses transformadores precisam ser adicionados ao código-fonte do Discourse. Se precisar de um diferente, por favor, informe-nos postando seu caso de uso abaixo.
Mais detalhes sobre as novas APIs de transformador de valor podem ser encontrados aqui.
home-logo
Introduzimos uma saída de plugin chamada home-logo em substituição às decorações de widget home-logo:before ou home-logo:after. Você pode utilizar a nomenclatura automática __before e __after em seu arquivo de conector para especificar onde seu conteúdo personalizado deve ser colocado.
Mais detalhes sobre a nomenclatura de arquivos de conector antes/depois podem ser encontrados aqui.
| Antes | Depois |
|---|---|
| api.decorateWidget(“home-logo:before”) | Mover conteúdo para /connectors/home-logo__before |
| api.decorateWidget(“header-buttons:after”) | Mover conteúdo para /connectors/home-logo__after) |
Alterando a URL do link do home-logo:
Uma necessidade muito comum é alterar a URL para a qual o home-logo aponta. Introduzimos o transformador de valor home-logo-href para resolver isso. Exemplos:
-
para alterar o link para uma URL estática
api.registerValueTransformer("home-logo-href", () => "https://example.com"); -
para retornar uma URL dinâmica com base no usuário atual
api.registerValueTransformer("home-logo-href", () => { const currentUser = api.getCurrentUser(); return `https://example.com/${currentUser.username}`; }); -
para retornar uma URL com base em uma configuração de componente de tema
api.registerValueTransformer("home-logo-href", () => { return settings.example_logo_url_setting; });
E outras personalizações?
Se sua personalização não puder ser realizada usando CSS, PluginOutlets ou as novas APIs que introduzimos, por favor, informe-nos criando um novo tópico em Development para discutir.
Como atualizar um tema/plugin para suportar tanto o cabeçalho antigo quanto o novo?
Todas as novas APIs e saídas de plugin listadas neste documento são suportadas tanto no cabeçalho novo quanto no antigo. Portanto, você só precisa fazer uma atualização no seu tema/plugin agora, e os usuários estarão prontos para a troca.
Hoje mesclamos 
Verdade, e eu estava mais ansioso para aprender, mais ambicioso, senti o que valia mais, fui espancado, atropelado e deixado para morrer desde então.
e novamente aprecio qualquer ajuda que outros possam oferecer.
