Usando o plugin Advanced Custom Fields (ACF) para criar campos personalizados facilmente

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!

30 comentários

  1. Esse plugin é realmente muito bom. Estou começando a utilizá-lo agora, e uma dúvida que tenho diz respeito a atualização de algum campo. Por exemplo, eu crio um campo e adiciono informações em diversos posts criados. Caso eu atualize esse campo diretamente pelo plugin, adicionando alguma nova informação, os dados dos posts anteriormente inseridos podem ser apagados?

    • Rafael, quando você cria um campo, você dá a ele um ID, e é com essa informação que o WordPress vai guardar e consultar no banco de dados. Portanto, se você não alterar o ID dos campos, eles permanecerão com seus valores preenchidos.

    • Carlos, ele guarda na tabela wp_postmeta. Na coluna meta_key ele salva o nome do campo mais ou menos assim: field_54afb8cfbf06a e na coluna meta_value ele guarda as informações serializadas.

  2. Olá Everaldo, este plugin realmente é sensacional. Eu preciso que os campos personalizados apareçam no post, exemplo:

    No painel admin do post eu adicionei uma informação X

    E então queria que no post aparecesse o mesmo campo com a informação X

    Teria como fazer isso ? Tentei com o shortcode, mas sem sucesso.

    • Entendi Gregory.
      Para isso precisa editar o single.php que exibe seus posts.

      As funções para exibição do valor do campo são:
      the_field() e get_field().

      Exemplo, colocando isso na sua single:

      Exemplo de Campo:

      Ele retornará o texto: Exemplo de Campo: Valor Preenchido no Campo

  3. criei um campo area de texto para Usuario, fui em editar perfil para colocar os valores. A funcao the_field(‘campo_xyz’) não mostra nada. porquê será?

  4. Cara, esse plugin é realmente muito bacana. Porém nele a infinitas possibilidades, e uma delas é:

    Utilizá-lo para front-end, isto é, publicar/editar posts pelo front-end do wordpress. E é exatamente isso o que eu procuro.

    Você sabe criar isso? Se sim, por favor, aguardo ANSIOSAMENTE pelo tutorial isso me ajudaria muito. ;)

    Ótimo tutorial, ótimo plugin, ótimo site.
    Parabéns e sucesso!

  5. Olá Everaldo, esse plugin é realmente sensacional. Será que é possível através dele fazer com que se caso os meus posts tiverem um botão de download (inserido ou não com o plugin MaxButton), esses mesmos botões apareçam abaixo das miniaturas dos posts numa página que utiliza list posts ou query posts de cada categoria. Faz algumas semanas que to tentando fazer isso, mas com grande dificuldade, os botões em geral usam shortcodes. Se puder me ajudar ficarei muito grato!
    abraços!

  6. Olá Everaldo, esse plugin e os add-ons são muito bons mesmo. Porém não estou entendendo como pegar os sub-fields de valor específico. Consigo puxar todos os itens, mas não filtrados. Ex: crio um grupo de campo “Cadastro de produtos” e adiciono um campo do tipo repeater com campos “nome do item” e “valor do item”. Como fazemos para puxar apenas os itens que possuem, por exemplo o nome “camisa branca”.

    Agradeço a ajuda. Abraço.

  7. Olá como faço pára criar um form de login só para o bbpress, sendo que os registrados no forum, não tenham acesso ao campo de usuário do wordpress.

  8. mano, eu coloquei um campo “area de texto” a mais no post, porém quando eu publico o post, não mostra o que coloquei nesse campo a mais..só no campo que ja existe por padrão né

  9. Olá Everaldo, estou usando este plugin juntamente com o woocommerce e preciso que o usuário(vendedor) ao criar um produto coloque seu código. No front-end quando alguém comprar este produto preciso que juntamente com as informações daquele produto, vá o código que o vendedor (usuário) colocou ao postar aquele produto. Como faço isso? E faço as edições em qual página, no single, no contend-single-product?

    Preciso de um HELP?

  10. Por favor se puderem me dar essa ajuda eu apreciaria muito, preciso criar custom fields nos produtos do woocommerce para que depois eu possa importar um arquivo xml e esses dados possam ir para o banco de dados, posso usar este plugin ou alguem me indicaria algo mais especifico, muito obrigado.

  11. Olá Everaldo!

    Muito bom! Obrigada pela dica. Encontrei o ACF aqui. :)
    E ele é realmente ótimo! Tenho usado pra qualquer coisa. rsrs

    Entretanto, estou com um problema (estou pesquisando há muito tempo e não consigo solucionar, creio que não seja esperta o suficiente :/) e gostaria de saber se você consegue me ajudar. Estou utilizando o “repeater field” para compor tabelas de algumas tarefas. Cada tarefa tem uma tabela com informações diversa, Elas funcionam direitinho no front-end. O que eu queria, e que não consigo, é fazer com que todas as informações cadastradas em todas as tabelas aparecem em uma outra tabela, como se fosse uma tabela geral, com um loop de todo o “repeater-fields”, tudo que foi cadastrado nele, em cada tabela que há no sistema.

    Será que consegui me explicar?

    Por favor, se conseguir me ajudar…

    Desde já agradeço muito muito mesmo!! <3

  12. Eu tenho um tema, que tem um campo personalizado, e gostaria mudar o tema que não existe o campo que desejo, nesse caso consigo importar todo conteúdo dos posts, mas esse campo infelizmente não é importado.
    Existe algum plugin para isso?

  13. Galera desativei este plugin e meu site saiu do ar, como ativo ele pelo código ao invés de ser pelo painel WordPress ?

Deixe um comentário

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *