Como fazer blocos personalizados do Gutenberg com o Advanced Custom Fields Pro

Desde a versão 5.8 do Advanced Custom Fields (ACF) Pro, você pode usar o ACF para criar blocos personalizados do Gutenberg. Tudo que você precisa lidar são os modelos PHP. Isso torna muito fácil para desenvolvedores que ainda não têm experiência no Javascript moderno necessário para criar blocos personalizados para Gutenberg com qualquer um dos tipos de campo que o ACF tem a oferecer. Lembre-se de que essa funcionalidade está disponível apenas na versão paga (Pro) dos Campos personalizados avançados. Não está disponível na versão gratuita, então você precisará comprar uma licença.

Se você é um editor do WordPress ou um webmaster que não quer se aprofundar na codificação, este post é definitivamente para você. No entanto, se você deseja ser um desenvolvedor de temas ou plugins do WordPress, recomendo dar o passo para aprender a criar seus próprios blocos personalizados. No entanto, usar Campos Personalizados Avançados para criar blocos pode fornecer uma boa introdução ao manuseio de blocos personalizados no Gutenberg.

Criar um bloco Gutenberg com ACF

Existem basicamente três etapas simples na criação de um bloco Gutenberg personalizado com campos personalizados avançados. A primeira é fácil e provavelmente familiar; configurando os campos (configurações) que você deseja ter em seu bloco. O segundo passo é usar a função do ACF para registrar um bloco Gutenberg. E o terceiro passo é escrever o template PHP para o bloco. Você simplesmente escreve o HTML e lida com as configurações da mesma forma que faria com os campos ACF de outra forma. E é isso! (Ok, talvez haja um quarto passo; estilizar seu bloco. Mas não vou entrar nisso neste post).

Crie suas configurações/campos

Se você já usou Campos Personalizados Avançados, provavelmente sabe como configurar campos. Você pode usar a interface do usuário de administração do Advanced Custom Field para fazer isso. Ou se você quiser que as configurações do bloco sejam incorporadas ao seu plugin ou tema, escreva as configurações com PHP. Eu tenho um post de referência completo sobre como adicionar configurações de ACF com PHP.

A coisa crítica que você precisa fazer com o seu grupo é definir o local como "Bloquear". Mas como ainda não registramos nosso bloco, ele será padronizado como "Todos". Deixe assim, salve seus campos e vamos prosseguir para registrando nosso bloco.

Registrar um bloco Gutenberg

No código do seu tema functions.phpou plugin você precisa escrever uma função ligada a acf/init, e chamar [acf_register_block](https://www.advancedcustomfields.com/resources/acf_register_block_type/)()para registrar um bloco. Como essa função é bem nova no ACF e depende de um plugin para ser ativado, recomendo que você envolva seu código dentro de um if-check para garantir que seu tema ou plugin não travará seu WordPress.

Registrar um bloco com o ACF é, na verdade, semelhante a como registraríamos manualmente um bloco personalizado do Gutenberg. Com o ACF, você precisa fornecer um nome slugified exclusivo para seu bloco no name. Eu recomendo usar um nome autoexplicativo, por exemplo, ctapara um bloco de Call to action, ou author-cardpara um bloco mostrando autores ou similares. Se você estiver um pouco familiarizado com o Gutenberg, você deve estar ciente de que todos os blocos devem ser registrados com um namespace, a /e, em seguida, seu nome de slug. Por exemplo, o namespace do WordPress é core, então, por exemplo, o bloco de parágrafo no WordPress é chamado core/paragraph. Com o ACF o namespace será acf, então, por exemplo, o bloco acima será registrado no Gutenberg como acf/yourblock. Se você estiver registrando seus campos com PHP, como verá mais adiante, precisamos nos lembrar disso.

Em categoryvocê define em qual categoria do Gutenberg você quer que seu bloco apareça. No momento, os valores possíveis são common, formatting, layout, widgetsou embed. Se você criar categorias personalizadas do Gutenberg, poderá adicioná-las a elas, se desejar. Quanto a iconfornecer qualquer nome de ícone do WordPress Dashicons (menos o “dashicons-“).

Para informar ao ACF como renderizar este bloco, você tem duas opções: fornecer um nome de função para a chave render_callback(como acima) ou fornecer um nome de modelo em seu tema para a chave render_template. Então, se você preferir se referir diretamente a um modelo, por exemplo, template-parts/block-yourblock.phpem seu tema, simplesmente faça assim e remova o render_callback:

Conecte seu grupo de campo ao seu bloco registrado

Quando estiver satisfeito com o código de registro do bloco, é hora de conectar o bloco às configurações feitas anteriormente. Se você criou os campos em admin, basta voltar e escolher seu bloco em Location. E se você adicionou o grupo de campos com PHP, no local forneça o valor ‘ acf/yourblock‘ onde yourblockestá o que você forneceu como nameacima.

Escreva o modelo

O passo final, e o mais divertido, é escrever o template para a saída do bloco!

A localização da saída de renderização do bloco depende do que você decidiu usar no registro do bloco, render_callbackou render_template.

Se você forneceu um nome de função, render_callbackvocê precisa definir esta função no functions.phpcódigo do seu tema ou plugin. Você obtém quatro parâmetros para sua função, como verá abaixo:

O primeiro parâmetro, $block, contém certas informações de Gutenberg. Por exemplo, cada bloco do Gutenberg quase sempre terá className, que você deve definir como class em seu wrapper mais externo. $block['align']para alinhamento também pode ser definido e algo que você deseja adicionar também. O segundo parâmetro, $content, sempre estará vazio com ACF (isso seria preenchido se você adicionasse blocos aninhados, mas isso não é possível com ACF). O booleano $is_previewserá verdadeiro se estivermos olhando para a renderização do bloco no modo de visualização no editor Gutenberg. E finalmente $post_idé o post em que este bloco é adicionado.

Quanto aos campos, você busca campos como faria normalmente, com get_field(). A saída HTML depende completamente de você e de como deseja gerar seus campos.

Se você forneceu um arquivo de modelo render_template, basta criar o arquivo no local especificado em seu tema. Dentro dele, você tem acesso às mesmas variáveis ​​globais exatas da função acima (por exemplo $block). Por exemplo:

E isso é tudo. É assim que é simples criar seus blocos personalizados do Gutenberg com o ACF.

Conclusão

Por mais fácil que tenha sido, contar com um plugin – principalmente um pago – não é uma boa solução final se você deseja desenvolver temas ou plugins. Lembre-se de que seus blocos deixarão de funcionar se você mover o código do seu tema para outro WordPress sem o ACF Pro. Ou onde suas configurações de campo não foram configuradas (a menos que você as tenha incorporado em seu código com PHP ou certifique-se de exportá-las e importá-las). Como um desenvolvedor de tema (ou plugin) que distribui código, você não pode esperar que cada usuário compre sua própria licença do ACF Pro para fazer seu tema funcionar! Mas esta é uma boa solução temporária para quem não pode ou não precisa codificar.

Se você está convencido de que precisa dar o passo e aprender Javascript e Gutenberg, confira minha introdução ao post de Gutenberg ou a categoria Gutenberg neste site para saber mais.