Esercitazione: creare un tipo di campo Moduli di gravità personalizzati avanzati e come gestire più valori di input

In questo tutorial ti mostrerò come creare un tipo di campo Gravity Forms personalizzato avanzato. Il campo avrà più input e richiederà una gestione speciale per memorizzare e visualizzare i valori inviati.

Cosa faremo

In questo esempio sto assumendo un esempio di proprietario di un sito Web WordPress che si occupa delle consegne di pranzo sul posto di lavoro. Il proprietario ha un modulo per le persone da compilare che tipo di pranzo vogliono e quanti per ogni giorno della settimana. Questo può essere risolto come un metodo simile a una tabella per inserire un numero per qualsiasi corso in qualsiasi giorno in cui desiderano essere consegnati.

I corsi sono modificabili nelle impostazioni del campo nell’editor di moduli e possono essere modificati in qualsiasi momento. E per ogni invio di modulo, il proprietario del sito Web ottiene una panoramica completa dei valori inviati:

Ovviamente questo è solo un esempio e probabilmente dovrai adattarlo al tuo caso. Ma con questo caso di esempio abbiamo la possibilità di imparare a gestire più input in un singolo campo. Dovrebbe darti alcune idee su come gestire il tuo tipo di campo personalizzato.

Prima di iniziare a codificare

Prima di iniziare abbiamo bisogno di un posto dove aggiungere il nostro codice. Puoi aggiungerlo nel functions.phpfile del tuo tema o del tuo plug-in.

Il metodo che ho scelto di utilizzare è orientato agli oggetti, il che significa creare una classe che estenda la GF_Fieldclasse di Gravity Forms. Ti consiglio di mettere la classe in un file separato nel tuo progetto. Dovresti anche verificare che il plug-in Gravity Forms esista prima di includere la tua classe per evitare il crash del tuo sito.

Se sei interessato puoi dare un’occhiata alla documentazione di Gravity Forms su GF_Field. Troverai più funzioni e variabili di cui potresti aver bisogno per il tuo tipo di campo.

Estendendo la GF_Fieldclasse possiamo semplicemente scegliere di sovrascrivere le funzioni che dobbiamo modificare. Per quanto riguarda le funzioni che non sovrascriviamo, Gravity Forms eseguirà il valore predefinito definito all’interno di GF_Field. Nel tutorial di seguito esamineremo ogni funzione che dobbiamo sovrascrivere per il nostro campo personalizzato una per una. Senza ulteriori indugi, iniziamo!

Creazione di un tipo di campo personalizzato

Il primo passo è definire una classe PHP personalizzata che estenda GF_Field. Assegna alla classe un nome univoco e assicurati che sia incluso nel tuo progetto. Dopo la definizione della classe eseguiamo la register()funzione static GF_Fieldpassando un’istanza della nostra classe come parametro. Questo inizializza la nostra classe e registra il tipo di campo.

L’unica variabile richiesta di cui hai bisogno all’interno della tua classe è $type. La variabile di classe $typedeve essere univoca ed è un nome slug del tipo di campo. Nel mio esempio l’ho chiamato ‘ 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());
}

Con questo piccolo pezzo di codice il nostro tipo di campo personalizzato dovrebbe essere aggiunto come scelta disponibile nell’editor Gravity Forms. Per impostazione predefinita appare alla fine della casella "Campi standard". Poiché non abbiamo ancora assegnato un nome corretto al nostro campo (questo è il passaggio successivo), il pulsante è etichettato come il valore di $type.

Definizione del nome del campo

Il passo successivo è facile; semplicemente dando al nostro campo un nome migliore. Per fare ciò sovrascriviamo la funzione get_form_editor_field_title(). Tutto quello che dobbiamo fare è restituire una stringa con il nome del campo.

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

Con questa funzione nella nostra classe il pulsante per aggiungere il campo viene aggiornato con un’etichetta molto migliore.

Modifica della categoria del campo

Questo passaggio è facoltativo. Come impostazione predefinita, il nostro tipo di campo personalizzato appare nella casella "Campi standard", ma possiamo cambiarlo. Supponiamo di volere che appaia invece all’interno della casella "Campi avanzati".

Per cambiare la categoria in cui vogliamo che appaia il campo, sovrascriviamo la funzione get_form_editor_button(). Dobbiamo restituire un array associativo con due elementi. Come valore per la chiave ‘ group‘ fornisci il nome interno della categoria in cui desideri che appaia il pulsante. Le opzioni disponibili qui sono ‘ standard_fields‘, ‘ advanced_fields‘, ‘ post_fields‘ o ‘ pricing_fields‘. (Puoi anche creare la tua categoria, ma non è trattata qui). Il secondo elemento nell’array necessita della chiave ‘ text‘ e per questo restituiamo semplicemente il nome del campo chiamando get_form_editor_field_title(). Questa è la funzione che abbiamo appena creato sopra.

