Adicionar arquivos CSS e JavaScript às extensões do Phabricator

Toda estrutura de código-fonte aberto tem seus próprios métodos de extensão de funcionalidade; alguns tornam a extensão incrivelmente fácil e outros… nem tanto. Na maioria das vezes, isso se resume a quão bem a estrutura está documentada. O Phabricator fez um trabalho incrível ao tornar as classes necessárias extensíveis, mas é justo dizer que seria ótimo se a estrutura tivesse uma documentação um pouco melhor (PRs bem-vindos, aposto!).

Ao criar minha própria extensão, precisei adicionar arquivos JavaScript e CSS à página. Infelizmente, o Adição de novos arquivos CSS e JS a documentação afirma que “Este documento é destinado aos desenvolvedores e colaboradores do Phabricator. Este processo não funcionará corretamente para códigos, plug-ins ou extensões de terceiros.” Descobri que isso não é verdade. Veja a seguir como adicionei ativos JavaScript e CSS à minha extensão.

Coloque os arquivos de ativos em seu diretório de extensão

Cada extensão que crio é colocada em seu próprio diretório com todas as dependências dentro desse diretório:

• extensões

  • my-extension

    • my-extension.php
    • my-extension.css
    • my-extension.js

Se desejar, o senhor pode colocar os arquivos CSS e JS em seus próprios diretórios. Cada arquivo CSS e JS deve ter um @provides pelo qual o senhor se referirá a ele quando for necessário:

/**
 * @provides my-extension-js
 */

Optei por acrescentar -js e -css ao nome de referência para facilitar a manutenção.

Use require_celerity_resource para solicitar o arquivo

Na função que representa a visualização na qual o senhor gostaria que os ativos fossem injetados, você usará require_celerity_resource com a palavra @provides nome do ativo:

protected function renderLoginForm(AphrontRequest $request, $mode) {
 // Add CSS and JS resources to the page
  require_celerity_resource('bmo-auth-css');
  require_celerity_resource('bmo-auth-js');

  // ....
}

Durante a construção, mova os locais dos ativos

O Phabricator espera que todos os arquivos JavaScript e CSS estejam em sua pasta /webroot/rsrc/js/ e /webroot/rsrc/css/ portanto, o senhor precisará mover seus ativos de extensão durante o processo de compilação. Adicionei o seguinte ao meu Dockerfile para fazer exatamente isso:

# Move static resources to phabricator, add files to celerity map array
COPY auth/my-extension.css /app/phabricator/webroot/rsrc/css/my-extension.css
COPY auth/my-extension.js /app/phabricator/webroot/rsrc/js/my-extension.js

Com seus arquivos JavaScript e CSS nesse local, o require_celerity_resource poderá encontrar seus ativos pelo nome.

Atualização do mapa do Celerity

Para remover o cache e indexar seus arquivos, o senhor precisará executar o seguinte comando:

phabricator/ $ ./bin/celerity map

Esse é o processo simples, mas não muito bem documentado, para adicionar seus próprios ativos CSS e JavaScript ao Phabricator!