O plugin Advanced Custom Fields (ACF) suporta a configuração completa de campos e grupos por código PHP em seu tema ou plugin. Os benefícios de fazer isso é que todos os seus campos estarão disponíveis independentemente da instância do WordPress em que você está trabalhando (por exemplo, se você precisar alternar entre local, servidor de teste e servidor ativo). Você pode configurar todos os campos no admin do ACF e usar a ferramenta de exportação para exportá-los para PHP.

No entanto, se você fizer isso com frequência, poderá notar que a exportação PHP do ACF contém muito código, tornando seus arquivos PHP desnecessariamente longos. Em alguns casos, é melhor escrever o código você mesmo, com o mínimo necessário, para um código mais limpo em seu tema ou plugin. Este guia tem como objetivo fornecer uma referência completa sobre como escrever manualmente a adição de campos e grupos ACF em PHP. Observe que ele não entrará em detalhes sobre cada tipo de campo, pois pressupõe que você já esteja familiarizado com os diferentes campos possíveis no ACF.

Mas primeiro; algumas precauções

Para manter bons padrões de código e garantir que seu site WordPress não falhe, você deve sempre verificar se as funções ou classes que seu código está usando realmente existem. Especialmente quando se trata de plugins que podem ser facilmente desativados ou nem mesmo instalados em um site, você deve sempre envolver o código específico do plugin em um teste if que verifica se as funções que você usa existem, antes de usá-las.

Quanto ao ACF você pode fazer isso verificando se a classe 'acf'existe ou se a função para adicionar campos e grupos, 'acf_add_local_field_group', existe. Enrole qualquer um deles ao redor do código abaixo.


if (function_exists('acf_add_local_field_group')) {
    // Your ACF specific code here
}
// OR:
if (class_exists('acf')) {
    // Your ACF specific code here
}

Código esqueleto

Para adicionar meta caixas (grupos) e campos, usamos o gancho chamado acf/init. Dentro da função chamamos a função acf_add_local_field_group()com um array como parâmetro. Dentro dessa matriz está a configuração completa do grupo e todos os seus campos. Os mais importantes são as chaves de matriz 'fields'e 'location'. Para chave de matriz 'fields'você fornece a matriz para todos os campos e para a chave 'location'você fornece as configurações de onde a metabox deve aparecer. Este post entrará em detalhes de quais opções possíveis você tem para cada uma delas abaixo.

Este é o mínimo para adicionar um grupo, além dos campos e local:

Cada grupo precisa de uma chave única, mas o nome real em si não importa muito (para nós). Se você estiver adicionando mais grupos, não se esqueça de alterar o 'key'campo. O título da metabox pode ser definido no elemento-chave do array, você adivinhou, 'title'. Se você estiver adicionando várias metaboxes no mesmo local (por exemplo, na pós-edição), você pode controlar o que vem primeiro fornecendo números diferentes em 'menu_order'.

Você pode controlar o design da metabox fornecendo um defaulteller seamlessem 'style'. No entanto, com o novo editor Gutenberg, isso tem um significado muito menor. O mesmo vale para a chave 'position'onde antigamente você podia posicionar a metabox abaixo do conteúdo do post ('normal'), ao lado ('side') ou logo após o título do post ('acf_after_title').

Tudo bem! Vamos mergulhar nos dois elementos mais interessantes do array; começando com a localização – que define onde a metabox aparece.

Localização

Isso é tudo sobre o que você coloca na chave 'location'. Mas antes de olharmos para as opções possíveis, precisamos entender sua estrutura de matriz.

'location'aceita um array com um array de elementos em um array! Resistir. Sim, porque é possível fornecer e combinar a lógica AND e OR no local (por exemplo, "mostrar na edição de postagem, mas não se o tipo de postagem for ‘livro’", ou "mostrar na tela de edição do usuário e também criar uma nova tela de usuário, mas para ambos os casos not if current role is author"). A maneira como você indica se é um AND ou OR é estruturando os arrays. É muito mais fácil mostrar do que explicar em palavras:

É assim que você combina dois elementos de localização com lógica AND (ambos devem ser verdadeiros):

