Hoje vamos aprender onde e como adicionar código fora dos templates em nosso tema. Fazemos isso adicionando o functions.phparquivo do tema. Ao longo do caminho, também aprenderemos como adicionar suas folhas de estilo e scripts da maneira correta.
O arquivo functions.php de um tema
Um tema precisa de um lugar para colocar o código que não faz parte dos modelos. Há sempre um monte de código que todos os temas precisam adicionar para lidar com a funcionalidade. Por exemplo, habilitar o recurso de imagens em destaque do WordPress (você notou que estava faltando?), suporte para menus, widgets, adição de folhas de estilo e scripts (da maneira correta) e muito mais.
Esse arquivo é functions.php. WordPress automaticamente e sempre carrega este arquivo se existir em seu tema. É sempre carregado tanto no admin quanto no frontend.
Adicionando um arquivo functions.php ao nosso tema
Vamos criar um novo arquivo vazio em nossa pasta de tema raiz e nomeá-lo functions.php.
Nesse arquivo, comece imediatamente com uma tag PHP de abertura (<?php) e não inclua a tag de fechamento. O functions.phparquivo é destinado a código PHP, não HTML. Seu tema pode quebrar (ou até mesmo agir de forma estranha) se você tiver caracteres ou novas linhas fora das tags PHP neste arquivo. Obviamente, você pode sair das tags PHP para gerar HTML, mas isso deve ser feito dentro de funções ou ganchos. Deixe-me explicar isso com um experimento.
Vamos testar este arquivo para ver como ele funciona. Dentro functions.phpescreva um eco de algum texto fictício:
<?php
echo 'This is an experiment';Atualize seu frontend. O texto fictício aparece. Mas se você inspecionar ou visualizar a fonte HTML, verá que o texto aparece antes de abrir <html>. Isso torna o HTML completamente inválido!
Vá para o seu painel de administração e clique em atualizar. Ele faz a mesma coisa lá também (pode estar escondido atrás da barra de administração, mas está lá no HTML).
Como você pode ver, qualquer código em suas functions.phpcargas antes de qualquer outra coisa em nossos modelos. Portanto, via de regra, qualquer saída (HTML fora de tags PHP ou echo) deve estar dentro de funções que serão executadas nos momentos certos, normalmente vinculadas a ações ou filtros.
Lembre-se de quando aprendemos e adicionamos ganchos na parte 3 do tutorial do tema WordPress para iniciantes. A maneira como executamos o código em um gancho é anexar uma função ao gancho com add_action(). Vamos testar outra coisa; vamos fazer uma função ligada a um gancho que já definimos em nossos templates; wp_footer.
Ao functions.phpremover o echoadicionamos para fins de teste e, em vez disso, escrevemos:
<?php
add_action('wp_footer', 'wptutorial_print_footer');
function wptutorial_print_footer() {
echo 'This sentence will appear in footer!';
}Clique em atualizar no frontend e veja que a string aparece bem no local exato que você definiu wp_footer, logo antes de fechar </body>. Além disso, observe que isso não ecoará nada no admin. Isso ocorre porque wp_footeré um gancho que é executado apenas no frontend.
Vamos fazer nossas primeiras operações em functions.php!
Nota: No PHP não é possível ter duas funções com o mesmo nome. Isso inclui nomes de funções no WordPress, seu tema e qualquer plugin ativado! Siga as práticas recomendadas e prefixe suas funções com seu slug de tema, como no exemplo acima: ” wptutorial_<function_name>“. Isso reduz muito o WordPress de travar fatalmente por causa de nomes de funções idênticos.
Nota 2: Não importa em qual ordem você adiciona funções e ganchos em seu arquivo functions.php. Lembre-se de que os ganchos são executados em determinados pontos de verificação de qualquer maneira, não na ordem em que estão functions.php. A única exceção é se você estiver incluindo outros arquivos ou inicializando suas próprias classes.
A maneira certa de adicionar estilos e scripts versus a maneira errada
Alguns de vocês devem se lembrar da parte 3, onde adicionamos o wp_headgancho em nosso arquivo header.php. Depois que fizemos isso, o WordPress conseguiu carregar seus estilos e scripts, incluindo a barra de administração. Você pode estar pensando que, para adicionar nossas folhas de estilo, precisamos fazer uma função vinculada wp_heade produzir o <link>para a folha de estilo… Normalmente você estaria certo!
No entanto, no WordPress existe uma maneira especial de adicionar scripts e estilos. Isso serve principalmente para gerenciar a ordem de carregamento e evitar o carregamento de bibliotecas duplicadas. Por exemplo, você como autor de um tema pode querer adicionar Javascripts que são dependentes da jQuerybiblioteca. Então você precisa ter certeza de jQueryser carregado antes de seus arquivos. Mas o WordPress e quaisquer plugins têm a mesma necessidade, para garantir que jQuerysejam carregados antes de seus scripts também. Você não pode carregar a jQuerybiblioteca várias vezes porque isso causa problemas. Portanto, o WordPress tem uma maneira de gerenciar em qual ordem os scripts e as folhas de estilo são carregados.
Adicionando folhas de estilo (da maneira certa)
Para adicionar qualquer estilo e qualquer javascript, usamos um gancho chamado wp_enqueue_scripts. Sim, você também usa este gancho para estilos, apesar do nome. A adição de scripts e estilos é chamada de “enfileiramento" – como colocar em uma fila. Vamos enfileirar (adicionar) nossa folha de estilo usando a função wp_enqueue_style em nosso functions.php:
<?php
add_action('wp_enqueue_scripts', 'wptutorial_enqueue_scripts');
function wptutorial_enqueue_scripts() {
wp_enqueue_style('theme-main-style', get_stylesheet_directory_uri().'/style.css');
}A wp_enqueue_stylefunção recebe no mínimo dois parâmetros. O primeiro é um nome exclusivo (identificador ou “ID do slug”) e o segundo é o local do arquivo. O identificador precisa ser exclusivo, pois esse é o identificador que o WordPress usa para determinar se há duplicatas.
Quanto a retornar o caminho para o seu tema, há muitas funções disponíveis. Acima eu usei get_stylesheet_directory_uri()que retorna a URL para a pasta do seu tema e, em seguida, acrescentei o restante do caminho à nossa folha de estilo.
PS: O WordPress oferece uma função separada para retornar o URL completo para o style.css: get_stylesheet_uri(). Eu usei a outra função acima, pois é mais útil para se familiarizar. Você o usará para quaisquer outros arquivos que precisar enfileirar.
A função wp_enqueue_styleaceita parâmetros mais úteis, como dependências (que outros arquivos css devem ser carregados antes) e número de versão (útil para fins de armazenamento em cache).
Atualize seu frontend e veja que sua folha de estilo está carregada na <head>tag!
Se você é um daqueles que estão ansiosos para deixar seu tema mais bonito enquanto o codifica, aqui está sua chance. Eu encorajo você a começar a definir seu HTML, classes e wrappers e adicionar algum estilo em seu arquivo style.css. Adicionaremos mais conteúdo que exigirá estilo à medida que avançamos nesta série de tutoriais.
Adicionando scripts (da maneira certa)
Vamos ver como adicionamos javascripts ao nosso tema. Isso é feito usando o mesmo gancho (assim você pode colocar tudo dentro de uma função). Mas para scripts usamos uma função um pouco diferente.
Para enfileirar um script, você usa wp_enqueue_script(). Os parâmetros são os mesmos do wp_enqueue_style(). O primeiro é o identificador exclusivo e o segundo é o caminho para o script. Terceiro (opcional) é o array de dependências. Como quarto parâmetro (opcional), você define o número da versão. E finalmente quinto (opcional) você define se o script deve ou não ser carregado na <head>tag ou no final do </body>.
O WordPress vem com uma grande variedade de bibliotecas já incluídas. Eles nem sempre estão todos carregados, mas estão disponíveis se você precisar deles. Se você deseja adicionar um script de biblioteca comum, verifique primeiro se o WordPress já o possui. Exemplos são jQuery, todos os módulos jQuery UI, Underscore e Backbone.
Se você adicionar um dos scripts incluídos no WordPress como uma dependência, não precisará enfileirar esse script! Vamos fazer isso na prática.
Crie uma pasta assetse dentro dela uma subpasta jsem nossa pasta de temas, e então adicione um novo arquivo vazio main.js. Digamos que este script requer a jQuerybiblioteca, então nós o configuramos como dependência. Sabemos que o WordPress vem com jQuerypacotes e o identificador para isso é jquery. Vamos enfileirar nosso script assim:
<?php
add_action('wp_enqueue_scripts', 'wptutorial_enqueue_scripts');
function wptutorial_enqueue_scripts() {
wp_enqueue_style('theme-main-style', get_stylesheet_directory_uri().'/style.css');
wp_enqueue_script('theme-main-script', get_stylesheet_directory_uri().'/assets/js/main.js', ['jquery']);
}Se você atualizar o frontend e verificar seu código-fonte, verá que seu script, main.js, foi adicionado, mas também que a jQuerybiblioteca foi carregada. E jQueryé carregado antes do seu arquivo!
Agora você aprendeu como adicionar estilos e scripts. Para adicionar mais arquivos, adicione um wp_enqueue_style()ou wp_enqueue_script()para cada novo arquivo.