Arquivo de Funções de um Tema WordPress (functions.php) | WordPress Developer
Arquivo de Funções de um Tema WordPress (functions.php)
Arquivo functions.php em evidência no editor de códigos
Os primeiros passos para a Integração de um Template Estático com o WordPress trata da definição dos arquivos base para o sistema identificar os arquivos como sendo um Tema e em seguida realizar a atribuição dos caminhos absolutos ao código fonte. O próximo passo é fazer uso do arquivo de funções do Tema para organizar e disparar as requisições necessárias para continuar com o processo de integração do template com o WordPress.
Escopo do Tema
O projeto que será trabalhado será o site da Blocos Engenharia. Trata-se de uma Home Page com textos de apresentação da empresa. São os objetivos do projeto:
Separar os arquivos de modo que seja possível realizar a edição do cabeçalho, conteúdo ou rodapé sem a necessidade de atualizar as demais partes do layout
Ocultar a barra de administração do WordPress
Inserir o nome da empresa no título (meta tag) do site
Incorporar corretamente scripts e estilos; e também hacks para Internet explorer
Utilizar um lightbox para exibir as imagens do site de modo ampliado, sem a necessidade de abrir uma nova aba
Exibir um texto dinâmico sobre a empresa ao clicar no botão "Saiba mais"
Tema WordPress desenvolvido para a empresa Blocos Engenharia
Você já pôde verificar no projeto anteriormente desenvolvido, que através da criação das constantes é possível trabalhar normalmente com códigos personalizados a partir do index.php. No entanto você não deve proceder dessa forma, pois seria muito complicado organizar todas as operações do lado servidor junto com a marcação HTML a ser apresentada pelo site. Para amparar essa necessidade do Tema possuir um lugar próprio destinado a funções personalizadas, o WordPress permite que você utilize um arquivo de funções.
O arquivo de funções nada mais é que um arquivo PHP chamado functions.php. Assim como o index.php ele é carregado toda vez junto com o seu Tema. Faça um teste rápido: Experimente criar o arquivo functions.php no Tema que você criou recentemente; e dentro dele, insira as definições das constantes. Você poderá confirmar esse funcionamento.
Áreas de um site: Cabeçalho e Rodapé
Faça o download do template, em seguida inicie o mesmo processo da integração básica apresentada anteriormente. Crie também o arquivo de funções. Repare na estrutura do template e como ele se subdivide:
Existe um cabeçalho bem evidenciado com título, descrição e menu;
Abaixo estão as informações do conteúdo da página;
E por fim, os créditos no rodapé.
As áreas que você definiu como cabeçalho e rodapé são geralmente replicadas em todas as telas de um projeto. Por tal motivo o mais interessante a ser feito é destrinchar o código agrupado no arquivo index.php de modo que você possa recuperá-lo por partes. Crie então um arquivo com o nome header.php e outro chamada footer.php. Os arquivos receberão a marcação HTML dos itens de cabeçalho e rodapé, pela ordem.
Insira uma chamada para a função wp_head dentro da tag de cabeçalho do HTML <head></head>. E uma outra para a função wp_footer imediatamente antes do fechamento da tag </body>. De volta ao arquivo index.php coloque no lugar das informações de cabeçalho a função get_header, e ao invés do HTML do rodapé, a função get_footer.
<!-- Marcações HTML do template -->
Feitas as devidas alterações, visualize o site. Logo de cara você reparou que foi inserida a barra de administração (Admin Bar) do WordPress. Se você abrir o código-fonte, verá também que uma série de informações foram acrescentadas ao seu código. Isso ocorreu pois as funções wp_head e wp_footer quando acionadas executaram outras funções atribuídas a elas. Como isso foi possível? Através de ações e filtros da API de Plugins.
Um Tema funcional deve estar alinhado com o WordPress e todas as ações que nele ocorrem. Foi justamente por isso que ao exibir o título do site, sua descrição e a estrutura de pastas em seu primeiro projeto; você não o fez de modo direto. Mesmo que tais valores sejam atualizados no WordPress, o Tema criado sempre irá recuperar o valor correto.
Além da recuperação dos valores, você pode ainda realizar tarefas de acordo com a necessidade do seu projeto e de eventos que possam ser disparados durante seu funcionamento. Esse tipo de integração é possível com o uso da API de Plugins.
A API de Plugins consiste na manipulação de gatilhos (Hooks, ganchos pela tradução literal) para atribuição de filtros e execução de ações. São tratados dentro do sistema como Filters e Actions, respectivamente.
Dentro do arquivo functions.php, insira a chamada para a configuração do seu Tema:
add_action( 'after_setup_theme', 'pw_theme_setup' );
function pw_theme_setup(){ }
Através da função add_action foi inserido um gatilho para a tag 'after_setup_theme' executar a função pw_theme_setup. O primeiro parâmetro é a tag de ação, ela define quando a função (passada no segundo parâmetro) será executada. No caso, a tag é acionada logo após o WordPress carregar as configurações básicas do site. Em outras palavras, você está dizendo para o WordPress: Logo após o sistema carregar as configurações básicas do site, execute minha função!
Note que assim como na definição das constantes, foi inserido um prefixo para a função. Essa boa prática de programação segue o mesmo princípio da denominação das constantes, e ainda evita a definição de funções com o mesmo nome de outras já existentes no WordPress e/ou em plugins. Nos exemplos do projeto o prefixo utilizado será sempre o pw_, mas você poderá fazer uso de qualquer outro prefixo também.
Foi exatamente isso que aconteceu ao inserir a função wp_head e wp_footer no seu Tema. As funções disparam todos os gatilhos atribuídos para as tags 'wp_head' e 'wp_footer'. Entre esses gatilhos está a inserção das informações automáticas do WordPress e também da barra de administração. Assim sendo, do mesmo modo que você adicionou uma ação após o carregamento das configurações do WordPress; você pode também criar um gatilho para o cabeçalho ou rodapé se desejar.
add_action( 'wp_head', 'pw_head' );
add_action( 'wp_footer', 'pw_footer' );
Como foi dito acima, além das ações a API de Plugins permite a manipulação de filtros. Dentro da função de configuração, coloque a instrução:
add_filter( 'show_admin_bar', 'pw_admin_bar' );
E fora de seu escopo, crie a função que será executada como filtro da informação; no caso a barra de administração:
function pw_admin_bar()
Sempre uma função atribuída para servir de filtro, deve retornar algum valor. No exemplo da Admin Bar a função deverá retornar simplesmente um valor do tipo boolean; sendo verdadeiro exibe a barra e do contrário a esconde. O simples retorno falso da função pode ser abreviado para:
Os filtros (assim como as ações) se diferenciam entre si pela passagem de parâmetros entre sua tag de criação e a função a ser disparada. Isso significa que um filtro pode enviar desde apenas um, até vários parâmetros a função acionada. Ilustrando o funcionamento da passagem de parâmetros entre filtro e função, inicialmente substitua o valor da tag <title> do HTML para:
Essa função gera os títulos dos conteúdos do WordPress de modo automático, de acordo com a requisição de URL feita. Ela insere ainda o caracter de separação (primeiro parâmetro) a direita ou a esquerda do texto recuperado (último parâmetro).
Em seguida, de volta ao functions.php adicione dentro da função de setup:
add_filter( 'wp_title', 'pw_title', 10, 2 );
Foi adicionado um novo filtro para 'wp_title'. Os demais parâmetros de add_filter são a prioridade e a quantidade de parâmetros, respectivamente. Tratando disso na função do gatilho, você terá:
function pw_title( $title, $sep )
return 'Novo título';
No caso desse gancho, os parâmetros recebidos foram o título obtido pela função wp_title de acordo com a requisição feita e o caracter de separação definido na chamada da função (no caso, o pipe '|'). Como o WordPress já se encarregou de tratar o título da página, o que você pode fazer para otimizar esse valor é adicionar a ele o nome do site:
if ( $title && !strpos( $title, $sep ) )
$title .= $sep;
$title .= PW_SITE_NAME;
Desse modo na Home do site será exibido apenas o título do site, e nas demais telas a estrutura será o texto resultante da requisição com o nome da tela, o separador e por fim o título do site.
Com a ajuda dos filtros e ações do WordPress você pode interferir em todas as etapas do desenvolvimento sem alterar em nada as linhas de código que já existem. Esse princípio é fundamental para a criação de um Tema funcional, mesmo diante de contratempos. Você não deve alterar linhas de código do WordPress para adequar ao seu projeto; qualquer atualização do sistema ou upgrade do próprio Tema, já colocaria seu trabalho em risco.
Do mesmo modo deve ser pensado o uso de CSS e JavaScript em seu Tema. Boas práticas de programação front-end determinam que tais arquivos devem vincular-se ao HTML via arquivos externos. Ao integrar esses arquivos a um site em WordPress recomenda-se ainda que esse vínculo seja determinado via arquivo de funções.
Através de algumas funções do sistema você tem condições de registrar, remover e empregar tais arquivos onde e quando for conveniente. As vantagens do uso dessas funções são muitas. Você poderá verificar que em eventuais atualizações não será preciso localizar em qual arquivo do Tema os arquivos foram inseridos ou então atualizar vários arquivos por conta de uma simples renomeação ou remoção desses mesmos arquivos.
O emprego dessa técnica a princípio se baseia em adicionar uma ação para a tag 'wp_enqueue_scripts'. Adicione o código abaixo dentro da função de setup do Tema que você está desenvolvendo:
add_action( 'wp_enqueue_scripts', 'pw_register_scripts_and_styles', 1 );
add_action( 'wp_enqueue_scripts', 'pw_enqueue_scripts_and_styles', 3 );
Com o propósito de organizar, classificar e otimizar a aplicação dos gatilhos do Tema; as ações e os filtros são sempre adicionados a partir dessa função inicial de setup. Não envolva funções PHP com trechos de códigos HTML, CSS ou JavaScript. Tenha sempre em mente sustentar a separação das linguagens. Seus projetos serão mais coesos e práticos de serem atualizados.
Veja no exemplo que é permitido inserir várias ações ao mesmo gancho e também inserir uma prioridade (de 0 a 10) como terceiro parâmetro. As prioridades devem ser vistas como números ordinais, isto é, a prioridade 1 será executada em primeiro lugar; a 2 em segundo e assim por diante. Caso existam prioridades iguais, a ordem de execução é a mesma do cadastro da ação; será executado antes o gancho adicionado primeiro.
Desse ponto em diante, você já trabalha com a incorporação de estilos e scripts a partir do arquivo de funções; portanto certifique-se de remover as instruções do template para não incorporar um mesmo arquivo várias vezes. Feita a verificação, o primeiro gatilho a ser disparado é referente ao registro dos arquivos a serem utilizados:
function pw_register_scripts_and_styles()
wp_register_style( 'be', PW_URL_THEME . 'style.css', false, '', 'screen' );
wp_register_style( 'be-font', 'http://fonts.googleapis.com/css?family=Oswald', false, '', 'screen' );
wp_register_style( 'be-ie', PW_URL_THEME . 'css/ie.css', false, array( 'be' ), 'screen' );
Com wp_register_style você determina um identificador único para o arquivo e atribui sua localização através do caminho absoluto. A função permite ainda determinar a dependência de outros arquivos, versão do arquivo atual e o atributo media de sua incorporação ao site. Registrados os arquivos, o próximo passo e realizar a incorporação dos mesmos:
function pw_enqueue_scripts_and_styles()
wp_enqueue_style( 'be' );
wp_enqueue_style( 'be-font' );
wp_enqueue_style( 'be-ie' );
Está feito! Veja como está o seu projeto. Lembre-se que a incorporação dos estilos apenas surtirá efeito se a função wp_head() estiver inserida no arquivo de cabeçalho previamente criado.
Além de contar com as formatações personalizadas do Tema é muito importante que você incorpore a seus estilos algumas formatações padrão do WordPress. Trata-se de algumas classes que são atribuídas ao site pela formatação dos textos no editor de conteúdo. Correspondem a definições de alinhamento e aplicação de moldura a imagens.
Você pode também usar a função wp_enqueue_style de modo direto, informando os mesmos parâmetros de wp_register_style. Dessa forma o registro e a incorporação do arquivo ocorrem ao mesmo tempo. Opte pela opção que melhor atende as necessidades do seu trabalho. Tenha um certo cuidado ao encurtar esse caminho, pois em situações onde você esteja trabalhando com muitos arquivos é provável que em algum ponto deixe de fazer o registro do arquivo e tenha que replicá-lo na íntegra novamente.
Hacks de CSS
Muitas vezes o desenvolvimento front-end faz uso de hacks de estilos para adequar a visualização do site a todos os navegadores. Nesses casos a incorporação das folhas de estilos é intercalada por trechos condicionais. Perceba no exemplo que o arquivo ie.css foi incorporado mas sem nenhum tratamento condicional. Para atribuir uma condição na qual o estilo será inserido ao site, adicione uma nova ação ao mesmo gancho 'wp_enqueue_scripts':
add_action( 'wp_enqueue_scripts', 'pw_register_styles_hacks', 2 );
A função chamada será responsável por atribuir a condição
function pw_register_styles_hacks()
$wp_styles->add_data( 'be-ie', 'conditional', 'lte IE 8' );
Seguindo o mesmo raciocínio da incorporação dos estilos, você pode fazer uso das funções wp_register_script e wp_enqueue_script para manipular seus scripts. A única diferença entre as funções de estilo e script está no último parâmetro. Enquanto que para as folhas de estilo o parâmetro diz respeito ao atributo media da tag <link>, para os scripts o último parâmetro é do tipo boolean e define se o referido arquivo será incorporado no cabeçalho (false) ou no rodapé da página (true). Assim como a inserção dos arquivos ao cabeçalho dependem da função wp_head(), para que os mesmos sejam anexos ao rodapé (quando assim determinados), é preciso fazer uso da wp_footer().
Alguns frameworks e recursos muito utilizados pelos desenvolvedores já estão incorporados ao WordPress, bastando a você realizar a incorporação dos mesmos; uma vez que o registro já foi realizado pelo sistema. Na HomePage da Blocos Engenharia é preciso exibir a imagem ampliada dentro de um lightbox, aproveite então o recurso thickbox inerente ao WordPress para incorporar esse recurso ao site. Adicione ao Tema o estilo e script que farão o recurso funcionar e certifique-se de que o link que aponta a imagem ampliada possua em sua definição do HTML a classe thickbox.
Em alguns casos é possível que o script em questão não esteja em sua versão mais recente; ou você prefira incorporar sua própria versão. Nessas situações faça uso de wp_deregister_script() para apagar o registro e logo em seguida adicioná-lo novamente:
wp_register_script( 'jquery', 'http://code.jquery.com/jquery-latest.pack.js', false, '', true );
O trabalho com requisições AJAX no WordPress requer alguns cuidados para que seja bem concebido. Você precisará desse recurso para apresentar a descrição do projeto atual mediante o clique no link determinado pelo template. Observe na prática, como se dá a aplicação a aplicação das requisições AJAX. Primeiramente, tal como apresentado acima, é feito o registro e incorporação do novo script:
wp_register_script( 'be', PW_URL_THEME . 'script.js', false, array( 'jquery' ), true );
wp_enqueue_script( 'be' );
Dentro do arquivo script.js faça uma requisição ajax ao arquivo ajax-description.php, cujo conteúdo é simplesmente:
Caso tenha dificuldades com esse tipo de requisição veja por exemplo como utilizar o método jQuery.post e também os conteúdos anexos dessa aula.
Ao testar a solicitação será retornado apenas o erro do PHP informando que a referida constante não foi setada. Logo no começo dos trabalhos você verificou que os caminhos relativos não funcionam adequadamente com o WordPress e também que o acesso direto aos arquivos PHP não possibilita o acesso as funções do CMS. Foi exatamente isso que aconteceu; o WordPress não foi carregado dentro de sua requisição.
Com a finalidade de oferecer um ambiente seguro e prático de ser trabalho nesse tipo de requisição, você tem em mãos os gatilhos de ação 'wp_ajax_{nome-da-ação}' e 'wp_ajax_nopriv_{nome-da-ação}'. O primeiro gancho diz respeito a manipulação de requisições por usuários logados no sistema, enquanto que o outro por usuários fora dele. Se uma requisição deverá surtir o mesmo efeito ao visitante do site, independente dele estar dentro ou fora do sistema; adicione a seu Tema ambos os gatilhos:
function pw_theme_setup()
add_action( 'wp_ajax_get_description',        'pw_get_description' );
add_action( 'wp_ajax_nopriv_get_description', 'pw_get_description' );
Sendo a função a ser disparada:
function pw_get_description()
Com o ambiente PHP devidamente preparado, altere o arquivo que será requisitado pelo seu script; aponte para /wordpress/wp-admin/admin-ajax.php. Adicione um campo de nome 'action' e valor 'get_description' a ser enviado junto com a requisição AJAX. Repare que o valor do campo action é igual ao nome da ação definido no momento da atribuição do gancho.