E isso é para combinar locais com lógica OR (apenas um precisa ser verdadeiro):

Veja a diferença?

Certo, vamos seguir em frente. Cada opção de localização consiste em uma matriz de três elementos; 'param'que é onde adicionamos todos os locais diferentes 'operator', e 'value'. Operador é como comparar o valor, podendo ser '=='igual ou '!='não igual a.

Vamos examinar as opções possíveis, uma por uma.

Localização por tipo de postagem

Defina o tipo de postagem desejado em 'value'. Tenha em mente que você não pode fornecer uma matriz de vários tipos de postagem, você precisa combinar várias dessas matrizes em uma configuração AND.

Localização por status de postagem

Defina o status de postagem desejado como 'value'. Novamente, lembre-se de que você não pode fornecer uma matriz de vários status de postagem, você precisará fornecer cada valor desejado em uma configuração AND ou OR.

Localização por modelo de página

Isso é exibido apenas se a página selecionada (ou tipo de postagem personalizado com suporte a modelo de página) tiver escolhido o nome do modelo de página fornecido.

Localização por termo de taxonomia atribuído

Este local é para quando um post tem um termo específico atribuído a ele. Você precisará fornecer o nome da taxonomia, dois pontos e o slug do termo como valor.

Localização por tipo de página

O ACF agrupa propriedades especiais para páginas como “tipo de página”. Preocupa-se principalmente se a página atual é ou não uma página pai ou filha, mas também para direcionar páginas definidas como página inicial do WordPress ou página do blog.

Local: taxonomia

Um local para editar ou adicionar um termo em uma taxonomia.

Forneça o nome da taxonomia como 'value'. Lembre-se de que você não pode fornecer uma matriz de várias taxonomias, mas pode fornecer 'all'para segmentar todas as taxonomias.

Local: usuário

Este local é para adicionar ou editar um perfil de usuário.

Forneça 'edit‘ para direcionar apenas a tela de edição de usuários existentes, 'register'para direcionar apenas o formulário ao registrar um novo usuário ou ‘ all'para ambos os itens acima.

Local: item de menu

Desde o ACF 5.6, você também pode adicionar grupos de campos aos itens de menu.

Você pode definir valuepara allaplicar o grupo a todos os itens de menu ou pode especificar menus por local (locais registrados em seu tema) ou por ID de menu. Para uso de local 'location/<name>'– portanto, para um local chamado ‘ primary‘, você pode definir o valor 'location/primary'para aplicar seu grupo a um menu atribuído apenas a este local. Se você deseja segmentar um ID de menu específico, defina o valor para uma string desse ID.

Local: widget

O ACF ainda fornece uma localização dentro das configurações do widget sem modificar o código principal do widget.

Você pode segmentar todos os widgets com 'all'as 'value'ou segmentar um widget específico. Você precisará saber o “ID interno” do widget com o qual eles estão registrados.

Local: página de opções do ACF (somente Pro)

Com o ACF Pro, você pode usar o ACF para configurar páginas de administração personalizadas.

Forneça o nome que você definiu em acf_add_options_page‘s menu_slugas 'value'.

Localização: bloco (somente Pro 5.8+)

O ACF Pro (5.8+) possui um recurso para adicionar blocos Gutenberg com campos do ACF e controlar sua saída com PHP. Muito bacana para aqueles que ainda não mergulharam na adição de blocos personalizados do Gutenberg e o Javascript necessário.

Campos

Agora estamos entrando na parte mais interessante; os próprios campos. ACF oferece uma gama (realmente) ampla de tipos de campo, e vou reiterar; este guia não mostra o que é cada campo e como eles funcionam ou se parecem.

Na matriz principal que você fornece 'fields', acf_add_local_field_group()você fornece uma matriz em que cada campo é sua própria matriz.

O mínimo absoluto necessário para cada campo é o seguinte: um exclusivo 'key'que pode ser o que você quiser e você provavelmente nunca precisará consultá-lo. Você também precisa de 'name'qual é a meta-chave (post, user, term) na qual o valor do campo é salvo – e é a que você irá se referir ao obter o valor dos campos. Você deve fornecer um 'label'e, finalmente, o crucial 'type'que define qual tipo de campo estamos lidando. O restante dos campos depende de 'type'como veremos quando passarmos por cada tipo de campo abaixo.

