Próximos cambios en la lista de temas: cómo preparar temas y plugins

[david (David Taylor)]

Como parte de nuestra búsqueda continua para estandarizar los sistemas de renderizado en la base de código de Discourse, estamos reemplazando la implementación de la lista de temas.

Anteriormente, esto utilizaba un enfoque de “handlebars en bruto” (.hbr), y podía personalizarse mediante anulaciones de plantillas y raw-plugin-outlets. La nueva implementación de la lista de temas utiliza componentes Glimmer modernos y se ha construido desde cero para ser personalizable de maneras sostenibles.

La nueva implementación ya está disponible detrás de la configuración glimmer_topic_list_mode.

• disabled: usa la lista de temas “handlebars en bruto” heredada.
• auto: detectará la compatibilidad de tus plugins y temas actuales. Si alguno es incompatible, usará el sistema heredado; de lo contrario, usará la nueva implementación.
• enabled: usará la nueva implementación de la lista de temas. Si tienes plugins o temas incompatibles, tu sitio puede romperse.

Ya hemos actualizado la mayoría de nuestros temas y plugins oficiales para que sean compatibles con el nuevo menú. Pero, si utilizas plugins, temas o componentes de temas de terceros que personalizan la lista de temas, será necesario actualizarlos.

Se imprimirán advertencias en la consola del navegador que identificarán la fuente de la incompatibilidad.

Cronograma de implementación

Estas son estimaciones aproximadas sujetas a cambios

Q4 2024:

• implementación principal finalizada
• actualización de temas/plugins oficiales (en progreso)
• habilitado en Meta
• publicado consejo de actualización

Q1 2025:

• actualización de temas/plugins oficiales

• glimmer_topic_list_mode por defecto a auto; mensajes de advertencia de consola habilitados

• las advertencias activarán una pancarta de advertencia para administradores para cualquier problema restante

• los plugins y temas de terceros deben actualizarse

• 1 de marzo - habilitar la nueva lista de temas para todos los sitios. El valor predeterminado para la configuración del sitio se cambiará a enabled, pero aún será posible volver a disabled.

Q2 2025

• después del 1 de abril - eliminación final del modo heredado y del código asociado.

¿Qué significa para mí?

Si tu plugin o tema tiene archivos ‘handlebars en bruto’ (con nombre .hbr o .raw.hbs), estos deberán actualizarse para ser compatibles con la nueva versión. Los archivos .hbs normales para componentes/rutas de Ember no se ven afectados por este cambio.

También se requerirán actualizaciones si usas modifyClass en component:topic-list o component:topic-list-item.

Si tu sitio tiene alguna de estas personalizaciones incompatibles, se imprimirán mensajes de advertencia en la consola del desarrollador del navegador, incluida información sobre qué tema/plugin es la causa.

¿Cuáles son los reemplazos?

Algunos de los antiguos raw-plugin-outlets se han convertido en Plugin Outlets regulares. Estos se pueden actualizar de forma 1:1.

Las personalizaciones más avanzadas deberán evaluarse caso por caso. La nueva lista de temas tiene una serie de nuevas API para una personalización fácil y robusta. Descubre más aquí:

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…

Aquí tienes algunos ejemplos:

• discourse-assign introduce una nueva columna a una lista de temas específica.

• discourse-calendar utiliza uno de los nuevos plugin outlets para mostrar la insignia de fecha del evento.

• discourse-solved utiliza un nuevo valueTransformer para reemplazar el modifyClass anterior.

¿Qué pasa con otras personalizaciones?

Si tu personalización no se puede lograr utilizando las nuevas API que hemos introducido, por favor, háznoslo saber creando un nuevo tema Dev para discutirlo.

Soy un autor de plugins/temas. ¿Cómo actualizo un tema/plugin para que admita tanto la lista de temas antigua como la nueva durante la transición?

Los nuevos plugin outlets se renderizan tanto en la implementación antigua como en la nueva de la lista de temas. Por lo tanto: cuando hayas implementado la nueva, simplemente elimina el conector raw-plugin-outlet antiguo.

Para personalizaciones basadas en DAG que reemplazan anulaciones de plantillas o outlets no modernizados, deberás mantener ambas implementaciones durante el período de transición.

Una vez que tu tema/plugin admita ambas implementaciones, antigua y nueva, puedes agregar este comentario mágico en la parte superior de todos tus archivos .hbr:

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

Esto silenciará los mensajes de advertencia y permitirá que se utilice la nueva implementación cuando esté en modo “auto”.

[pfaffman (Jay Pfaffman)]

@david

Si tu plugin o tema tiene archivos de ‘raw handlebars’ (con nombre .hbr o .raw.hbs), estos deberán actualizarse para ser compatibles con la nueva versión.

Perdona por ser quisquilloso, pero ¿no significa esto realmente algo más parecido a “si tu plugin o tema tiene archivos de ‘raw handlebars’ que tengan algo que ver con la lista de temas, entonces deben actualizarse”?

Mis archivos de raw handlebars que tienen que ver con otros modelos van a seguir estando bien, ¿verdad? ¿O los archivos de raw handlebars desaparecen por completo? (Creo que son necesarios para modelos/rutas adicionales, ¿verdad?)

[david (David Taylor)]

“Raw handlebars” significa nuestras plantillas específicas de Discourse, que tienen la extensión de archivo .hbr (o históricamente .raw.hbs). Solo usamos este sistema para la lista de temas y algunas partes internas de “autocompletado”.

Otros archivos .hbs (por ejemplo, para componentes de Ember o rutas) no se ven afectados.

Actualizaré el OP para que quede más claro. ¡Gracias @pfaffman!

Editar: aquí vamos:

@david

Si tu plugin o tema tiene algún archivo de ‘raw handlebars’ (con nombre .hbr o .raw.hbs), estos deberán actualizarse para ser compatibles con la nueva versión. Los archivos .hbs normales para componentes/rutas de Ember no se ven afectados por este cambio.

[pfaffman (Jay Pfaffman)]

@david

«Plantillas de handlebars sin procesar» significa nuestras plantillas específicas de Discourse, que tienen la extensión de archivo .hbr (o históricamente .raw.hbs).

Oh. Realmente intentaste dejarlo claro. Declaraste explícitamente las extensiones. No creo que puedas hacerlo más claro. Creo que este es mi error.

Pero tal vez agregar la oración adicional me habría ayudado a poder leer.

[Don]

Gracias por compartir. He temido esto durante mucho tiempo y está llegando… No parecerá una carrera fácil… Pero el transformador de valor probablemente lo hará más fácil.

[merefield (Robert)]

Creo que GitHub - discourse/discourse-topic-excerpts: Add topic excerpts to all topics in the topic list aún no se ha actualizado.

[david (David Taylor)]

Sí, todavía tenemos muchos temas/plugins oficiales pendientes de actualización. Ampliaré ese punto en la Q1 en el OP

[merefield (Robert)]

¡Gracias! ¡Estoy disfrutando la experiencia de desarrollador hasta ahora! Te avisaré si TLP presenta algún problema cuando llegue a eso.

[david (David Taylor)]

¡Genial! La lista oficial de miniaturas de temas (topic-list-thumbnails) es una de las que hemos terminado de actualizar, por lo que podría servir como una referencia útil.

[david (David Taylor)]

@merefield

Creo que GitHub - discourse/discourse-topic-excerpts: Añade extractos de temas a todos los temas en la lista de temas aún no se ha actualizado.

@david

Sí, todavía tenemos muchos temas/plugins oficiales pendientes de actualización.

¡Oh, lo siento! @isaac actualizó topic-excerpts la semana pasada: DEV: Update plugin for `glimmer-topic-list` (#34) · discourse/discourse-topic-excerpts@0dd3c6c · GitHub

Así que debería funcionar bien con la nueva lista de temas

[merefield (Robert)]

Estoy recibiendo:

Ambas versiones están actualizadas.

[merefield (Robert)]

@david

discourse-assign introduce una nueva columna a una lista de temas específica.

Al añadir una columna, ¿cuál es la forma estratégica de añadir una cabecera de columna ordenable?

¿utilizando:

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

además del otro transformador?

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

¿no parece hacerlo por sí solo?

[david (David Taylor)]

@merefield

Estoy recibiendo:

cc @isaac. Si tuviera que adivinar: ¿quizás la nueva lógica necesita actualizarse para manejar temas no categorizados?

@merefield

¿cuál es la forma estratégica de añadir una cabecera de columna ordenable?

El transformador que encontraste es para anular la capacidad de ordenación de las columnas existentes (por ejemplo, lo hacemos en discourse-calendar para evitar que se utilicen otros métodos de ordenación cuando estás en la vista cronológica de temas).

Si estás añadiendo una nueva columna, entonces deberías poder definir tu cabecera usando el componente SortableColumn. Por ejemplo, aquí tienes uno en el núcleo:

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

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

(una cosa que es realmente agradable de la nueva API es que todas las columnas principales se definen usando la misma API que tú usas desde temas/plugins).

[merefield (Robert)]

@david

¡las columnas principales se definen usando la misma API que usas desde temas/plugins!

Sí, lo noté cuando hice una búsqueda de código, ¡genial!

[isaac (Isaac Janzen)]

@david

cc @isaac. Si tuviera que adivinar: ¿quizás la nueva lógica necesita actualizarse para manejar temas no categorizados?

Fixed

[merefield (Robert)]

P: ¿Es posible asignar un Componente completo a una Celda, no solo una <template>?

Por ejemplo, ¿qué pasaría si quisiera mostrar un botón transparente en una celda que requiriera una lógica mínima de javascript?

[david (David Taylor)]

@merefield

P: ¿Es posible asignar un Componente completo a una Celda, no solo una <template>?

¡Sí! Técnicamente, una etiqueta <template> vacía está creando técnicamente un "Componente Solo Plantilla". Similar al tipo de componente que obtienes cuando colocas un archivo .hbs vacío en el directorio components/.

Así que sí, importar y pasar una clase de componente normal funcionará de la misma manera. ¡Incluso funcionará con componentes clásicos! (aunque obviamente recomendaríamos usar los componentes Glimmer más modernos).

[merefield (Robert)]

¡Eso es totalmente increíble!

¡Eso cambia… mucho!

[merefield (Robert)]

Pregunta tonta, quizás.

Pero, ¿cómo aplicar cambios a… la lista de temas móvil?

[david (David Taylor)]

Para móvil, tenemos un montón de nuevos puntos de conexión de plugins (incluyendo puntos de conexión envolventes).

O, alternativamente, puedes usar un valueTransformer para forzar la vista de escritorio en todas partes (hacemos esto para topic-thumbnails).

Planeo escribir una guía más detallada sobre “cómo personalizar la lista de temas” en Documentation > Developer Guides la próxima semana, así que me aseguraré de incluir esa información allí.