Como criar um formulário front-end com o ACF

Neste tutorial, mostrarei como criar um formulário front-end com Advanced Custom Fields (ACF). Vou entrar em detalhes sobre como ele funciona e como você pode ajustá-lo para atender às suas necessidades.

Advanced Custom Fields (ACF) é um plugin gratuito que ajuda você a adicionar configurações de campo de vários tipos a quase qualquer tipo de conteúdo no WordPress. Você pode adicionar campos a postagens, taxonomias, menus, widgets, usuários e até páginas de administração personalizadas. Seu uso principal é para admin, mas você pode usá-lo para gerar os campos no front-end também.

As aplicações para adicionar campos ACF ao front-end são muitas; você pode adicionar um formulário para criar e atualizar postagens, categorias ou usuários. Com algum código, você pode até criar um formulário de contato geral onde as respostas são salvas como postagens de tipo de postagem personalizadas e o código aciona notificações por e-mail nas respostas do formulário. Assim como um formulário de contato normal. Usar a funcionalidade de formulário front-end do ACF para criar formulários e permitir que os visitantes criem ou editem o conteúdo do site sem fazer login são os usos comuns. Mas use isso com cautela. Isso abre facilmente para spam e abuso e, na pior das hipóteses, os visitantes podem destruir o conteúdo ou as configurações do seu site. Você deve, no mínimo, exigir que os visitantes façam login com usuários válidos para obter acesso a formulários que podem alterar o conteúdo crítico do WordPress (perfil do usuário, postagens etc.).

O que vamos fazer

Estou assumindo que o site WordPress definiu um conjunto de campos adicionais em usuários de uma função personalizada (‘ member‘) usando o ACF. Esses usuários não têm acesso de administrador, mas queremos oferecer a eles a possibilidade de editar seus campos personalizados em seu perfil. A solução que optei é criar um template de página customizado para atualização do perfil, apenas mostrando o formulário se estiverem logados e com a função correta.

Estou mantendo isso bastante simples neste tutorial, então não incluirei um exemplo de adição de campos de perfil de usuário padrão no WordPress (e-mail, senha, etc). Isso foge um pouco do escopo deste tutorial. Só permitirei editar os campos ACF nesta página de edição de perfil.

Com o ACF, criei um grupo de campos com um conjunto de configurações para usuários membros:

E eu tenho um modelo de página personalizado no meu tema que atualmente se parece com isso – no momento apenas um modelo de página simples padrão;

Na linha #11verificamos se o usuário atual está logado e tem o papel personalizado member. Altere a função ou regra mínima para o que você deseja permitir neste formulário de front-end. Apenas lembre-se de que mesmo o papel mais baixo no WordPress, subscriber, tem acesso à edição de seu perfil no painel de administração.

Resumindo, queremos adicionar esses campos em cada membro a essa página de front-end personalizada:

Como os formulários front-end do ACF funcionam

