Prossimi cambiamenti all'elenco degli argomenti - come preparare temi e plugin

[david (David Taylor)]

Nell’ambito della nostra continua ricerca di standardizzazione dei sistemi di rendering nel codebase di Discourse, stiamo sostituendo l’implementazione della topic-list.

In precedenza, questo utilizzava un approccio ‘raw handlebars’ (.hbr), e poteva essere personalizzato tramite override di template e raw-plugin-outlets. La nuova implementazione della topic-list utilizza i moderni componenti Glimmer, ed è stata costruita da zero per essere personalizzabile in modi sostenibili.

La nuova implementazione è ora disponibile dietro l’impostazione glimmer_topic_list_mode.

• disabled: utilizza la legacy topic-list “raw handlebars”
• auto: rileverà la compatibilità dei tuoi plugin e temi attuali. Se alcuni sono incompatibili, utilizzerà il sistema legacy; altrimenti utilizzerà la nuova implementazione.
• enabled: utilizzerà la nuova implementazione della topic-list. Se hai plugin o temi incompatibili, il tuo sito potrebbe bloccarsi.

Abbiamo già aggiornato la maggior parte dei nostri temi e plugin ufficiali per essere compatibili con il nuovo menu. Tuttavia, se utilizzi plugin, temi o componenti tema di terze parti che personalizzano la topic-list, sarà necessario aggiornarli.

Verranno stampati avvisi nella console del browser che identificheranno la fonte dell’incompatibilità.

Tempistiche di rilascio

Queste sono stime approssimative soggette a modifiche

Q4 2024:

• implementazione core completata
• aggiornamento temi/plugin ufficiali (in corso)
• abilitato su Meta
• pubblicati consigli per l’aggiornamento

Q1 2025:

• aggiornamento temi/plugin ufficiali

• glimmer_topic_list_mode impostato di default su auto; abilitati messaggi di deprecazione nella console

• le deprecazioni attiveranno un banner di avviso per gli amministratori per eventuali problemi rimanenti

• i plugin e i temi di terze parti dovrebbero essere aggiornati

• 1° marzo - abilitazione della nuova topic-list per tutti i siti. L’impostazione predefinita per l’impostazione del sito sarà cambiata in enabled, ma sarà ancora possibile tornare a ‘disabled’

Q2 2025

• dopo il 1° aprile - rimozione definitiva della modalità legacy e del codice associato

Cosa significa per me?

Se il tuo plugin o tema ha file ‘raw handlebars’ (con estensione .hbr o .raw.hbs), questi dovranno essere aggiornati per essere compatibili con la nuova versione. I normali file .hbs per componenti/route Ember non sono interessati da questa modifica.

Saranno richiesti aggiornamenti anche se utilizzi modifyClass su component:topic-list o component:topic-list-item.

Se il tuo sito presenta una di queste personalizzazioni incompatibili, verranno stampati messaggi di avviso nella console degli sviluppatori del browser, incluse informazioni su quale tema/plugin ne sia la causa.

Quali sono le sostituzioni?

Alcuni dei vecchi raw-plugin-outlets sono stati convertiti in regolari Plugin Outlets. Questi possono essere aggiornati in modo 1:1.

Le personalizzazioni più avanzate dovranno essere valutate caso per caso. La nuova topic-list dispone di una serie di nuove API per una personalizzazione semplice e robusta. Scopri di più qui:

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…

Ecco alcuni esempi:

• discourse-assign introduce una nuova colonna a una specifica topic-list

• discourse-calendar utilizza uno dei nuovi plugin outlets per visualizzare il badge della data dell’evento

• discourse-solved utilizza un nuovo valueTransformer per sostituire il precedente modifyClass

Cosa succede alle altre personalizzazioni?

Se la tua personalizzazione non può essere realizzata utilizzando le nuove API che abbiamo introdotto, faccelo sapere creando un nuovo topic Dev per discuterne.

Sono un autore di plugin/temi. Come aggiorno un tema/plugin per supportare sia la vecchia che la nuova topic list durante la transizione?

I nuovi plugin outlets vengono renderizzati sia nella vecchia che nella nuova implementazione della topic list. Quindi: quando avrai implementato la nuova, semplicemente elimina il vecchio connettore raw-plugin-outlet.

Per le personalizzazioni basate su DAG che sostituiscono gli override di template o gli outlet non modernizzati, dovrai mantenere entrambe le implementazioni durante il periodo di transizione.

Una volta che il tuo tema/plugin supporterà entrambe le implementazioni, potrai aggiungere questo commento magico in cima a tutti i tuoi file .hbr:

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

Questo silenzierà i messaggi di deprecazione e consentirà l’utilizzo della nuova implementazione quando è in modalità “auto”.

[pfaffman (Jay Pfaffman)]

@david

Se il tuo plugin o tema ha file ‘raw handlebars’ (denominati .hbr o .raw.hbs), questi dovranno essere aggiornati per la compatibilità con la nuova versione.

Mi scuso per essere pignolo, ma questo non significa in realtà qualcosa di più simile a “se il tuo plugin o tema ha file ‘raw handlebars’ che hanno a che fare con la lista degli argomenti, allora devono essere aggiornati”

I miei file raw handlebars che hanno a che fare con altri modelli continueranno ad andare bene, giusto? O i file raw handlebars stanno scomparendo del tutto? (Penso che siano necessari per modelli/route aggiuntivi, giusto?)

[david (David Taylor)]

“Raw handlebars” significa i nostri template specifici per discourse, che hanno l’estensione del file .hbr (o storicamente .raw.hbs). Abbiamo utilizzato questo sistema solo per la lista degli argomenti e per alcuni elementi interni di ‘autocomplete’.

Altri file .hbs (ad esempio per componenti Ember o route) non sono interessati.

Aggiornerò l’OP per renderlo più chiaro. Grazie @pfaffman!

Modifica: ecco fatto:

@david

Se il tuo plugin o tema ha file ‘raw handlebars’ (denominati .hbr o .raw.hbs), questi dovranno essere aggiornati per la compatibilità con la nuova versione. I file .hbs normali per componenti/route Ember non sono interessati da questa modifica.

[pfaffman (Jay Pfaffman)]

@david

“Raw handlebars” significa i nostri template specifici per discourse, che hanno l’estensione del file .hbr (o storicamente .raw.hbs).

Oh. Ci hai davvero provato a renderlo chiaro. Hai esplicitamente indicato le estensioni. Non credo che tu possa renderlo più chiaro. Penso che questo sia un mio problema.

Ma forse l’aggiunta di una frase in più mi avrebbe aiutato a leggere.

[Don]

Grazie per aver condiviso. Ho avuto paura di questo per molto tempo e sta arrivando… Non sembrerà una corsa facile… Ma il trasformatore di valore probabilmente lo renderà più facile.

[merefield (Robert)]

Credo che GitHub - discourse/discourse-topic-excerpts: Add topic excerpts to all topics in the topic list non sia ancora stato aggiornato?

[david (David Taylor)]

Sì, abbiamo ancora molti temi/plugin ufficiali in attesa di aggiornamento. Estenderò quel punto elenco al Q1 nell’OP

[merefield (Robert)]

Grazie! Mi sto godendo l’esperienza di sviluppo finora! Ti farò sapere se TLP solleva problemi quando ci arriverò.

[david (David Taylor)]

Fantastico! La topic-list-thumbnails ufficiale è una di quelle che abbiamo finito di aggiornare, quindi potrebbe servire come utile riferimento.

[david (David Taylor)]

@merefield

Credo che GitHub - discourse/discourse-topic-excerpts: Add topic excerpts to all topics in the topic list non sia ancora stato aggiornato?

@david

Sì, abbiamo ancora molti temi/plugin ufficiali in attesa di aggiornamento

Oh, scusami! @isaac ha aggiornato topic-excerpts la scorsa settimana: DEV: Update plugin for `glimmer-topic-list` (#34) · discourse/discourse-topic-excerpts@0dd3c6c · GitHub

Quindi dovrebbe funzionare bene con la nuova topic-list

[merefield (Robert)]

Sto riscontrando:

Entrambe le versioni sono aggiornate.

[merefield (Robert)]

@david

discourse-assign introduce una nuova colonna in un elenco di argomenti specifico.

quando si aggiunge una colonna, qual è il modo strategico per aggiungere un’intestazione di colonna ordinabile?

usando:

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

in aggiunta all’altro transformer?

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

non sembra farlo da solo?

[david (David Taylor)]

@merefield

Sto ricevendo:

cc @isaac. Se dovessi indovinare: forse la nuova logica necessita di un aggiornamento per gestire gli argomenti non categorizzati?

@merefield

qual è il modo strategico per aggiungere un’intestazione di colonna ordinabile?

Il transformer che hai trovato serve a sovrascrivere l’ordinabilità delle colonne esistenti (ad esempio, lo facciamo in discourse-calendar per impedire l’uso di altri metodi di ordinamento quando ci si trova nella vista cronologica degli argomenti).

Se stai aggiungendo una nuova colonna, allora dovresti essere in grado di definire la tua intestazione utilizzando il componente SortableColumn. Ad esempio, eccone uno nel core:

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

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

(una cosa che è davvero bella della nuova API è che tutte le colonne principali sono definite utilizzando la stessa API che usi da temi/plugin!)

[merefield (Robert)]

@david

le colonne principali sono definite utilizzando la stessa API che si utilizza da temi/plugin!

sì, l’ho notato quando ho fatto una ricerca nel codice, bello!

[isaac (Isaac Janzen)]

@david

cc @isaac. Se dovessi indovinare: forse la nuova logica necessita di un aggiornamento per gestire argomenti non categorizzati?

Fixed

[merefield (Robert)]

D: È possibile assegnare un Component intero a una Cell, non solo un <template>?

Ad esempio, cosa succederebbe se volessi visualizzare un pulsante trasparente in una cella che richiedesse una logica JavaScript minima?

[david (David Taylor)]

@merefield

D: È possibile assegnare un Component completo a una Cell, non solo un <template>?

Sì! Tecnicamente, un tag <template> vuoto crea tecnicamente un “Template Only Component”. Simile al tipo di componente che si ottiene quando si inserisce un file .hbs vuoto nella directory components/.

Quindi sì, importare e passare una normale classe di componente funzionerà allo stesso modo. Funzionerà anche con i componenti classici! (anche se ovviamente raccomandiamo di utilizzare i componenti Glimmer più moderni).

[merefield (Robert)]

È fantastico!

Questo cambia… molto!

[merefield (Robert)]

Domanda stupida, forse.

Ma come applicare le modifiche a… topic-list mobile?

[david (David Taylor)]

Per dispositivi mobili, abbiamo una serie di nuovi plugin outlet (inclusi i wrapper outlet).

In alternativa, puoi usare un valueTransformer per forzare la visualizzazione desktop ovunque (lo facciamo per i topic-thumbnails).

Ho in programma di scrivere una guida più dettagliata su “come personalizzare l’elenco degli argomenti” Documentation > Developer Guides la prossima settimana, quindi includerò sicuramente queste informazioni.