Este é o código de esqueleto para adicionar um campo.

Tenha em mente que você precisará do acima para cada campo, mas para não repetir o mesmo código, cada tipo de campo abaixo incluirá apenas 'type'e quaisquer outros elementos necessários para esse tipo de campo.

Campo: entrada de texto

O campo mais simples de todos. Tudo o que realmente precisamos é:

Mas para personalizar ainda mais sua entrada de texto, você também pode fornecer qualquer um dos seguintes:

Campo: Entrada de número

Campo: Textarea

Campo: controle deslizante de alcance

Campo: Senha

Igual à entrada de texto, exceto que qualquer coisa que você digitar será coberta com * como seria de esperar em um campo de senha.

Campo: Imagem

Seleção de imagem única.

Campo: Arquivo

Semelhante à imagem acima, exceto que não visualiza o arquivo.

Você também pode fornecer 'mime_types' => '',e configurá-lo para, por exemplo, 'pdf,docx'permitir apenas arquivos PDF e DOCX.

Campo: Editor WYSIWYG

WYSIWYG é um editor “What You See Is What You Get” – aquele com o qual estávamos familiarizados antes da chegada de Gutenberg (TinyMCE).

O parâmetro 'media_upload'e 'delay'pode ser 1 (verdadeiro) ou 0 (falso).

Campo: Selecione

Campo: caixa de seleção

Observe que 'default_value'pode ser uma matriz de várias opções.

Campo: Botão de rádio

Definir 'other_choice'como true adiciona um botão de opção extra chamado "Outro" com uma entrada de texto onde o usuário pode digitar algo.

Campo: Verdadeiro/Falso (alternar)

O 'ui_on_text'e 'ui_off_text'só é válido se 'ui'for 1, pois eles estão definindo o que deve aparecer no alternador especial da interface do usuário.

Campo: Link

Dá a você um botão para inserir um link, digitando ou escolhendo o conteúdo do seu site WordPress (deve estar familiarizado com a adição de um link no editor normal do WordPress).

Campo: Postar Objeto

Dá uma caixa de seleção onde você pode escolher entre o conteúdo do WordPress. O select permite pesquisar digitando e todo o conteúdo é dividido por tipo de postagem. Você pode permitir que várias postagens sejam escolhidas ou apenas uma.

Campo: Relacionamento

Campo: Escolher termos em uma taxonomia

O seletor de termos de taxonomia tem quatro “modos” ou tipos diferentes, onde dois deles permitem várias escolhas.

Campo: Selecionar usuário

Campo: Google Maps

Lembre-se de que você precisa fornecer uma chave de API do GoogleMaps válida ao ACF para que esse campo funcione, assim:


add_filter('acf/fields/google_map/api', function($api) {
    $api['key'] = 'YOURAPIKEY';
    return $api;
});

Campo: DataPicker

Campo: seletor de data e hora

Campo: selecionador de tempo

Campo: Colorpicker

Campo: Galeria (somente ACF Pro)

Tipos especiais de campos

O ACF também oferece alguns tipos de campo que não economizam valor per se, mas são mais para fins organizacionais. Para tudo isso, defina 'name'como uma string vazia.

Mensagem HTML

Se você precisar simplesmente imprimir algum HTML sem salvar um valor, você pode usar type 'message'.

Repetidor (somente ACF Pro)

Um repetidor contém uma matriz de campos que podem ser repetidos.

O elemento sub_fieldsespera uma matriz de campos, assim como você configurou os campos acima.

Conclusão

Este não é de forma alguma um guia exaustivo, pois o ACF oferece uma ampla gama de opções e personalizações. Mas deve abranger as opções mais usadas e casos de uso personalizados. Pessoalmente, me vejo me referindo a isso com bastante frequência sempre que adiciono campos ACF para clientes. E mesmo para as opções mais estranhas, este guia é suficiente para que eu não precise inchar meus arquivos PHP com o código de exportação do ACF. Espero que isso tenha sido útil para você também!

Fonte de gravação: awhitepixel.com