Usando modifyClass para alterar o comportamento principal

[Discourse]

Para temas e plugins avançados, o Discourse oferece o sistema modifyClass. Isso permite estender e substituir a funcionalidade em muitas das classes javascript do núcleo.

Quando usar modifyClass

modifyClass deve ser um último recurso, quando sua personalização não puder ser feita através das APIs de personalização mais estáveis do Discourse (por exemplo, métodos plugin-api, plugin outlets, transformers).

O código do núcleo pode mudar a qualquer momento. E, portanto, personalizações feitas via modifyClass podem quebrar a qualquer momento. Ao usar esta API, você deve garantir que possui controles implementados para capturar esses problemas antes que cheguem a um ambiente de produção. Por exemplo, você pode adicionar testes automatizados ao tema/plugin, ou pode usar um site de homologação (staging) para testar as atualizações de entrada do Discourse contra seu tema/plugin.

Uso Básico

api.modifyClass pode ser usado para modificar as funções e propriedades de qualquer classe que seja acessível através do resolvedor Ember. Isso inclui rotas, controladores, serviços e componentes do Discourse.

modifyClass aceita dois argumentos:

• resolverName (string) - construa isso usando o tipo (por exemplo, component/controller/etc.), seguido por dois pontos, seguido pelo nome da classe (em formato hifenizado). Por exemplo: component:d-button, component:modal/login, controller:user, route:application, etc.

• callback (função) - uma função que recebe a definição da classe existente e, em seguida, retorna uma versão estendida.

Por exemplo, para modificar a ação click() no d-button:

api.modifyClass(
  "component:d-button",
  (Superclass) =>
    class extends Superclass {
      @action
      click() {
        console.log("botão foi clicado");
        super.click();
      }
    }
);

A sintaxe class extends ... imita a das classes filhas do JS. Em geral, qualquer sintaxe/recurso suportado por classes filhas pode ser aplicado aqui. Isso inclui super, propriedades/funções estáticas e mais.

No entanto, existem algumas limitações. O sistema modifyClass detecta apenas alterações no prototype JS da classe. Na prática, isso significa:

• introduzir ou modificar um constructor() não é suportado

  api.modifyClass(
    "component:foo",
    (Superclass) =>
      class extends Superclass {
        constructor() {
          // Isso não é suportado. O construtor será ignorado
        }
      }
  );
  

• introduzir ou modificar campos de classe não é suportado (embora alguns campos de classe decorados, como @tracked, possam ser usados)

  api.modifyClass(
    "component:foo",
    (Superclass) =>
      class extends Superclass {
        someField = "foo"; // NÃO SUPORTADO - não copie
        @tracked someOtherField = "foo"; // Isso é permitido
      }
  );
  

• campos de classe simples na implementação original não podem ser substituídos de forma alguma (embora, como acima, campos @tracked possam ser substituídos por outro campo @tracked)

  // Código do núcleo:
  class Foo extends Component {
    // Este campo do núcleo não pode ser substituído
    someField = "original";
  
    // Este campo tracked do núcleo pode ser substituído incluindo
    // `@tracked someTrackedField =` na chamada modifyClass
    @tracked someTrackedField = "original";
  }
  

Se você se encontrar querendo fazer essas coisas, então seu caso de uso pode ser melhor atendido fazendo um PR para introduzir novas APIs no núcleo (por exemplo, plugin outlets, transformers, ou APIs personalizadas).

Atualizando Sintaxe Legada

No passado, modifyClass era chamado usando uma sintaxe de literal de objeto como esta:

// Sintaxe desatualizada - não use
api.modifyClass("component:some-component", {
  someFunction() {
    const original = this._super();
    return original + " alguma alteração";
  }
  pluginId: "some-unique-id"
});

Esta sintaxe não é mais recomendada e tem bugs conhecidos (por exemplo, substituir getters ou @actions). Qualquer código que use esta sintaxe deve ser atualizado para usar a sintaxe de classe nativa descrita acima. Em geral, a conversão pode ser feita por:

1. remover pluginId - isso não é mais necessário
2. Atualizar para a sintaxe de classe nativa moderna descrita acima
3. Testar suas alterações

Solução de Problemas

Classe já inicializada

Ao usar modifyClass em um inicializador, você pode ver este aviso no console:

Attempted to modify "{name}", but it was already initialized earlier in the boot process (Tentativa de modificar “{nome}”, mas ele já foi inicializado anteriormente no processo de boot)

No desenvolvimento de temas/plugins, existem duas maneiras pelas quais esse erro é normalmente introduzido:

• Adicionar um lookup() causou o erro

  Se você fizer lookup() de um singleton muito cedo no processo de boot, isso fará com que quaisquer chamadas modifyClass posteriores falhem. Nessa situação, você deve tentar mover o lookup para ocorrer mais tarde. Por exemplo, você mudaria algo como isto:

  // Faz lookup do serviço no inicializador, então o usa em tempo de execução (ruim!)
  export default apiInitializer("0.8", (api) => {
    const composerService = api.container.lookup("service:composer");
    api.composerBeforeSave(async () => {
      composerService.doSomething();
    });
  });
  

  Para isto:

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

• Adicionar um novo modifyClass causou o erro

  Se o erro for introduzido pela adição de uma chamada modifyClass pelo seu tema/plugin, então você precisará movê-la mais cedo no processo de boot. Isso acontece comumente ao substituir métodos em serviços (por exemplo, topicTrackingState), e em modelos que são inicializados cedo no processo de boot do aplicativo (por exemplo, um model:user é inicializado para service:current-user).

  Mover a chamada modifyClass mais cedo no processo de boot normalmente significa mover a chamada para um pre-initializer, e configurá-lo para rodar antes do inicializador ‘inject-discourse-objects’ do Discourse. Por exemplo:

  // (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);
    },
  };
  

  Esta modificação do modelo de usuário agora deve funcionar sem imprimir um aviso, e o novo método estará disponível no objeto currentUser.

---

Este documento é controlado por versão - sugira alterações no github.