Ora il pulsante per aggiungere il nostro tipo di campo personalizzato viene spostato nella casella "Campi avanzati".

Attivazione delle impostazioni in loco

Se hai provato ad aggiungere il tipo di campo in un modulo, potresti aver notato che non ci sono impostazioni. Non puoi nemmeno modificare l’etichetta. Il modo in cui funziona è che tutti i tipi di impostazioni sono effettivamente presenti, sono semplicemente tutti nascosti con CSS di Gravity Forms. Dobbiamo definire individualmente quali impostazioni vogliamo abilitare e Gravity Forms mostrerà quindi le impostazioni scelte per noi.

Dobbiamo definire la funzione get_form_editor_field_settings()e restituire un array di tutte le impostazioni che non vogliamo nascondere per il nostro tipo di campo. Quali impostazioni vuoi aggiungere dipende interamente da te e dal tuo progetto. Tieni presente che il tuo campo dovrebbe supportare tutte le impostazioni che attivi, altrimenti non ha senso mostrare un’impostazione per esso.

Ho creato una rapida panoramica dei nomi delle impostazioni di seguito. Questo è tutt’altro che un elenco completo, perché ci sono molte impostazioni che sono praticamente utili solo per tipi di campo molto specifici. Ad esempio il formato del telefono, il formato data/ora e un sacco di impostazioni relative ai campi Posta e Prezzi.

Scheda Generale

• Etichetta campo:label_setting
• Descrizione campo:description_setting
• Scelte:choices_setting
• Necessario:rules_setting
• Nessun duplicato:duplicate_setting
• Abilita colonne:columns_setting
• Abilita la scelta "seleziona tutto":select_all_choices_setting
• Abilita la scelta "altro":other_choice_setting

Scheda Aspetto

• Segnaposto:placeholder_setting
• Visibilità dell’etichetta del campo e posizionamento della descrizione:label_placement_setting
• Messaggio di convalida personalizzato:error_message_setting
• Classe CSS personalizzata:css_class_setting
• Dimensione del campo:size_setting

Scheda Avanzate

• Etichetta campo amministratore:admin_label_setting
• Valore di default:default_value_setting
• Abilita inserimento password:password_field_setting
• Forza SSL:force_ssl_field_setting
• Visibilità:visibility_setting
• Consenti il ​​riempimento dinamico del campo:prepopulate_field_setting
• Abilita logica condizionale:conditional_logic_field_setting
• Abilita la logica condizionale della pagina:conditional_logic_page_setting

Come per il nostro esempio, le più importanti sono l’etichetta del campo, la descrizione, le scelte e se il campo è richiesto o meno. Consentiamo anche le impostazioni per la classe CSS, il messaggio di convalida personalizzato e la logica condizionale.

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'
    ];
}

Aggiorna l’editor di moduli e ora dovresti vedere tutte le impostazioni e le schede scelte apparire all’interno del nostro campo. Tutte le impostazioni vengono gestite e salvate automaticamente da Gravity Forms.

Vai avanti e aggiungi alcuni elementi nell’elenco Scelte in modo da avere qualcosa con cui lavorare. Ecco cosa ho impostato come esempio:

Definizione di scelte predefinite personalizzate

Se sei abituato ad usare, ad esempio, pulsanti di opzione o caselle di controllo in Gravity Forms, probabilmente avrai notato che vengono proposti con scelte come "Prima scelta", "Seconda scelta", "Terza scelta". Questo è il comportamento predefinito di Gravity Forms se nessuna scelta è stata salvata (prima) e si attiva solo su questi tipi di campo specifici. Ma per il nostro tipo di campo personalizzato, nessuna scelta verrà popolata. Questo lo rende un po’ ingombrante, perché non otterrai il pulsante "+" per aggiungere un’altra scelta. Dovresti usare il pulsante "Aggiungi in blocco/Scelte predefinite", aggiungere alcune scelte lì e, successivamente, avrai accesso ai pulsanti "+" per aggiungere scelte. Ma è facile definire alcune scelte personalizzate: tutto ciò che serve è definire una variabile array di classepublic $choicese Gravity Forms genereranno automaticamente scelte predefinite nel tuo campo quando lo aggiungi ai tuoi moduli.

Nota: questa è una variabile di classe, che puoi aggiungere nella parte superiore della classe, proprio sotto public $type. Ogni scelta deve essere un array, con la scelta come valore per la chiave ‘ text‘.

