Utilizzo di modifyClass per cambiare il comportamento core

[Discourse]

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

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 principale può cambiare in qualsiasi momento. Di conseguenza, le personalizzazioni effettuate tramite modifyClass possono smettere di funzionare 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 automatici 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 risolutore Ember. Ciò include rotte, 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 della classe (in formato “dasherizzato”). 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 figlio di JS. In generale, qualsiasi sintassi/funzionalità supportata dalle classi figlio 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 semplici campi di classe 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 principale:
  class Foo extends Component {
    // Questo campo principale non può essere sovrascritto
    someField = "original";
  
    // Questo campo tracked principale può essere sovrascritto includendo
    // `@tracked someTrackedField =` nella chiamata modifyClass
    @tracked someTrackedField = "original";
  }
  

Se ti trovi a voler fare queste cose, allora il tuo caso d’uso potrebbe essere soddisfatto meglio creando una PR per introdurre nuove API nel codice principale (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ù raccomandata 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, si potrebbe vedere 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 introdotto normalmente:

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

  Se si esegue lookup() di un singleton troppo presto nel processo di avvio, ciò causerà il fallimento di qualsiasi successiva chiamata a modifyClass. In questa situazione, si dovrebbe cercare di spostare la lookup in modo che avvenga più tardi. Ad esempio, si cambierebbe qualcosa come questo:

  // Lookup del servizio nell'inizializzatore, quindi utilizzarlo al runtime (male!)
  export default apiInitializer((api) => {
    const composerService = api.container.lookup("service:composer");
    api.composerBeforeSave(async () => {
      composerService.doSomething();
    });
  });
  

  In questo:

  // Lookup del servizio 'Just in time' (bene!)
  export default apiInitializer((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 tuo tema/plugin, allora dovrai spostarla più indietro nel processo di avvio. Questo 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 in un pre-initializer, e configurarlo per essere eseguito prima dell’inizializzatore ‘inject-discourse-objects’ di Discourse. Per esempio:

  // (plugin)/assets/javascripts/discourse/pre-initializers/extend-user-for-my-plugin.js
  // o
  // (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 al 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.