Utiliser modifyClass pour changer le comportement de base

[Discourse]

Pour les thèmes et les plugins avancés, Discourse propose le système modifyClass. Celui-ci vous permet d’étendre et de remplacer la fonctionnalité dans de nombreuses classes javascript de base.

Quand utiliser modifyClass

modifyClass doit être un dernier recours, lorsque votre personnalisation ne peut pas être effectuée via les API de personnalisation plus stables de Discourse (par exemple, les méthodes plugin-api, les plugin outlets, les transformers).

Le code de base peut changer à tout moment. Par conséquent, les personnalisations effectuées via modifyClass peuvent cesser de fonctionner à tout moment. Lorsque vous utilisez cette API, vous devez vous assurer que vous disposez de contrôles pour détecter ces problèmes avant qu’ils n’atteignent un site de production. Par exemple, vous pourriez ajouter des tests automatisés au thème/plugin, ou vous pourriez utiliser un site de staging pour tester les mises à jour entrantes de Discourse par rapport à votre thème/plugin.

Utilisation de base

api.modifyClass peut être utilisé pour modifier les fonctions et les propriétés de toute classe accessible via le résolveur Ember. Cela inclut les routes, les contrôleurs, les services et les composants de Discourse.

modifyClass prend deux arguments :

• resolverName (chaîne de caractères) - construisez-le en utilisant le type (par exemple, component/controller/etc.), suivi de deux points, suivi du nom de la classe (en trait d’union). Par exemple : component:d-button, component:modal/login, controller:user, route:application, etc.

• callback (fonction) - une fonction qui reçoit la définition de classe existante, puis retourne une version étendue.

Par exemple, pour modifier l’action click() sur d-button :

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

La syntaxe class extends ... imite celle des classes enfants JS. En général, toute syntaxe/fonctionnalité prise en charge par les classes enfants peut être appliquée ici. Cela inclut super, les propriétés/fonctions statiques, et plus encore.

Cependant, il existe quelques limitations. Le système modifyClass ne détecte que les changements apportés au prototype JS de la classe. Concrètement, cela signifie :

• introduire ou modifier un constructor() n’est pas pris en charge

  api.modifyClass(
    "component:foo",
    (Superclass) =>
      class extends Superclass {
        constructor() {
          // Ceci n'est pas pris en charge. Le constructeur sera ignoré
        }
      }
  );
  

• introduire ou modifier des champs de classe n’est pas pris en charge (bien que certains champs de classe décorés, comme @tracked, puissent être utilisés)

  api.modifyClass(
    "component:foo",
    (Superclass) =>
      class extends Superclass {
        someField = "foo"; // NON PRIS EN CHARGE - ne pas copier
        @tracked someOtherField = "foo"; // Ceci est acceptable
      }
  );
  

• les champs de classe simples sur l’implémentation d’origine ne peuvent être remplacés d’aucune manière (bien que, comme ci-dessus, les champs @tracked puissent être remplacés par un autre champ @tracked)

  // Code de base :
  class Foo extends Component {
    // Ce champ de base ne peut pas être remplacé
    someField = "original";
  
    // Ce champ tracked de base peut être remplacé en incluant
    // `@tracked someTrackedField =` dans l'appel modifyClass
    @tracked someTrackedField = "original";
  }
  

Si vous vous trouvez à vouloir faire ces choses, votre cas d’utilisation pourrait être mieux satisfait en faisant une PR pour introduire de nouvelles API dans le code de base (par exemple, des plugin outlets, des transformers, ou des API sur mesure).

Mise à niveau de la syntaxe héritée

Dans le passé, modifyClass était appelé en utilisant une syntaxe littérale d’objet comme ceci :

// Syntaxe obsolète - ne pas utiliser
api.modifyClass("component:some-component", {
  someFunction() {
    const original = this._super();
    return original + " some change";
  }
  pluginId: "some-unique-id"
});

Cette syntaxe n’est plus recommandée et présente des bogues connus (par exemple, remplacer les accesseurs ou les @actions). Tout code utilisant cette syntaxe doit être mis à jour pour utiliser la syntaxe de classe native décrite ci-dessus. En général, la conversion peut être effectuée en :

1. supprimant pluginId - ceci n’est plus requis
2. Mise à jour vers la syntaxe de classe native moderne décrite ci-dessus
3. Tester vos modifications

Dépannage