Tieni presente che se hai già aggiunto il campo al modulo, non compilerà retroattivamente le scelte. Questo diventa effettivo solo quando aggiungi un nuovo campo al modulo.

Nota: in Gravity Forms sembra essere possibile aggiungere anche chiavi ‘ value‘ a ciascuna scelta. Ma non ho questo per funzionare: i valori diventeranno automaticamente gli stessi del testo scelto.

Definire il valore del campo come array

Il passaggio successivo è piuttosto semplice, ma necessario. Come valori predefiniti per i campi in Gravity Forms sono stringhe. Abbiamo bisogno che il valore sia un array perché lavoriamo con più input. Per fare ciò definiamo la funzione is_value_submission_array()e restituiamo true.

public function is_value_submission_array() {
    return true;
}

Ciò garantisce che possiamo lavorare correttamente con il valore inserito dei nostri input multipli.

Rendering dell’output del campo

Quando si tratta di rendere l’output del campo, ci sono un paio di cose di cui essere consapevoli.

Prima di tutto è necessario scegliere tra due funzioni; get_field_input()o get_field_content(). Nel primo metodo Gravity Forms rende automaticamente l’elemento dell’elenco di wrapping, l’etichetta, la descrizione e il messaggio di errore del contenitore per la convalida nel tuo campo e tu controlli solo l’output del campo interno. Con il secondo metodo non accade nulla di tutto ciò e hai più controllo sull’output del campo. Tuttavia è necessario eseguire manualmente il rendering dell’etichetta, della descrizione e dei messaggi di errore. Il primo metodo, get_field_input(), è perfetto per la maggior parte dei casi.

La seconda cosa da tenere presente è che la funzione di rendering per il campo interessa tre diverse posizioni. I tre sono il rendering dell’output del campo nel frontend, l’anteprima per il campo all’interno dell’editor di moduli e infine anche il campo durante la modifica di una voce. Fortunatamente Gravity Forms offre funzioni per determinare facilmente a quale vista ci troviamo. Di solito il campo viene visualizzato allo stesso modo in tutti e tre i casi. Ma poiché il rendering di una tabella di grandi dimensioni con molti input diventa inutilmente goffo all’interno dell’editor di moduli, ho scelto di eseguire il rendering del campo in modo diverso all’interno dell’editor di moduli.

E infine, dobbiamo assicurarci che qualsiasi input ottenga un nameattributo appropriato in modo che Gravity Forms sia in grado di raccogliere il suo valore al momento dell’invio del modulo. Tutti gli input in Gravity Forms necessitano namedi attributi che seguano questa regola: name="input_{FIELD_ID}"(i campi a selezione multipla utilizzano un ID aggiuntivo, ma non dobbiamo preoccuparci di questo nel nostro caso). Abbiamo accesso all’ID del campo in quanto è una variabile di classe (da GF_Field). Ma nel nostro caso abbiamo detto a Gravity Forms che il valore è un array e non un valore singolare (passaggio precedente), quindi aggiungiamo parentesi dopo l’attributo name; name="input_{FIELD_ID}[]". Quindi, se il campo ha l’ID 4 all’interno di un modulo, l’attributo del nome dovrebbe essere " input_4[]".

Sto optando per l’utilizzo get_field_input()che viene fornito con tre parametri. Il primo parametro è l’oggetto form, di cui non abbiamo davvero bisogno per il nostro esempio. Il secondo parametro è il valore corrente. Questo può essere il valore del campo da $_POSTquando il modulo è stato inviato, ma senza successo. Possiamo conservare i precedenti valori inviati. Oppure, se la funzione è in esecuzione durante la modifica di una voce, il valore sarà il valore memorizzato dall’invio. Tratteremo il valore più da vicino in seguito. E il terzo parametro è l’oggetto entry, di cui non avremo bisogno per il nostro esempio.

Iniziamo a implementare get_field_input()che prevede il rendering finale come una stringa. Immediatamente decido di restituire una stringa vuota se siamo all’interno dell’editor di moduli, perché non voglio eseguire il rendering dell’intera tabella in questa vista. Possiamo utilizzare il metodo $this->is_form_editor()per verificare se siamo o meno all’interno della modifica del modulo. Puoi scegliere di saltare questo o eseguire il rendering di qualcos’altro se desideri un’anteprima del campo all’interno dell’editor di moduli.

Il passaggio successivo consiste nella creazione dell’HTML per una tabella che scorre su un array di giorni per generare le colonne e le righe per ogni elemento del corso. Ma poiché abbiamo bisogno di accedere all’array di giorni (colonne della tabella) in più posti, dovremmo definirlo come una variabile di classe, rendendolo accessibile da qualsiasi funzione al suo interno. Definisco una variabile di classe $delivery_dayscon una matrice dei giorni per cui voglio offrire la consegna.

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

Questo è solo un esempio! Potresti voler recuperare l’array per le colonne da qualche altra parte che non è hardcoded.

Torniamo get_field_input()e costruiamo la nostra tabella con gli input. Per prima cosa eseguo il ciclo sulla variabile di classe e genero le intestazioni della tabella. Quindi ripeto le scelte immesse nell’impostazione del campo per Scelte. Questo è accessibile dalla variabile di classe (da GF_Field) $this->choices. Per ogni scelta rendo un input con gli attributi del nome proprio. Abbiamo accesso all’ID del campo dalla GF_Fieldvariabile di classe $this->id.

Con questo codice in atto dovremmo ottenere una bella tabella renderizzata per il nostro tipo di campo nel frontend! Ovviamente l’HTML dipende interamente da te, questo è solo un esempio di base.

Lasciamo questa funzione per ora, ma ci torneremo in seguito per gestire il valore inviato!

Memorizzazione del valore correttamente

A partire da ora Gravity Forms salverà il nostro campo come un array unidimensionale popolato con i valori inseriti e le stringhe vuote in cui l’input era vuoto. Non ci sono informazioni sul giorno o sulla scelta a cui appartiene il valore, a parte l’indice. Dobbiamo trasformare questo array unidimensionale in un array associativo multidimensionale in cui memorizziamo il giorno e l’etichetta di scelta. Possiamo quindi accedere facilmente al valore del numero memorizzato per es $value['Ham sandwich']['Monday']. Dopo questa trasformazione dell’array, dobbiamo anche serializzare l’array in modo che Gravity Forms possa memorizzare correttamente il valore nel database.

Avremo bisogno di trasformare questo array di valori in più posti, quindi definirò una funzione separata per questo. La funzione accetta l’array unidimensionale e lo trasforma in un array multidimensionale con i valori memorizzati per i giorni e le scelte:

Ciò memorizzerà i nomi dei giorni e le scelte direttamente all’interno del valore del campo. In questo modo è possibile modificare le scelte in un momento successivo senza interrompere le vecchie voci.

Passiamo ora all’override della funzione che gestisce la memorizzazione del valore inviato; get_value_save_entry(). Viene fornito con cinque parametri, ma abbiamo solo bisogno del primo che è il valore inviato. All’interno della funzione passiamo il valore nella nostra funzione personalizzata sopra, serializziamo il suo ritorno e infine restituiamo il nuovo valore.

A questo punto Gravity Forms memorizzerà con successo i nostri valori proprio nel modo in cui li vogliamo! Tuttavia, il valore memorizzato è ora un array serializzato che Gravity Forms farà felicemente eco direttamente. Abbiamo bisogno di implementare funzioni per trasformarlo da un brutto array serializzato in un bel output ovunque ne abbiamo bisogno.

Visualizzazione del valore inviato

Ci sono tre posti in cui abbiamo bisogno per cambiare l’output del valore del nostro campo; l’elenco delle voci, guardando una singola voce e all’interno dei tag di unione di Gravity Forms. I tag di unione vengono utilizzati più comunemente nelle notifiche e-mail. Ad esempio {all_fields}, c’è un tag di unione che mostra i valori completi del modulo inviato nelle e-mail.

Poiché stiamo eseguendo il rendering dello stesso output in tre casi diversi, ha senso creare una funzione separata per esso. Ho definito una funzione personalizzata che accetta il valore; l’array multidimensionale non serializzato, come parametro. La funzione crea quindi un codice HTML che visualizza l’array in modo carino e restituisce la stringa. Ho optato per un <ul>elenco nidificato, ma puoi modificare l’output come preferisci.

Ottimo, iniziamo con il primo: l’elenco delle voci: get_value_entry_list(). Puoi scegliere di generare l’output completo qui, ma può diventare piuttosto goffo e lungo per la visualizzazione elenco, quindi ho optato per restituire semplicemente una stringa fissa che spiega che l’utente deve entrare nei dettagli della voce per vedere la panoramica completa.

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

Questo ovviamente dipende interamente da te, potresti optare per la visualizzazione solo del primo x numero di caratteri, ad esempio.

La seconda funzione è quella che interessa la visualizzazione di una singola voce: get_value_entry_detail():

