Tutorial: Criar um tipo de campo de formulários de gravidade personalizados avançados e como lidar com vários valores de entrada

Neste tutorial, mostrarei como criar um tipo de campo personalizado avançado Gravity Forms. O campo terá várias entradas e precisará de tratamento especial para armazenar e exibir os valores enviados.

O que vamos fazer

Neste exemplo, estou assumindo um exemplo de proprietário de um site WordPress que lida com entregas de almoço em um local de trabalho. O proprietário tem um formulário para as pessoas preencherem o tipo de almoço que desejam e quantos para cada dia da semana. Isso pode ser resolvido como um método semelhante a uma tabela de inserir um número para qualquer curso em qualquer dia que eles desejem entregar.

Os cursos são editáveis ​​nas configurações do campo no editor de formulários e podem ser alterados a qualquer momento. E para cada envio de formulário, o proprietário do site obtém uma visão geral completa dos valores enviados:

Obviamente, este é apenas um exemplo e você provavelmente precisará ajustar isso ao seu caso. Mas com este caso de exemplo, temos a chance de aprender a lidar com várias entradas em um único campo. Ele deve fornecer algumas ideias sobre como lidar com seu próprio tipo de campo personalizado.

Antes de começar a codificar

Antes de começarmos, precisamos de um lugar para adicionar nosso código. Você pode adicionar isso no seu tema functions.phpou no seu arquivo de plugin.

O método que escolhi é orientado a objetos, o que significa criar uma classe que estende a GF_Fieldclasse do Gravity Forms. Eu recomendo colocar a classe em um arquivo separado em seu projeto. Você também deve verificar se o plug-in Gravity Forms existe antes de incluir sua classe para evitar travar seu site.

Se você estiver interessado, pode dar uma olhada na documentação do Gravity Forms no GF_Field. Você encontrará mais funções e variáveis ​​que podem ser necessárias para seu tipo de campo.

Ao estender a GF_Fieldclasse, podemos simplesmente optar por substituir as funções que precisamos alterar. Quanto às funções que não substituímos, o Gravity Forms executará o padrão definido dentro do GF_Field. No tutorial abaixo, veremos cada função que precisamos substituir para nosso campo personalizado, uma por uma. Sem mais delongas, vamos começar!

Criando um tipo de campo personalizado

A primeira etapa é definir uma classe PHP personalizada que estende arquivos GF_Field. Dê um nome exclusivo à classe e certifique-se de que ela esteja incluída em seu projeto. Após a definição da classe, executamos a register()função estática GF_Fieldpassando uma instância de nossa classe como parâmetro. Isso inicializa nossa classe e registra o tipo de campo.

A única variável necessária que você precisa dentro de sua classe é $type. A variável de classe $typedeve ser exclusiva e é um nome de slug do seu tipo de campo. No meu exemplo eu dei o nome de ‘ food_delivery‘.

if (class_exists('GF_Field')) {
    class FoodDelivery extends GF_Field {
        public $type = 'food_delivery';
 
        // The rest of the code is added here...
    }
    GF_Fields::register(new FoodDelivery());
}

Com este pequeno pedaço de código, nosso tipo de campo personalizado deve ser adicionado como uma opção disponível no editor Gravity Forms. Por padrão, ele aparece no final da caixa "Campos padrão". Como ainda não demos um nome próprio ao nosso campo (essa é a próxima etapa), o botão é rotulado como o valor de $type.

Definindo o nome do campo

O próximo passo é fácil; simplesmente dando ao nosso campo um nome melhor. Para fazer isso, sobrescrevemos a função get_form_editor_field_title(). Tudo o que precisamos fazer é retornar uma string com o nome do campo.

public function get_form_editor_field_title() {
    return esc_attr__('Food Delivery', 'txtdomain');
}

Com esta função em nossa classe o botão para adicionar o campo é atualizado com um rótulo muito melhor.

Alterando a categoria do campo

Esta etapa é opcional. Como padrão, nosso tipo de campo personalizado aparece na caixa "Campos padrão", mas podemos alterar isso. Vamos supor que queremos que apareça dentro da caixa “Advanced Fields".

Para alterar a categoria em que queremos que o campo apareça, sobrescrevemos a função get_form_editor_button(). Precisamos retornar um array associativo com dois elementos. Como valor para a chave ‘ group‘ você fornece o nome interno da categoria na qual deseja que o botão apareça. As opções disponíveis aqui são ‘ standard_fields‘, ‘ advanced_fields‘, ‘ post_fields‘ ou ‘ pricing_fields‘. (Você também pode criar sua própria categoria, mas isso não é abordado aqui). O segundo elemento do array precisa da chave ‘ text‘ e para isso simplesmente retornamos o nome do campo chamando get_form_editor_field_title(). Esta é a função que acabamos de criar acima.

Agora o botão para adicionar nosso tipo de campo personalizado é movido para a caixa “Campos Avançados”.

Ativando as configurações de campo

Se você tentou adicionar o tipo de campo em um formulário, deve ter notado que não há nenhuma configuração. Você não pode nem editar o rótulo. A maneira como isso funciona é que todos os tipos de configurações realmente estão lá, eles estão simplesmente todos ocultos com CSS por Gravity Forms. Precisamos definir individualmente quais configurações queremos habilitar, e o Gravity Forms exibirá as configurações escolhidas para nós.

Precisamos definir a função get_form_editor_field_settings()e retornar um array de todas as configurações que não queremos ocultar para nosso tipo de campo. Quais configurações você deseja adicionar depende inteiramente de você e do seu projeto. Lembre-se de que seu campo deve oferecer suporte a quaisquer configurações que você ativar, caso contrário, não faz sentido mostrar uma configuração para ele.

Eu criei uma visão geral rápida dos nomes das configurações abaixo. Isso está longe de ser uma lista completa – porque há muitas configurações que são úteis apenas para tipos de campo muito específicos. Por exemplo, formato de telefone, formato de data/hora e várias configurações relacionadas a campos de postagem e campos de preços.

Guia geral

• Legenda do campo:label_setting
• Descrição do campo:description_setting
• Escolhas:choices_setting
• Requeridos:rules_setting
• Sem duplicatas:duplicate_setting
• Ativar colunas:columns_setting
• Habilite a opção “selecionar tudo”:select_all_choices_setting
• Habilite a opção “outro”:other_choice_setting

Aba Aparência

• Espaço reservado:placeholder_setting
• Visibilidade do rótulo do campo e posicionamento da descrição:label_placement_setting
• Mensagem de validação personalizada:error_message_setting
• Classe CSS personalizada:css_class_setting
• Tamanho do campo:size_setting

Guia Avançado

• Rótulo do campo de administrador:admin_label_setting
• Valor padrão:default_value_setting
• Habilitar entrada de senha:password_field_setting
• Força SSL:force_ssl_field_setting
• Visibilidade:visibility_setting
• Permitir que o campo seja preenchido dinamicamente:prepopulate_field_setting
• Habilite a lógica condicional:conditional_logic_field_setting
• Ative a lógica condicional da página:conditional_logic_page_setting

Quanto ao nosso exemplo, os mais importantes são o rótulo do campo, descrição, opções e se o campo é obrigatório ou não. Também permitimos configurações para classe CSS, mensagem de validação personalizada e lógica condicional.

public function get_form_editor_field_settings() {
    return [
        'label_setting',
        'choices_setting',
        'description_setting',
        'rules_setting',
        'error_message_setting',
        'css_class_setting',
        'conditional_logic_field_setting'
    ];
}

Atualize o editor de formulários e agora você deve ver todas as configurações e guias escolhidas aparecerem dentro do nosso campo. Todas as configurações são tratadas e salvas automaticamente pelo Gravity Forms.

Vá em frente e adicione alguns itens na lista de opções para que tenhamos algo para trabalhar. Aqui está o que eu configurei como exemplo:

Definindo opções padrão personalizadas

Se você está acostumado a usar, por exemplo, botões de rádio ou caixas de seleção em Gravity Forms, você provavelmente notou que eles vêm com opções como “Primeira Escolha”, “Segunda Escolha”, “Terceira Escolha”. Este é o comportamento padrão do Gravity Forms se nenhuma escolha tiver sido salva (antes) e isso é acionado apenas nesses tipos de campo específicos. Mas para nosso tipo de campo personalizado, nenhuma opção será preenchida. Isso o torna um pouco complicado, porque você não receberá o botão “+” para adicionar outra opção. Você teria que usar o botão “Adicionar em massa/Escolhas predefinidas”, adicionar algumas opções lá, e depois disso, você terá acesso aos botões “+” para adicionar opções. Mas é fácil definir algumas escolhas personalizadas – tudo que você precisa é definir uma variável de array de classepublic $choicese o Gravity Forms gerará automaticamente opções predefinidas em seu campo quando você o adicionar aos seus formulários.

Nota: Esta é uma variável de classe, que você pode adicionar no topo da classe, logo abaixo de public $type. Cada escolha precisa ser um array, com a escolha como valor para a chave ‘ text‘.

Lembre-se de que, se você já adicionou o campo ao formulário, ele não preencherá retroativamente as opções. Isso só entra em vigor quando você adiciona um novo campo ao formulário.

Nota: Em Gravity Forms parece ser possível também adicionar chaves ‘ value‘ a cada escolha. Mas não consegui fazer isso funcionar – os valores se tornarão automaticamente os mesmos que o texto de escolha.

Definindo o valor do campo como array

O próximo passo é bem simples, mas necessário. Como valores padrão para campos em Gravity Forms são strings. Precisamos que o valor seja um array porque trabalhamos com várias entradas. Para fazer isso, definimos a função is_value_submission_array()e retornamos true.

public function is_value_submission_array() {
    return true;
}

Isso garante que possamos trabalhar corretamente com o valor inserido de nossas múltiplas entradas.

Renderizando a saída de campo

Quando se trata de renderizar a saída do campo, há algumas coisas a serem observadas.

Primeiro é que você precisa escolher entre duas funções; get_field_input()ou get_field_content(). No primeiro método, o Gravity Forms renderiza automaticamente o elemento da lista de encapsulamento, o rótulo, a descrição e o contêiner para a mensagem de erro de validação para seu campo e você controla apenas a saída do campo interno. Com o segundo método, nada disso acontece e você tem mais controle sobre a saída do campo. No entanto, você precisa renderizar manualmente o rótulo, a descrição e as mensagens de erro. O primeiro método, get_field_input(), é perfeitamente adequado para a maioria dos casos.

A segunda coisa a ser observada é que a função de renderização do campo afeta três locais diferentes. Os três são a renderização da saída do campo no frontend, a visualização do campo dentro do editor de formulários e, finalmente, também o campo ao editar uma entrada. Felizmente, o Gravity Forms oferece funções para determinar facilmente em qual visualização estamos. Normalmente, você renderizaria o campo da mesma maneira nos três casos. Mas como renderizar uma tabela grande com muitas entradas fica desnecessariamente desajeitado dentro do editor de formulários, optei por renderizar o campo de maneira diferente dentro do editor de formulários.

E, finalmente, precisamos garantir que todas as entradas recebam um nameatributo adequado para que o Gravity Forms possa coletar seu valor no envio do formulário. Todas as entradas no Gravity Forms precisam de nameatributos que seguem esta regra: name="input_{FIELD_ID}"(campos de seleção múltipla usam um ID adicional, mas não precisamos nos preocupar com isso para o nosso caso). Temos acesso ao ID do campo, pois é uma variável de classe (de GF_Field). Mas no nosso caso dissemos ao Gravity Forms que o valor é um array e não um valor singular (passo anterior), então adicionamos colchetes após o atributo name; name="input_{FIELD_ID}[]". Portanto, se o campo tiver o ID 4 dentro de um formulário, o atributo name deve ser ” input_4[]“.

Estou optando por usar get_field_input()que vem com três parâmetros. O primeiro parâmetro é o objeto de formulário, que realmente não precisamos para nosso exemplo. O segundo parâmetro é o valor atual. Este pode ser o valor do campo de $_POSTquando o formulário foi tentado, mas sem sucesso. Podemos reter os valores enviados anteriormente. Ou se a função estiver sendo executada na edição de uma entrada, o valor será o valor armazenado do envio. Vamos lidar com o valor mais de perto mais tarde. E o terceiro parâmetro é o objeto de entrada, que também não precisaremos para nosso exemplo.

Vamos começar a implementar get_field_input()o que espera a renderização final como uma string. Logo de cara eu decido retornar uma string vazia se estivermos dentro do editor de formulários – porque não quero renderizar a tabela completa nesta view. Podemos usar o método $this->is_form_editor()para verificar se estamos ou não dentro do form edit. Você pode optar por ignorar isso ou renderizar outra coisa se quiser uma visualização do campo dentro do editor de formulários.

O próximo passo é construir o HTML para uma tabela que faz um loop em uma matriz de dias para gerar as colunas e as linhas para cada item do curso. Mas como precisamos acessar a matriz de dias (colunas da tabela) em vários lugares, devemos defini-la como uma variável de classe, tornando-a acessível a partir de qualquer função dentro dela. Eu defino uma variável de classe $delivery_dayscom uma matriz dos dias para os quais quero oferecer entrega.

class FoodDelivery extends GF_Field {
    public $type = 'food_delivery';
 
    private $delivery_days = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday'];
 
    public function get_form_editor_field_title() {
        ...
}

Este é apenas um exemplo! Você pode querer buscar a matriz para as colunas de outro lugar que não seja codificado.

Vamos voltar get_field_input()e construir nossa tabela com entradas. Primeiro, faço um loop sobre a variável de classe e gero os cabeçalhos da tabela. Em seguida, faço um loop sobre as opções inseridas na configuração de campo para Opções. Isso é acessível a partir da variável de classe (de GF_Field) $this->choices. Para cada escolha eu renderizo uma entrada com os atributos de nome apropriados. Temos acesso ao ID do campo a partir GF_Fieldda variável de classe de $this->id.

Com este código em vigor, devemos obter uma boa tabela renderizada para nosso tipo de campo no frontend! Obviamente, o HTML depende inteiramente de você, este é apenas um exemplo básico.

Deixamos esta função por enquanto, mas voltaremos a ela mais tarde para lidar com o valor enviado!

Armazenando o valor corretamente

A partir de agora, o Gravity Forms salvará nosso campo como um array unidimensional preenchido com os valores inseridos e strings vazias onde a entrada estava vazia. Não há informações sobre a qual dia ou escolha o valor pertence, exceto o índice. Precisamos transformar esse array unidimensional em um array associativo multidimensional onde armazenamos o dia e o rótulo de escolha. Podemos então acessar facilmente o valor numérico armazenado para, por exemplo, $value['Ham sandwich']['Monday']. Após essa transformação de array, também precisamos serializar o array para que o Gravity Forms possa armazenar o valor corretamente no banco de dados.

Precisaremos transformar essa matriz de valores em vários lugares, então definirei uma função separada para isso. A função aceita o array unidimensional e o transforma em um array multidimensional com os valores armazenados para dias e opções:

Isso armazenará os nomes dos dias e as opções diretamente dentro do valor do campo. Fazendo isso, é possível alterar as opções posteriormente sem quebrar as entradas antigas.

Agora vamos sobrescrever a função que manipula o armazenamento do valor enviado; get_value_save_entry(). Ele vem com cinco parâmetros, mas só precisamos do primeiro que é o valor enviado. Dentro da função passamos o valor para nossa função customizada acima, serializamos seu retorno e finalmente retornamos o novo valor.

Neste ponto, o Gravity Forms armazenará com sucesso nossos valores da maneira que queremos! No entanto, o valor armazenado agora é uma matriz serializada que o Gravity Forms ecoará com prazer. Precisamos implementar funções para transformá-lo de um array serializado feio em uma saída bonita onde quer que precisemos.

Exibindo o valor enviado

Há três lugares que precisamos alterar a saída do valor do nosso campo; a lista de entradas, olhando para uma única entrada e dentro das etiquetas de mesclagem do Gravity Forms. As etiquetas de mesclagem são usadas com mais frequência em notificações por e-mail. Por exemplo {all_fields}, é uma tag de mesclagem que exibe os valores completos do formulário enviado em e-mails.

Como estamos renderizando a mesma saída em três casos diferentes, faz sentido criar uma função separada para ela. Defini uma função personalizada que aceita o valor; o array multidimensional não serializado, como parâmetro. A função então cria algum HTML que exibe o array de uma maneira bonita e retorna a string. Optei por uma <ul>lista aninhada, mas você pode alterar a saída como quiser.

Ótimo, vamos começar com o primeiro: a lista de entradas: get_value_entry_list(). Você pode optar por gerar a saída completa aqui, mas pode ficar muito desajeitado e longo para o modo de exibição de lista, então optei por simplesmente retornar uma string fixa que explica que o usuário precisa entrar nos detalhes da entrada para ver a visão geral completa.

public function get_value_entry_list($value, $entry, $field_id, $columns, $form) {
    return __('Enter details to see delivery details', 'txtdomain');
}

Obviamente, isso depende inteiramente de você, você pode optar por exibir apenas o primeiro número x de caracteres, por exemplo.

A segunda função é a que afeta a visualização de uma única entrada: get_value_entry_detail():

Nós simplesmente deserializamos a matriz com a função do WordPress [maybe_unserialize](https://developer.wordpress.org/reference/functions/maybe_unserialize/)()e retornamos a saída da string de nossa função personalizada.

A função final afeta as tags de mesclagem e garante que o valor do nosso campo fique bem dentro dos emails: get_value_merge_tag().

Observe que não precisaremos desserializar o valor dentro desta função.

Com essas três funções em vigor, todos os valores enviados devem parecer muito bons em todos os lugares! Por exemplo, ao visualizar uma entrada enviada:

No entanto, há uma coisa importante faltando! Neste ponto, nossas entradas não retêm os valores enviados anteriormente e isso é muito ruim.

Faça com que nossos insumos mantenham o valor enviado anteriormente

Existem principalmente dois casos em que precisamos garantir que as entradas mantenham os valores enviados anteriormente. O primeiro caso é quando o envio de um formulário falhou (por exemplo, o usuário esqueceu um campo obrigatório). Neste momento, todas as nossas entradas perdem todos os valores inseridos anteriormente e o usuário precisa reinserir todos os valores novamente. Em segundo lugar, quando o proprietário do site edita uma entrada, as entradas não são preenchidas com os valores enviados do envio – o que torna praticamente impossível editar os valores corretamente.

Para corrigir isso, voltamos à função get_field_input(). O segundo parâmetro para esta função é o valor. Mas lembre-se de que esta função afeta a renderização do frontend e a edição de entrada. Isso é importante porque o valor armazenado é diferente nesses dois casos. Se estivermos no frontend e manipulando o envio do formulário, o valor estará no formato do array unidimensional mencionado anteriormente. E se estivermos editando uma entrada, o valor estará no formato de um array multidimensional serializado. Portanto, precisamos traduzir adequadamente o valor fornecido get_field_input()para acessar facilmente os valores reais.

No código acima, antes de começarmos a criar o HTML para a saída do campo, criamos uma variável $table_valueque contém o valor traduzido corretamente. Usamos GF_Fielda função ‘s is_entry_detail()para verificar se estamos editando ou não uma entrada. E então para nossas entradas é fácil acessar os valores apropriados e defini-los como valueatributos das entradas:

Com o acima atualizado get_field_input(), todas as nossas entradas personalizadas devem sempre ser preenchidas com o valor anterior; não importa se está editando uma entrada ou tentando novamente um envio de formulário.

Neste ponto, tudo sobre renderização e armazenamento de nossos valores está pronto e funcionando perfeitamente. Mas há mais uma coisa que definitivamente precisamos consertar.

Faça nosso campo passar a validação “obrigatória”

Gravity Forms tem verificações para ver se o valor de um campo está vazio ou não. Isso geralmente é necessário quando o campo é definido como obrigatório. Quando um campo é obrigatório, você não pode enviar o formulário se estiver vazio, certo? O problema para nós é que temos várias entradas e queremos permitir que algumas delas fiquem vazias. Isso se torna um problema se nosso campo estiver definido como obrigatório. Infelizmente, o Gravity Forms interpreta "está vazio" errado e exige que todas as entradas sejam preenchidas. Portanto, precisamos adicionar uma regra que diga que, se pelo menos uma de nossas muitas entradas for preenchida, o valor total do campo não ficará vazio.

A função final que precisamos substituir em nossa classe é is_value_submission_empty(). Obtemos apenas o ID do formulário como parâmetro para esta função, portanto, precisamos extrair o valor do campo usando a função Gravity Forms para buscá-lo no $_POSTarray: rgpost('input_<FIELD ID>'). O retorno deve ser o array unidimensional que vimos antes. Tudo o que precisamos fazer é percorrer o array e retornar falsese encontrarmos um valor em algum lugar. Caso contrário, retornamos, truepois o valor do campo está de fato completamente vazio.

Com a função acima em vigor, nosso campo não falhará no envio se estiver definido como obrigatório e pelo menos uma entrada estiver preenchida.

Conclusão e código final

Este tutorial mostrou em detalhes como criar seu próprio tipo de campo avançado personalizado para Gravity Forms. Mesmo que seu projeto seja diferente do meu exemplo, espero que você tenha algumas dicas e a-ha’s ao longo do caminho. Acho a documentação do Gravity Forms bastante carente em alguns casos, e isso é resultado de muita tentativa e erro! Enfim, espero que isso tenha sido de alguma utilidade para você!

Para referência, aqui está o código completo em sua totalidade: