Recientemente hemos estado trabajando en actualizar el encabezado de Discourse, pasando del sistema de renderizado heredado de «widgets» a los componentes modernos de Glimmer. Este cambio ya está disponible en el núcleo de Discourse mediante la configuración del sitio glimmer header mode.
Cronograma aproximado
(estimaciones muy aproximadas; sujetas a cambios en cualquier dirección)
Primer trimestre de 2024:
-
implementación en el núcleo finalizada y habilitada en Meta -
publicadas recomendaciones de actualización; habilitados mensajes de obsolescencia en la consola -
iniciado el trabajo para actualizar todos los plugins y temas oficiales y de terceros
Segundo trimestre de 2024:
-
inicio de la activación por defecto de la nueva implementación del encabezado -
temas y plugins oficiales y de terceros listos para la actualización -
los mensajes de obsolescencia comienzan a mostrar una alerta de administrador en la interfaz para cualquier problema pendiente
Tercer trimestre de 2024:
-
publicado tema de anuncio para mayor visibilidad: Preparing your community for behind-the-scenes header changes -
semana del 5 de agosto de 2024 (v3.4.0.beta1): el nuevo encabezado habilitado por defecto en todos los sitios. Los administradores podrán volver al encabezado antiguo activando la configuración del sitio glimmer header mode. -
semana del 2 de septiembre de 2024: eliminación definitiva de la bandera de característica y del código heredado
¿Qué significa esto para mí?
Si tu plugin o tema utiliza alguna API de «widget» para personalizar el encabezado, deberás actualizarlo para que sea compatible con el nuevo encabezado.
¿Cómo puedo probar el nuevo encabezado?
En la versión más reciente de Discourse, el nuevo encabezado se activa automáticamente cuando todos tus temas y plugins son compatibles.
Si tus temas o plugins no son compatibles, se seguirá utilizando el encabezado heredado y se mostrará una advertencia en la consola junto con los mensajes de obsolescencia existentes. También se mostrará una alerta a los administradores en la interfaz.
En el poco probable caso de que este sistema automático no funcione como se espera, puedes anular temporalmente esta «bandera de característica automática» mediante la configuración del sitio glimmer header mode. Si lo haces, por favor indícanos la razón en este tema.
¿Necesito actualizar mi plugin o tema?
Para determinar si tu personalización requiere actualización, verifica si utiliza decorateWidget, changeWidgetSetting, reopenWidget o attachWidgetAction en cualquiera de estos widgets:
- header
- site-header
- header-contents
- header-buttons
- user-status-bubble
- sidebar-toggle
- header-icons
- header-topic-info
- header-notifications
- home-logo
- user-dropdown
o si utiliza alguno de estos métodos de la API de plugins:
addToHeaderIconsaddHeaderPanel
Todas estas acciones ahora generarán mensajes de obsolescencia en la consola. Los identificadores de obsolescencia son:
discourse.add-header-paneldiscourse.header-widget-overrides
Si utilizas más de un tema en tu instancia, asegúrate de verificarlos a todos.
Aviso para administradores
A partir del 20 de junio de 2024, hemos habilitado el aviso para administradores sobre las obsolescencias mencionadas anteriormente.
Si tu instancia fue desplegada después de esta fecha y sus plugins, temas o componentes de tema actuales activan alguna de las advertencias de obsolescencia, se mostrará el siguiente mensaje únicamente para los administradores*:
Este mensaje solo sirve para alertar a los administradores de que deben actuar pronto para modernizar las personalizaciones afectadas: las personalizaciones antiguas seguirán funcionando hasta que eliminemos el código base heredado.
¿Cuáles son las alternativas?
Cada tema o plugin es diferente, pero aquí tienes orientación para los casos de uso más comunes:
addToHeaderIcons
Para iconos personalizados del encabezado, recomendamos eliminar tu código e instalar el componente oficial Custom Header Links (Icons) Theme Component. Si esto no cumple con tus requisitos, consulta a continuación los detalles sobre los cambios de código necesarios:
La API de plugins addToHeaderIcons ha sido obsoleta en favor de la nueva API headerIcons. Esta permite agregar, eliminar o reordenar iconos en el encabezado. Requiere pasar un Componente.
El componente puede pasarse de la siguiente manera:
| Antes | Después |
|---|---|
| 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 ejemplo utiliza el Formato de etiquetas de plantilla (gjs) de Ember para definir un componente en línea y pasarlo a la 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>);
});
O para un menú desplegable, podrías usar <DMenu en lugar 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="Usuario 1" @href="/u/user1" />
<DButton @translatedLabel="Usuario 2" @href="/u/user2" />
<DButton @translatedLabel="Usuario 3" @href="/u/user3" />
</DMenu>
</li>
</template>);
});
Ejemplos de commits de actualización:
decorateWidget("header-buttons:*")
Para enlaces personalizados del encabezado, recomendamos eliminar tu código e instalar el componente oficial Custom Header Links Theme Component. Si esto no cumple con tus requisitos, consulta a continuación los detalles sobre los cambios de código necesarios:
El widget header-buttons ha sido obsoleto y hemos introducido una API de plugins headerButtons. Esta permite agregar, eliminar o reordenar botones en el encabezado. Requiere pasar un Componente.
| Antes | Después |
|---|---|
| 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 los widgets del encabezado
Los usos más comunes de
changeWidgetSettingpueden lograrse mediante estos componentes de tema:Si estos no se ajustan a tu caso de uso, continúa leyendo…
Algunas personalizaciones en los widgets del encabezado utilizaban la API changeWidgetSetting.
Aunque no existe un reemplazo directo para personalizaciones como la mencionada anteriormente, debido a cómo funcionan los campos de los componentes Glimmer, hemos introducido una nueva API de plugins en Discourse 3.3.0.beta3 para manejar algunos de estos casos.
registerValueTransformer puede usarse para anular valores marcados en el código fuente como anulables; este es un enfoque similar al de los outlets de plugins.
Ya hemos añadido dos transformadores para los casos de uso que encontramos más comunes en nuestra base de código fuente:
-
home-logo-href: puede usarse para anular la URL en el ancla del logotipo principal. Consulta la secciónhome-logomás abajo para ejemplos. -
header-notifications-avatar-size: puede usarse para cambiar el tamaño de la imagen cargada para el avatar del usuario en el encabezado. Ejemplo:
El siguiente código:
api.changeWidgetSetting(
"header-notifications",
"avatarSize",
settings.header_avatars_size
);
Se convertiría en:
api.registerValueTransformer(
"header-notifications-avatar-size",
() => settings.header_avatars_size
);
Estos transformadores deben agregarse al código fuente de Discourse. Si necesitas uno diferente, por favor indícanos tu caso de uso publicándolo a continuación.
Más detalles sobre las nuevas APIs de transformadores de valores se pueden encontrar aquí.
home-logo
Hemos introducido un outlet de plugins llamado home-logo en reemplazo de las decoraciones de widgets home-logo:before o home-logo:after. Puedes utilizar la nomenclatura automática __before y __after en tu archivo de conectores para especificar dónde debe colocarse tu contenido personalizado.
Más detalles sobre la nomenclatura de archivos de conectores antes/después se pueden encontrar aquí.
| Antes | Después |
|---|---|
| api.decorateWidget(“home-logo:before”) | Mover contenido a /connectors/home-logo__before |
| api.decorateWidget(“header-buttons:after”) | Mover contenido a /connectors/home-logo__after) |
Modificar la URL del ancla del logotipo principal:
Una necesidad muy común es modificar la URL a la que enlaza el home-logo. Hemos introducido el transformador de valores home-logo-href para abordar esto. Ejemplos:
-
para cambiar el enlace a una URL estática
api.registerValueTransformer("home-logo-href", () => "https://example.com"); -
para devolver una URL dinámica basada en el usuario actual
api.registerValueTransformer("home-logo-href", () => { const currentUser = api.getCurrentUser(); return `https://example.com/${currentUser.username}`; }); -
para devolver una URL basada en una configuración de componente de tema
api.registerValueTransformer("home-logo-href", () => { return settings.example_logo_url_setting; });
¿Qué pasa con otras personalizaciones?
Si tu personalización no puede lograrse mediante CSS, PluginOutlets o las nuevas APIs que hemos introducido, por favor indícanos creando un nuevo tema en Development para discutirlo.
¿Cómo actualizo un tema o plugin para que soporte tanto el encabezado antiguo como el nuevo?
Todas las nuevas APIs y outlets de plugins mencionados en este documento son compatibles tanto con el encabezado nuevo como con el antiguo. Por lo tanto, solo necesitas realizar una actualización en tu tema o plugin ahora, y los usuarios estarán listos para el cambio.