Deserializziamo semplicemente l’array con la funzione di WordPress [maybe_unserialize](https://developer.wordpress.org/reference/functions/maybe_unserialize/)()e restituiamo l’output della stringa dalla nostra funzione personalizzata.

La funzione finale influisce sui tag di unione e assicura che il valore del nostro campo appaia buono anche all’interno delle e-mail: get_value_merge_tag().

Nota che non avremo bisogno di annullare la serializzazione del valore all’interno di questa funzione.

Con queste tre funzioni in atto, tutti i valori inviati dovrebbero avere un bell’aspetto ovunque! Ad esempio durante la visualizzazione di una voce inviata:

Tuttavia manca una cosa importante! A questo punto i nostri input non mantengono i valori precedentemente inviati e questo è piuttosto negativo.

Fai in modo che i nostri input mantengano il valore precedentemente inviato

Ci sono principalmente due casi in cui dobbiamo assicurarci che gli input mantengano i valori precedentemente inviati. Il primo caso è quando l’invio di un modulo non è riuscito (ad esempio l’utente ha dimenticato un campo obbligatorio). In questo momento tutti i nostri input perdono tutti i valori immessi in precedenza e l’utente deve reinserire tutti i valori. In secondo luogo, quando il proprietario del sito modifica una voce, gli input non vengono popolati con i valori inviati dall’invio, il che rende praticamente impossibile modificare i valori correttamente.

Per risolvere questo problema torniamo alla funzione get_field_input(). Il secondo parametro di questa funzione è il valore. Ma ricorda che questa funzione influisce sia sul rendering del frontend che sulla modifica della voce. Questo è importante perché il valore memorizzato è diverso in questi due casi. Se siamo al frontend e gestiamo l’invio del modulo, il valore è nel formato dell’array unidimensionale menzionato in precedenza. E se stiamo modificando una voce, il valore è nel formato di un array multidimensionale serializzato. Quindi dobbiamo tradurre correttamente il valore fornito get_field_input()per accedere facilmente ai valori effettivi.

Nel codice sopra, prima di iniziare a creare l’HTML per l’output del campo, creiamo una variabile $table_valueche contiene il valore tradotto correttamente. Usiamo GF_Fieldla funzione di ‘ is_entry_detail()per verificare se stiamo modificando o meno una voce. E poi per i nostri input è facile accedere ai valori corretti e impostarli come valueattributi degli input:

Con quanto sopra aggiornato get_field_input()tutti i nostri input personalizzati dovrebbero sempre essere popolati con il valore precedente; non importa se sta modificando una voce o riprovando a inviare un modulo.

A questo punto tutto ciò che riguarda il rendering e la memorizzazione dei nostri valori è fatto e funziona completamente. Ma c’è un’altra cosa che dobbiamo assolutamente sistemare.

Effettua la convalida "richiesta" del nostro pass sul campo

Gravity Forms ha controlli per vedere se il valore di un campo è vuoto o meno. Questo è spesso necessario quando il campo è impostato come richiesto. Quando un campo è obbligatorio non puoi inviare il modulo se è vuoto, giusto? Il problema per noi è che abbiamo più input e vogliamo che alcuni di essi siano vuoti. Questo diventa un problema se il nostro campo è impostato su obbligatorio. Gravity Forms sfortunatamente interpreta "è vuoto questo" in modo errato e richiede che tutti gli input siano compilati. Quindi dobbiamo aggiungere una regola che dice che se almeno uno dei nostri molti input è compilato, il valore totale del campo non è vuoto.

L’ultima funzione che dobbiamo sovrascrivere nella nostra classe è is_value_submission_empty(). Otteniamo solo l’ID del modulo come parametro per questa funzione, quindi è necessario estrarre il valore del campo utilizzando la funzione Gravity Forms per recuperarlo $_POSTdall’array: rgpost('input_<FIELD ID>'). Il ritorno dovrebbe essere l’array unidimensionale che abbiamo visto prima. Tutto quello che dobbiamo fare è scorrere l’array e restituire falsese troviamo un valore da qualche parte. Altrimenti ritorniamo truein quanto il valore del campo è effettivamente completamente vuoto.

Con la funzione di cui sopra in atto, il nostro campo non fallirà l’invio se è impostato su obbligatorio e almeno un input è compilato.

Conclusione e codice finale

Questo tutorial ti ha mostrato in dettaglio come creare il tuo tipo di campo avanzato personalizzato per Gravity Forms. Anche se il tuo progetto è diverso dal mio esempio, spero che tu abbia alcuni suggerimenti e a-ha lungo la strada. Trovo che la documentazione di Gravity Forms sia piuttosto carente in alcuni casi, e questo è il risultato di molti tentativi ed errori! Comunque, spero che questo ti sia stato di qualche utilità!

Per riferimento, ecco il codice completo nella sua interezza: