Como inserir arquivos JS e CSS no WordPress

Registrar e inserir arquivos CSS e JS no WordPress é algo muito simples, mas que a maioria dos desenvolvedores iniciantes no CMS fazem errado. Veja a maneira correta de como inserir arquivos JS e CSS no WordPress neste artigo!

As maneiras erradas de inserir arquivos JS e CSS no WordPress

Quando estamos começando a desenvolver com o WordPress, é muito comum inserirmos arquivos JS e CSS no WordPress das duas maneiras abaixo:

Por função:

Uma maneira incorreta, mas com menor possibilidade de dar erro em caso de atualizações.

<?php
add_action('wp_head', function(){
 echo '<link rel='stylesheet' href="https://meusite.com/style.css">';
});

add_action('wp_footer', function(){
 echo '<script src="https://meusite.com/script.js"></script>';
});

Manipulando arquivos do tema:

A pior maneira possível, sem dúvidas, é localizar os arquivos footer.php e header.php e fazer a modificação direto neles. Já que caso o tema atualize e você não esteja em um tema filho, toda a sua personalização será perdida.

Praticamente todos já fizemos este tipo de inserção de arquivos .css e .js no WordPress logo que estamos começando a desenvolver com ele, mas a partir de hoje, vamos ensinar você a não cometer mais este erro!

A maneira correta de inserir arquivos JS e CSS no WordPress

Partido do princípio que você já esta usando um tema filho em sua aplicação, inserir os assets do seu tema é uma tarefa simples e extremamente dinâmica para ser realizada no WordPress. Para fazermos as inserções, iremos usar três funções e iremos inseri-las no arquivo functions.php do nosso tema filho:

• wp_enqueue_style(): Para registro de arquivos .css
• wp_enqueue_script(): Para registro de arquivos .js
• wp_enqueue_scripts(): Para inserção dos arquivos .css e .js

E ainda podemos utilizar a função wp_localize_script() para passarmos informações extras aos nossos arquivos .js!

Agora, ao trabalho!

Aprenda a criar shortcodes personalizados para WordPress clicando aqui!

Criando a função de registro

O primeiro passo para inserir arquivos .css e .js no WordPress é criar uma função que irá fazer o gerenciamento dos arquivos para nosso tema, basicamente, ela terá essa estrutura:

Note que estamos usando a função get_stylesheet_directory_uri() para retornar a URL do diretório do tema ativo. No caso de registro de CSS e JS por plugins, você precisa usar a função plugin_dir_url(__FILE__) para retornar a url relativa ao plugin que você está desenvolvendo.

O uso das funções para buscar url não é obrigatório, mas é uma mão na roda quando você quer construir um tema ou plugin para ser usado em múltiplos domínios!

Inserindo arquivos CSS

Para inserir corretamente arquivos .css no seu tema ou plugin de WordPress, você precisará usar a função wp_enqueue_style() (com alguns parâmetros) dentro da função recém criada para registro de assets do seu tema.

Vale frisar, que as variáveis ali são apenas para fins didáticos, você não precisa, necessariamente, criar elas para cada arquivo CSS que você quiser inserir em seu site.

Sobre os atributos da função (seguindo a nomenclatura da imagem)

• $nomeStyle (obrigatório): é o nome do “handler” do seu arquivo .css. Pense nele como o ID da sua folha de estilos; ele deve ser único em toda a instalação do WP, caso contrário, apenas o primeiro arquivo .css com esse ID será instanciado
• $urlStyle (obrigatório): é a url completa de onde está o seu arquivo. Neste caso, estamos concatenando a url base que instanciamos acima com o nome do arquivo. Isso resultaria em algo assim https://meusite.com.br/wp-content/themes/meu-tema/main.css . Caso você queira coloca um arquivo externo de alguma CDN, você só precisa inserir a url completa do item em questão!
• $dependenciasStyle (opcional): neste argumento, você passará IDs de outros arquivos css que você precisa que sejam utilizados para que este arquivo seja instanciado.
• $versaoStyle (opcional): Este argumento é muito importante e poucos desenvolvedores fazem uso dele. Com ele você pode definir a versão atual do seu arquivo para que seja criado uma versão em cache dele e assim carregar mais rapidamente no frontend do seu site, os valores possíveis para este atributo são:
  • Um numeral qualquer que indique a versão
  • false para que a versão do script seja a mesma do WP (padrão)
  • null para o caso de o arquivo não ser servido em cache (esta é a melhor opção para ambientes de desenvolvimento)
• $media (opcional): Este último argumento é muito poderoso! Ele serve como uma @media query do css!

Inserindo arquivos JS

Seguindo a mesma lógica de arquivos .css, arquivos .js devem ser inseridos dentro do mesma função de registro de assets do seu tema, porém utilizando a função wp_enqueue_script() e seus respectivos argumentos.

• $nomeScript(obrigatório): é o nome do “handler” do seu arquivo .js. e Segue a mesma lógica da usada par arquivos .css
• $urlScript (obrigatório): Segue a mesma lógica da usada para os arquivos .css
• $dependenciasScript (opcional): Segue a mesma lógica da usada para os arquivos .css . No caso de arquivos .js você pode ver a lista de todos os scripts pré-registrados pelo WP para uso clicando aqui.
• $versaoScript (opcional): Segue a mesma lógica da usada para os arquivos .css, inclusive para a nomenclatura das versões
• $carregarNoFooter (opcional): Este último argumento é usado para definir se seu script deve ser carregado no começo ou no fim do conteúdo. O padrão é para que ele carregue no header (valor da variável “false“, porém para fins de performance é recomendado sempre definir ele como “true” para que se arquivo carregue no footer do seu html.

Um segredo para arquivos .js

Após ser inserido um arquivo .js no seu site, você pode utilizar uma função chamada wp_localize_script() para que você possa atribuir valores a variáveis .js antes mesmo do arquivo ser carregado na página.

Você pode usar isso para informar se o usuário está logado ou não, um valor específico ou qualquer outra informação relevante que você necessite para que seu arquivo funcione corretamente.

Para usar essa função, você precisa de apenas três argumentos, sendo o primeiro o ID do seu arquivo .js (veja a explicação acima), o nome da variável em questão que será chamada no seu arquivo .js e depois uma array no formato chave => valor para criar o objeto no site nas páginas onde este arquivo é instanciado.

Lembre-se de passar arrays e objetos complexos nessa função no formato json (json_encode()) para evitar erros de interpretação!

E para acessar as variáveis criadas pela sua função, no seu arquivo .js você as chamará como qualquer outra variável no formato de objeto JavaScript, por exemplo:

• meuScriptParams.parametro0 irá retornar 132
• meuScriptParams[parametro1] irá retornar o resultado da função is_user_logged_in()

Visão completa da função para inserir arquivos JS e CSS no WordPress

Depois de seguir os passos acima, você terá um código similar ao da imagem abaixo.

Você consegue o código fonte completo da função clicando aqui.

E para concluir

Inserir arquivos .js e .css no WordPress dessa maneira, apenas irá funcionar se você tiver as funções wp_head() e wp_footer() inseridas nos seus arquivos do tema!

Se você quiser aprender mais sobre como desenvolver utilizando o WordPress, siga o repositório no GitHub e acompanhe os artigos postados nesta seção do blog!

Se você tiver alguma dúvida de implementação do código acima, ou alguma abordagem melhor para solucionar esta questão, deixe nos comentários abaixo!