Hoje vamos conhecer o plugin Advanced Custom Fields – ACF. Ele está cada vez mais popular entre os desenvolvedores e usuários em geral do WordPress. Com esse plugin, você cria campos personalizados em seus posts (e até em outros lugares) para adicionar informações aos seus posts/páginas e até no perfil do usuário.

Desde que conheci esse plugin não consigo iniciar nenhum projeto sem usá-lo. Ele facilita absurdamente o desenvolvimento principalmente quando é preciso usar muitos campos e informações personalizadas em cada post. Conheci o plugin quando estava desenvolvendo um site que precisava arquivar documentos com classificação bibliográfica. E então, para cada post precisei adicionar vários campos e o ACF foi fundamental e acelerou muito o desenvolvimento desse projeto.

Uma das coisas mais fantásticas desse plugin é que você pode aplicá-lo de duas formas. A primeira é do jeito tradicional,  instala e ativa o plugin pelo painel e ele está pronto para criar campos pela administração. O plugin adiciona uma página onde você cria os campos e determina as regras para onde e quando esses campos devem aparecer. Ótimo – com isso qualquer pessoa, sem desenvolver nenhuma linha de código, cria seus campos personalizados. Só vai precisar de algumas funções para exibir esses valores no front-end, mas pode-se usar shortcodes para resolver isso.
ACF - Campos Personalizados

A segunda forma, e a que eu utilizo em meus projetos, funciona da seguinte forma: você instala, ativa e cria os campos da mesma forma citada acima. E, ao finalizar o desenvolvimento, você exporta os campos em PHP e adiciona em seu tema junto com o plugin. Veja como fazer este procedimento:

1 – Instale e ative o plugin pela administração do WordPress.

Instalando ACF

2 – Crie seus campos (mais detalhes sobre alguns tipos de campos abaixo). Observe que você pode criar grupos de campos personalizados, e com isso criar um grupo para um tipo de post, outro para determinada necessidade, e assim por diante. Com isso, você mantém a administração e seu código mais organizados.

Criando campos com o ACF

3 – Feito isso, vá ao menu Campos Personalizados/Exportar. Ele vai oferecer duas possibilidades: XML e PHP. Escolha PHP e copie o código que ele vai fornecer.
Exportando campos ACF
4 – Em seu tema, crie um arquivo e o nomeie para algo como fields.php, ou acf-fields.php. Cole o código que exportou no novo arquivo e então adicione o seguinte trecho no seu functions.php:
// ACF Fields
require_once( '/inc/acf-fields.php' );
Observação: Dependendo da configuração do seu servidor, será preciso definir uma URL mais completa para fazer esse require. Caso isso aconteça, faça da sequinte forma:
// ACF Fields
require_once( get_template_directory_uri() . '/inc/acf-fields.php' );
Pode ser que nesse momento você vai encontrar algum conflito – o mais comum é que os campos que você criou sumam, porque eles estão duplicados (primeiro na administração do site e segundo no arquivo que acabamos de incluir no tema). Para resolver isso, vá em Campos Personalizados e mova o grupo de campos para a Lixeira.
Agora, vamos incluir os arquivos do plugin no seu tema. Isso é mais útil quando você vai criar os campos e entregar o site pronto para um cliente que não vai precisar ficar fazendo edições nesses campos. Mas, caso seja preciso editar, o usuário pode fazê-lo de forma simples. Vamos ver, então, como incluir os arquivos no tema:
5 – Copie a pasta do plugin e cole dentro da pasta do tema. Como organização, costumo fazer isso na pasta /inc.
6 – Adicione o seguinte trecho de código no seu functions.php:
include_once( '/inc/advanced-custom-fields/acf.php' );
7 – Desative o plugin no painel de plugins do seu WordPress.
8 – Para esconder qualquer interface visual da administração, adicione o seguinte no seu functions.php:
define( 'ACF_LITE', true );
9 – E, quando precisar fazer qualquer alteração, basta mudar o valor do item acima para ‘false’ e a interface administrativa volta a aparecer.
Para agilizar esse processo, costumo fazer da seguinte forma: inicio todos projetos já com o ACF incluso no tema. E deixo em uma instalação local o ACF habilitado para criar os campos. Sempre que preciso, crio os campos nessa instalação local, exporto e colo no tema em que estou trabalhando. Simples e prático.
Até aqui vimos como criar campos com o ACF e implementá-los dentro do seu tema. Vamos agora entender como exibir no seu site os valores preenchidos nos campos.
A primeira forma de fazer isso é através das funções que o plugin habilita. Vamos conhecer as principais delas:
the_field()
Exibe o valor do campo. Ela recebe dois parâmetros, mas apenas o primeiro é obrigatório; o segundo é para caso precise usar o campo fora do seu post de origem.
<?php the_field($field_name, $post_id); ?>
get_field()
Retorna o valor do campo. No mais, funciona igual à função anterior. Serve para quando precisamos guardar em uma $variável o valor do campo.
<?php $field = get_field($field_name, $post_id, $format_value); ?>
Veja a documentação completa do plugin no site oficial.
A segunda forma de utilizar os valores inseridos nos campos personalizados é através de shortcode, que é uma ferramenta poderosa do WordPress de que já falamos aqui no blog (veja o post).
Em seu post, o shortcode usado para exibir o valor do campo seria:

[acf field="field_name" post_id="123"]

 

Caso esteja usando o shortcode no post em que preencheu o campo, não precisa declarar o post_id. E atualmente, pela documentação, os shortcodes podem ser usados apenas para textos simples.

 

Tipos de campos

O quantidade de tipos de campos padrões é suficiente para muita coisa, ainda mais levando em conta que cada tipo de campo possui ainda configurações específicas.

 

Tipos de Campos

 

Texto

Área de Texto

Número – Usado para números inteiros, quantidades. Ele oferece opção de valor mínimo, máximo e inicial. Junto com esse campo, ele mostra duas setas para aumentar ou diminuir esse valor;

E-mail – Com esse campo, ao inserir um e-mail ele confere automaticamente se é mesmo um e-mail que está sendo inserido;

Senha

Editor Wysiwyg

Imagem – Ideal para adicionar imagens específicas, como por exemplo um logo, uma capa ou um flyer. Ele oferece opções de retornar o valor como objeto da imagem, URL ou ID. Além de escolher o tamanho que ela será exibida na administração e de onde deve gravar, na Biblioteca de Mídias ou anexada ao post;

Arquivo

Seleção

Checkbox

Botão de Rádio – Campo onde a pessoa pode escolher apenas uma opção. O que me chamou a atenção é que o ACF o incorporou em seu código oferendo a opção de adicionar um valor para Outro. E assim, em uma próxima vez que for preencher esse campo, o valor que adicionou em Outro passa a fazer parte da lista de opções;

Verdadeiro / Falso

Link da Página

Objeto do Post

Relação

Taxonomia

Usuário

Mapa, Datas, Cor

Uma opção global, que está presente em todos os campos e que também é muito útil é a Condições para exibição. Com isso, nós podemos determinar quais campos devem aparecer a partir de outros campos preenchidos. Por exemplo, você pode iniciar os campos com um Verdadeiro / Falso e, de acordo com isso, mostrar outros campos específicos. Isso me ajudou a fazer uma interface muito mais intuitiva no projeto que comentei acima, da Biblioteca. Nele, tínhamos a opção de colocar um arquivo em .pdf para download, e então quando a pessoa preenchia esse campo, usando as Condições para exibição, determinei que o ACF exibisse outro campo para preenchimento com a quantidade de páginas do arquivo.

Addons

O ACF é um plugin gratuito, mantido pelo Elliot Condon, e suas possibilidades são praticamente infinitas. Mas podemos ir além do infinito com os Add-ons (pagos) que ele disponibiliza. Vou comentar abaixo alguns desses complementos e que são extremamente úteis.

Options Page
Existem diversos frameworks para criação de Options Page para WordPress. Mas um ganho em fazer isso com o ACF é de ter uma interface visual para criação dos campos. Com esse add-on você pode utilizar todos os campos que apresentamos acima para criar uma página de opções para o seu site.

Depois de preenchido, para exibir o valor use a mesma função apresentada acima mas com o argumento ‘option’, veja:

<?php the_field('header_title', 'option'); ?>

Como a maioria (ou todos) os frameworks de Options Page, esse também salva as informações na tabela wp_options.

Repeater Field
Esse add-on é fundamental. Com ele você pode criar campos com valores infinitos. A pessoa que estiver preenchendo os campos pode inserir novos à medida em que vai precisando. Um exemplo básico seria para exibir a equipe envolvida em um projeto. Para cada linha teríamos o nome, cargo e função da pessoa.

Dentro dessa linha, podemos colocar qualquer um dos campos apresentados acima, ou seja, podemos colocar imagens, e-mail, textos e etc.

Já a exibição desse campo é mais complexa. Ele salva tudo em um array e então precisamos de um loop para fazer a exibição. Veja como (retirado da documentação oficial):

<?php

// check if the repeater field has rows of data
if( have_rows('repeater_field_name') ):
	// loop through the rows of data
    while ( have_rows('repeater_field_name') ) : the_row();
 // display a sub field value
        the_sub_field('sub_field_name');
endwhile;
else :
 // no rows found

endif;
?>

Conclusão

Só posso concluir dizendo que você precisa instalar e usar esse plugin! Ele é muito útil e possui uma abordagem de uso bem simples em comparação à quantidade de recursos que ele adiciona ao seu projeto em WordPress. Faça seus testes e comente conosco suas impressões. Dúvidas e sugestões são sempre bem-vindas!