Usare modifyClass per cambiare il comportamento di base

[Discourse]

Per i temi e i plugin avanzati, Discourse offre il sistema modifyClass. Questo consente di estendere e sovrascrivere la funzionalità in molte delle classi javascript del core.

Quando usare modifyClass

modifyClass dovrebbe essere l’ultima risorsa, quando la personalizzazione non può essere effettuata tramite le API di personalizzazione più stabili di Discourse (ad esempio, metodi plugin-api, plugin outlet, transformer).

Il codice del core può cambiare in qualsiasi momento. Di conseguenza, le personalizzazioni effettuate tramite modifyClass potrebbero interrompersi in qualsiasi momento. Quando si utilizza questa API, è necessario assicurarsi di disporre di controlli per rilevare tali problemi prima che raggiungano un sito di produzione. Ad esempio, è possibile aggiungere test automatizzati al tema/plugin, oppure utilizzare un sito di staging per testare gli aggiornamenti in arrivo di Discourse rispetto al proprio tema/plugin.

Utilizzo di base

api.modifyClass può essere utilizzato per modificare le funzioni e le proprietà di qualsiasi classe accessibile tramite il resolver di Ember. Ciò include route, controller, servizi e componenti di Discourse.

modifyClass accetta due argomenti:

• resolverName (stringa) - costruiscilo usando il tipo (ad esempio, component/controller/ecc.), seguito da due punti, seguito dal nome (in formato dasherized) del file della classe. Ad esempio: component:d-button, component:modal/login, controller:user, route:application, ecc.

• callback (funzione) - una funzione che riceve la definizione della classe esistente e quindi restituisce una versione estesa.

Ad esempio, per modificare l’azione click() su d-button:

api.modifyClass(
  "component:d-button",
  (Superclass) =>
    class extends Superclass {
      @action
      click() {
        console.log("button was clicked");
        super.click();
      }
    }
);

La sintassi class extends ... imita quella delle classi figlie di JS. In generale, qualsiasi sintassi/funzionalità supportata dalle classi figlie può essere applicata qui. Ciò include super, proprietà/funzioni statiche e altro.

Tuttavia, ci sono alcune limitazioni. Il sistema modifyClass rileva solo le modifiche al prototype JS della classe. In pratica, ciò significa:

• l’introduzione o la modifica di un constructor() non è supportata

  api.modifyClass(
    "component:foo",
    (Superclass) =>
      class extends Superclass {
        constructor() {
          // Questo non è supportato. Il costruttore verrà ignorato
        }
      }
  );
  

• l’introduzione o la modifica dei campi di classe non è supportata (anche se alcuni campi di classe decorati, come @tracked, possono essere utilizzati)

  api.modifyClass(
    "component:foo",
    (Superclass) =>
      class extends Superclass {
        someField = "foo"; // NON SUPPORTATO - non copiare
        @tracked someOtherField = "foo"; // Questo va bene
      }
  );
  

• i campi di classe semplici sull’implementazione originale non possono essere sovrascritti in alcun modo (anche se, come sopra, i campi @tracked possono essere sovrascritti da un altro campo @tracked)

  // Codice Core:
  class Foo extends Component {
    // Questo campo core non può essere sovrascritto
    someField = "original";
  
    // Questo campo tracked core può essere sovrascritto includendo
    // `@tracked someTrackedField =` nella chiamata modifyClass
    @tracked someTrackedField = "original";
  }
  

Se ti trovi a voler fare queste cose, il tuo caso d’uso potrebbe essere meglio soddisfatto creando una PR per introdurre nuove API nel core (ad esempio, plugin outlet, transformer o API su misura).

Aggiornamento della sintassi legacy

In passato, modifyClass veniva chiamato utilizzando una sintassi con letterale oggetto come questa:

// Sintassi obsoleta - non usare
api.modifyClass("component:some-component", {
  someFunction() {
    const original = this._super();
    return original + " some change";
  }
  pluginId: "some-unique-id"
});

Questa sintassi non è più consigliata e presenta bug noti (ad esempio, la sovrascrittura di getter o @actions). Qualsiasi codice che utilizza questa sintassi dovrebbe essere aggiornato per utilizzare la sintassi nativa delle classi descritta sopra. In generale, la conversione può essere effettuata tramite:

1. rimozione di pluginId - questo non è più richiesto
2. Aggiornamento alla sintassi nativa delle classi moderna descritta sopra
3. Test delle modifiche

Risoluzione dei problemi

Classe già inizializzata

Quando si utilizza modifyClass in un inizializzatore, è possibile visualizzare questo avviso nella console:

Attempted to modify "{name}", but it was already initialized earlier in the boot process

Nello sviluppo di temi/plugin, ci sono due modi in cui questo errore viene normalmente introdotto:

• L’aggiunta di una lookup() ha causato l’errore

  Se si esegue la lookup() di un singleton troppo presto nel processo di avvio, ciò causerà il fallimento di tutte le successive chiamate modifyClass. In questa situazione, si dovrebbe tentare di spostare la lookup in modo che avvenga più tardi. Ad esempio, si modificherebbe qualcosa di simile a questo:

  // Esegue la lookup del servizio nell'inizializzatore, quindi lo usa a runtime (male!)
  export default apiInitializer("0.8", (api) => {
    const composerService = api.container.lookup("service:composer");
    api.composerBeforeSave(async () => {
      composerService.doSomething();
    });
  });
  

  A questo:

  // Lookup 'Just in time' del servizio (bene!)
  export default apiInitializer("0.8", (api) => {
    api.composerBeforeSave(async () => {
      const composerService = api.container.lookup("service:composer");
      composerService.doSomething();
    });
  });
  

• L’aggiunta di un nuovo modifyClass ha causato l’errore

  Se l’errore è introdotto dalla chiamata modifyClass aggiunta dal tema/plugin, sarà necessario spostarla più indietro nel processo di avvio. Ciò accade comunemente quando si sovrascrivono metodi sui servizi (ad esempio, topicTrackingState), e sui modelli che vengono inizializzati presto nel processo di avvio dell’app (ad esempio, un model:user viene inizializzato per service:current-user).

  Spostare la chiamata modifyClass più indietro nel processo di avvio di solito significa spostare la chiamata a un pre-initializer, e configurarlo per essere eseguito prima dell’inizializzatore ‘inject-discourse-objects’ di Discourse. Ad esempio:

  // (plugin)/assets/javascripts/discourse/pre-initializers/extend-user-for-my-plugin.js
  // oppure
  // (theme)/javascripts/discourse/pre-initializers/extend-user-for-my-plugin.js
  
  import { withPluginApi } from "discourse/lib/plugin-api";
  
  export default {
    name: "extend-user-for-my-plugin",
    before: "inject-discourse-objects",
  
    initializeWithApi(api) {
      api.modifyClass("model:user", (Superclass) => class extends Superclass {
        myNewUserFunction() {
          return "hello world";
        },
      });
    },
  
    initialize() {
      withPluginApi(this.initializeWithApi);
    },
  };
  

  Questa modifica del modello utente dovrebbe ora funzionare senza stampare un avviso, e il nuovo metodo sarà disponibile sull’oggetto currentUser.

---

Questo documento è controllato tramite versione - suggerisci modifiche su github.