Classe déjà initialisée

Lorsque vous utilisez modifyClass dans un initialiseur, vous pouvez voir cet avertissement dans la console :

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

Dans le développement de thèmes/plugins, deux façons introduisent normalement cette erreur :

• L’ajout d’un lookup() a provoqué l’erreur

  Si vous lookup() un singleton trop tôt dans le processus de démarrage, cela provoquera l’échec de tous les appels modifyClass ultérieurs. Dans ce cas, vous devriez essayer de déplacer le lookup pour qu’il se produise plus tard. Par exemple, vous changeriez quelque chose comme ceci :

  // Lookup du service dans l'initialiseur, puis utilisation à l'exécution (mauvais !)
  export default apiInitializer("0.8", (api) => {
    const composerService = api.container.lookup("service:composer");
    api.composerBeforeSave(async () => {
      composerService.doSomething();
    });
  });
  

  À ceci :

  // Lookup 'juste à temps' du service (bon !)
  export default apiInitializer("0.8", (api) => {
    api.composerBeforeSave(async () => {
      const composerService = api.container.lookup("service:composer");
      composerService.doSomething();
    });
  });
  

• L’ajout d’un nouveau modifyClass a provoqué l’erreur

  Si l’erreur est introduite par votre thème/plugin ajoutant un appel modifyClass, vous devrez le déplacer plus tôt dans le processus de démarrage. Cela se produit couramment lors de la modification des méthodes sur les services (par exemple, topicTrackingState), et sur les modèles qui sont initialisés tôt dans le processus de démarrage de l’application (par exemple, un model:user est initialisé pour service:current-user).

  Déplacer l’appel modifyClass plus tôt dans le processus de démarrage signifie normalement déplacer l’appel vers un pre-initializer, et le configurer pour qu’il s’exécute avant l’initialiseur ‘inject-discourse-objects’ de Discourse. Par exemple :

  // (plugin)/assets/javascripts/discourse/pre-initializers/extend-user-for-my-plugin.js
  // ou
  // (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);
    },
  };
  

  Cette modification du modèle utilisateur devrait maintenant fonctionner sans afficher d’avertissement, et la nouvelle méthode sera disponible sur l’objet currentUser.

---

Ce document est contrôlé par version - suggérez des modifications sur github.

[merefield (Robert)]

Je présume qu’il est impossible ou du moins peu fiable de tenter d’utiliser modifyClass (dans les cas d’utilisation légaux mentionnés ci-dessus) au sein d’un plugin sur le composant d’un autre plugin dans la même installation ?

Même s’il s’agit d’un plugin inclus dans le cœur (par exemple, Chat ou Sondage) ?

[david (David Taylor)]

Si les deux plugins sont installés et activés, cela devrait fonctionner sans problème. Si la cible n’est pas installée/activée, vous obtiendrez un avertissement dans la console. Mais vous pouvez utiliser le paramètre ignoreMissing pour le supprimer.

api.modifyClass(
  "component:some-component",
  (Superclass) => ...,
  { ignoreMissing: true }
);

Bien sûr, les conseils standards concernant modifyClass s’appliquent toujours : cela devrait être un dernier recours, et cela peut échouer à tout moment, vous devez donc vous assurer que vos tests sont suffisamment bons pour identifier rapidement les problèmes. L’utilisation de transformers serait une stratégie beaucoup plus sûre.

[merefield (Robert)]

Alors, comment cela fonctionne-t-il, cela reporte-t-il l’application jusqu’à ce que tous les composants de tous les plugins aient été enregistrés et chargés ?

Je pense que j’ai un cas qui ne semble pas fonctionner.

[david (David Taylor)]

Tous les modules ES6 (y compris les composants) sont définis d’abord, puis nous exécutons les pré-initialiseurs, puis nous exécutons les initialiseurs réguliers. Donc oui, au moment où un initialiseur s’exécute, tous les composants sont résolubles.

@merefield

Je pense que j’ai un cas qui ne semble pas fonctionner.

Je serais ravi d’examiner si vous pouvez partager un extrait ou une branche

[merefield (Robert)]

Désolé, vous devez faire attention à fournir le chemin complet !

par exemple :

api.modifyClass("component:chat/modal/create-channel",

ni :

api.modifyClass("component:create-channel",

ni même

api.modifyClass("component:modal/create-channel",

ne suffisent !