Abbiamo recentemente lavorato sull’aggiornamento dell’intestazione di Discourse dal vecchio sistema di rendering ‘widget’ ai moderni componenti Glimmer. Questo cambiamento è ora disponibile nel core di Discourse dietro l’impostazione del sito glimmer header mode.
Tempistica Approssimativa
(stime molto indicative - soggette a modifiche in entrambe le direzioni)
Q1 2024:
-
implementazione core completata e abilitata su Meta -
pubblicato consiglio di aggiornamento; messaggi di deprecazione nella console abilitati
-
inizia il lavoro per aggiornare tutti i plugin e i temi ufficiali e di terze parti
Q2 2024:
-
inizia l’abilitazione predefinita della nuova implementazione dell’intestazione
-
temi e plugin ufficiali e di terze parti pronti per l’aggiornamento
-
i messaggi di deprecazione iniziano a generare un banner di avviso per gli amministratori per eventuali problemi residui
Q3 2024:
-
Pubblicato argomento di annuncio per una maggiore visibilità: Preparing your community for behind-the-scenes header changes
-
settimana del 5 agosto 2024 (v3.4.0.beta1): nuova intestazione abilitata per tutti i siti per impostazione predefinita. Gli amministratori potranno comunque tornare all’intestazione vecchia attivando l’impostazione del sito ‘glimmer header mode’.
-
settimana del 2 settembre 2024: rimozione definitiva del flag di funzionalità e del codice legacy
Cosa Significa per Me?
Se il tuo plugin o tema utilizza le API ‘widget’ per personalizzare l’intestazione, queste dovranno essere aggiornate per essere compatibili con la nuova intestazione.
Come Posso Provare la Nuova Intestazione?
Nell’ultima versione di Discourse, la nuova intestazione viene abilitata automaticamente quando tutti i tuoi temi/plugin sono compatibili.
Se i tuoi temi/plugin non sono compatibili, verrà utilizzata l’intestazione legacy e verrà stampato un avviso nella console insieme ai messaggi di deprecazione esistenti. Verrà mostrato anche un banner di avviso agli amministratori nell’interfaccia utente.
Nel raro caso in cui questo sistema automatico non funzioni come previsto, puoi sovrascrivere temporaneamente questo ‘flag di funzionalità automatico’ tramite l’impostazione del sito glimmer header mode. Se lo fai, ti preghiamo di farci sapere il motivo in questo argomento.
Devo Aggiornare il Mio Plugin/Tema?
Per determinare se la tua personalizzazione deve essere aggiornata, verifica se utilizza decorateWidget, changeWidgetSetting, reopenWidget o attachWidgetAction su uno di questi widget:
- header
- site-header
- header-contents
- header-buttons
- user-status-bubble
- sidebar-toggle
- header-icons
- header-topic-info
- header-notifications
- home-logo
- user-dropdown
oppure utilizza uno di questi metodi dell’API plugin:
addToHeaderIconsaddHeaderPanel
Tutte queste azioni genereranno ora messaggi di deprecazione nella console. Gli ID di deprecazione sono:
discourse.add-header-paneldiscourse.header-widget-overrides
Se utilizzi più di un tema nella tua istanza, assicurati di controllarli tutti.
Avviso per gli amministratori
A partire dal 20 giugno 2024, abbiamo abilitato l’avviso per gli amministratori per le deprecazioni sopra indicate.
Se la tua istanza è stata distribuita dopo questa data e i plugin, il tema o i componenti del tema attuali della tua istanza attivano uno degli avvisi di deprecazione, verrà visualizzato il seguente messaggio solo per gli amministratori*:
Questo messaggio serve solo per avvisare gli amministratori che devono agire presto per modernizzare le personalizzazioni interessate: le vecchie personalizzazioni continueranno a funzionare fino alla rimozione del codice legacy.
Quali Sono le Sostituzioni?
Ogni tema/plugin è diverso, ma ecco alcune indicazioni per i casi d’uso più comuni:
addToHeaderIcons
Per le icone personalizzate nell’intestazione, consigliamo di rimuovere il tuo codice e installare il componente tema ufficiale Custom Header Links (Icons) Theme Component. Se questo non soddisfa le tue esigenze, consulta di seguito le informazioni sui necessari cambiamenti di codice:
L’API plugin addToHeaderIcons è stata deprecata a favore della nuova API headerIcons. Esiste per consentire l’aggiunta, la rimozione o il riordinamento delle icone nell’intestazione. Richiede il passaggio di un Componente.
Il componente può essere passato nel seguente modo:
| Prima | Dopo |
|---|---|
| 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” }) |
Questo esempio utilizza il Formato Tag Template di Ember (gjs) per definire un componente in linea e passarlo all’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 per un menu a tendina, puoi utilizzare <DMenu invece di <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="Utente 1" @href="/u/user1" />
<DButton @translatedLabel="Utente 2" @href="/u/user2" />
<DButton @translatedLabel="Utente 3" @href="/u/user3" />
</DMenu>
</li>
</template>);
});
Commit di aggiornamento di esempio:
discourse-icon-header-linksdecorateWidget("header-buttons:*")
Il widget header-buttons è stato deprecato e abbiamo introdotto un’API plugin headerButtons. Esiste per consentire l’aggiunta, la rimozione o il riordinamento dei pulsanti nell’intestazione. Richiede il passaggio di un Componente.
| Prima | Dopo |
|---|---|
| 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(...) per i widget dell’intestazione
changeWidgetSettingpossono essere realizzati utilizzando questi componenti tema:Se questi non si adattano al tuo caso d’uso, continua a leggere…
Alcune personalizzazioni sui widget dell’intestazione utilizzavano l’API changeWidgetSetting.
Sebbene non esista una sostituzione diretta per personalizzazioni come quella sopra, a causa del funzionamento dei campi dei componenti Glimmer, abbiamo introdotto una nuova API plugin in Discourse 3.3.0.beta3 per gestire alcuni di questi casi.
registerValueTransformer può essere utilizzato per sovrascrivere i valori contrassegnati nel codice sorgente come sovrascrivibili; questo è un approccio simile a quello degli outlet dei plugin.
Abbiamo già aggiunto due transformer per i casi d’uso che abbiamo trovato comuni nel nostro codice sorgente:
-
home-logo-href: può essere utilizzato per sovrascrivere l’URL nell’ancora del logo home. Vedi la sezionehome-logoqui sotto per esempi. -
header-notifications-avatar-size: può essere utilizzato per modificare le dimensioni dell’immagine recuperata per l’avatar dell’utente nell’intestazione. Esempio:
Il codice seguente:
api.changeWidgetSetting(
"header-notifications",
"avatarSize",
settings.header_avatars_size
);
Verrebbe convertito in:
api.registerValueTransformer(
"header-notifications-avatar-size",
() => settings.header_avatars_size
);
Questi transformer devono essere aggiunti al codice sorgente di Discourse. Se ne hai bisogno di uno diverso, ti preghiamo di farcelo sapere pubblicando il tuo caso d’uso qui sotto.
Maggiori dettagli sulle nuove API dei transformer dei valori sono disponibili qui.
home-logo
Abbiamo introdotto un plugin outlet home-logo in sostituzione delle decorazioni widget home-logo:before o home-logo:after. Puoi utilizzare la convenzione di denominazione automatica __before e __after nel tuo file di connettore per specificare dove deve essere posizionato il tuo contenuto personalizzato.
Maggiori dettagli sulla convenzione di denominazione dei file di connettore before/after sono disponibili qui.
| Prima | Dopo |
|---|---|
| api.decorateWidget(“home-logo:before”) | Sposta il contenuto in /connectors/home-logo__before |
| api.decorateWidget(“header-buttons:after”) | Sposta il contenuto in /connectors/home-logo__after) |
Modifica dell’URL dell’ancora home-logo:
Un’esigenza molto comune è modificare l’URL a cui punta il home-logo. Abbiamo introdotto il transformer dei valori home-logo-href per risolvere questo problema. Esempi:
-
per cambiare il link in un URL statico
api.registerValueTransformer("home-logo-href", () => "https://example.com"); -
per restituire un URL dinamico in base all’utente corrente
api.registerValueTransformer("home-logo-href", () => { const currentUser = api.getCurrentUser(); return `https://example.com/${currentUser.username}`; }); -
per restituire un URL in base a un’impostazione del tema-componente
api.registerValueTransformer("home-logo-href", () => { return settings.example_logo_url_setting; });
E per le altre personalizzazioni?
Se la tua personalizzazione non può essere realizzata utilizzando CSS, PluginOutlets o le nuove API che abbiamo introdotto, ti preghiamo di farcelo sapere creando un nuovo argomento Development per discuterne.
Come Aggiorno un Tema/Plugin per Supportare sia la Vecchia che la Nuova Intestazione?
Tutte le nuove API e i plugin outlet elencati in questo documento sono supportati sia sulla nuova che sulla vecchia intestazione. Quindi devi effettuare un solo aggiornamento al tuo tema/plugin ora, e gli utenti saranno pronti per il passaggio.
Oggi abbiamo unito 
vero, ed ero più ansioso di imparare, più ambizioso, sentivo di più il valore, da allora sono stato picchiato, investito e lasciato per morto
e ancora una volta apprezzo qualsiasi aiuto gli altri possano offrire.