Você precisa adicionar duas chamadas de função no modelo que deseja no formulário front-end; [acf_form_head](https://www.advancedcustomfields.com/resources/acf_form_head/)()e [acf_form](https://www.advancedcustomfields.com/resources/acf_form/)().

A função acf_form_head()deve ser colocada no topo do seu modelo, antes de qualquer saída. Normalmente em um modelo isso significa antes [get_header](https://developer.wordpress.org/reference/functions/get_header/)(). A chamada de função garante que todos os scripts e estilos sejam adicionados para que os campos ACF sejam renderizados corretamente, assim como todas as funcionalidades para processamento, validação e envio de trabalho. Não precisamos adicionar nenhum parâmetro a esta função.

A acf_form()função é aquela que renderiza o formulário front-end e deve ser colocada onde você deseja que o formulário apareça. Ele aceita uma variedade de configurações. Precisamos informar no mínimo quais campos ou grupos mostrar e onde salvá-los.

Quando se trata de decidir quais campos mostrar, você normalmente fornece um grupo de campos (propriedade field_groups). Mas a acf_form()função também suporta o fornecimento de campos únicos específicos (propriedade fields). Você também pode fornecer vários campos ou grupos de campos para combiná-los no mesmo formulário. Devido a isso field_groupsespera uma matriz. Portanto, mesmo que você queira mostrar apenas um grupo de campos, precisará fornecer esse ID ou slug dentro de uma matriz.

A segunda propriedade obrigatória que você precisa fornecer acf_form()é de onde os dados devem ser carregados e onde eles devem ser salvos, na propriedade post_id. Não se deixe enganar pelo nome ‘post’. As regras para post_idsão as mesmas quando você usa get_field(), se estiver familiarizado com o trabalho com o ACF antes. Se os campos forem para uma postagem (postagem, página, postagem de tipo de postagem personalizada), você só precisa fornecer o ID aqui. Mas se você quiser carregar e atualizar dados sobre usuários, siga este formato: user_{user ID}. Da mesma forma com campos para uma categoria: category_{category ID}. Confira todas as regras sob o título "Obter um valor de objetos diferentes" na documentação do ACF emget_field().

Adicionando o formulário front-end do ACF ao nosso modelo

Primeiro adicionamos o acf_form_head()no topo, logo antes get_header()– mas depois da declaração do template de página (line #3). Então, no local onde queremos renderizar o formulário, adicionamos acf_form()duas propriedades.

Precisamos descobrir nosso ID de grupo de campos. Se você adicionou o grupo de campos por código (tenho um post detalhado sobre como adicionar campos ACF por código ), você já forneceu um slug de grupo de campos. Você então forneceria o slug para a field_groupspropriedade, em uma matriz. Se você adicionou o grupo de campos no painel de administração, você precisa abrir o grupo no navegador e verificar a URL. Estamos interessados ​​no ID que aparece depois de ” ?post=“:

No meu exemplo, o ID é 1145. Então é isso que eu forneço na matriz de field_groups.

PS: Eu não recomendo codificar um ID, pois esse ID será diferente em cada instância do WordPress! Se você estiver trabalhando em uma instalação local, bem como em um servidor de teste e produção, definitivamente recomendo adicionar os campos por código. Dessa forma, você pode definir um nome de grupo de campos e ele funcionará em qualquer lugar.

Quanto à post_idpropriedade, posso obter o ID do usuário atual usando a função do WordPress [get_current_user_id](https://developer.wordpress.org/reference/functions/get_current_user_id/)(). Eu concateno a string ‘ user_‘ e o retorno desta função como post_id.

E é basicamente isso!

Se eu visitar esta página logado como usuário membro, obterei os valores atuais para esse usuário. Todos os tipos de campo ACF funcionam e têm boa aparência. E posso atualizar os valores usando o formulário front-end e ver que eles também são atualizados no admin.

Personalizando ainda mais o formulário

Podemos ajustar ainda mais as configurações passadas para acf_form(). Consulte a documentação do ACF em acf_form() para ver todas as configurações possíveis.

No momento, nosso formulário de perfil de usuário exibe "Publicação atualizada" quando as configurações são enviadas. Isso não faz sentido para as configurações de perfil. Podemos personalizar a mensagem com a propriedade updated_message.

Se desejar, você pode definir uma URL diferente para redirecionar após o envio do formulário. Como padrão, a mesma página é recarregada com o parâmetro GET ‘ ?updated=true‘. Você pode especificar um URL específico para uma página de agradecimento ou, se o formulário for para uma postagem, talvez você queira redirecionar para visualizar essa postagem. Podemos fornecer a URL na propriedade return.

Se quisermos um texto diferente no botão de envio do formulário, podemos especificar isso na propriedade submit_value.

Você também pode dizer acf_form()para não renderizar a <form>tag. Se você quiser combinar o formulário do ACF com seu próprio formulário personalizado, você pode definir forme falsedigitar o <form>e <input type="submit"/>manualmente. Se você fizer isso, o ACF ainda poderá atualizar os valores, mas você precisará atualizar quaisquer outros campos em seu formulário personalizado.

Acionando ações ao enviar formulários

Às vezes, você pode querer acionar alguma função ou eventos personalizados quando um formulário de front-end é atualizado. Um exemplo comum é escrever uma função que envia uma notificação por email em cada envio de formulário.

Campos personalizados avançados oferece dois ganchos úteis para quando os campos são atualizados; a ação [acf/save_post](https://www.advancedcustomfields.com/resources/acf-save_post/)e o filtro [acf/pre_save_post](https://www.advancedcustomfields.com/resources/acf-pre_save_post/). Novamente, não se deixe enganar pelo nome ‘post’. Eles são acionados para qualquer atualização de campos do ACF, incluindo campos para um usuário, categoria, menu e assim por diante.

O filtro acf/pre_save_posté executado apenas em formulários front-end usando acf_form(). Como parâmetro para este filtro temos, o post_idmesmo valor que passamos acima. O filtro espera que você retorne. Lembre-se de que precisamos analisar isso se não estivermos nos referindo a um ID de postagem. Por exemplo, para o usuário, você precisaria fazer algo como:post_id``acf_form()``post_id

add_filter('acf/pre_save_post', function($post_id) {
    if (strpos($post_id, 'user_') === false) {
        return $post_id;
    }
 
    $user_id = intval(substr($post_id, 5));  // Extracts the user ID
 
    // Do your thing. You'll find the submitted values in $_POST
 
    return $post_id;
});

Alternativamente, você pode usar o gancho acf/save_post– mas lembre-se de que ele também é acionado no admin. Como parâmetro para este gancho, você obterá post_id, o mesmo que acf/pre_save_post. Uma coisa importante a ser lembrada ao usar acf/save_posté que você pode usar a prioridade do gancho para controlar se sua função é executada antes dos campos serem salvos ou depois. Uma função vinculada à prioridade 10 ou superior será acionada depois que os campos forem salvos. E uma prioridade menor que 10 será acionada antes que o ACF salve os valores.

add_action('acf/save_post', function($post_id) {
    // You can fetch the values with standard get_field()
});
 
add_action('acf/save_post', function($post_id) {
    // You can access the submitted values in $_POST
}, 8);

Quando você enganchou a função antes de salvar (prioridade menor que 10), você pode comparar os valores enviados com o que o ACF salvará. Você pode fazer get_field()para obter o valor atual e compará-los com o valor correspondente em $_POST.

Se você quiser fazer algo apenas quando os campos forem atualizados no front-end, basta verificar se estamos em admin com [is_admin](https://developer.wordpress.org/reference/functions/is_admin/)(). Abaixo está um exemplo de como você configuraria notificações por e-mail quando um usuário estiver atualizando suas configurações no front-end;

add_action('acf/save_post', function($post_id) {
    if (strpos($post_id, 'user_') === false) {
        return $post_id;
    }
 
    if (is_admin()) {
        return;  // Bail if we are updating in admin
    }
 
    $user_id = intval(substr($post_id, 5));
 
    // Use get_field() to get the saved/submitted values if needed
    // Then use wp_mail() to send an email
});