Campo del form

Il blocco gutenberg Campo del form è un blocco personalizzato del wordpress Gpci framework; nella maggior parte dei casi verrà utilizzato insieme a un blocco form ma è anche possibile utilizzarlo indipendentemente, ad esempio per avviare funzioni javascript basate sugli input o i click dell'utente. Il blocco è composto da un div html che racchiude label e campo ed è indicato utilizzare il gruppo di controlli posizionamento con proprietà css display:flex per definire istantaneamente la direzione e la posizione dei componenti. Con questo blocco è possibile anche generare uno o più campi calcolati da campi wordpress (come titolo e riassunto) o campi metabox in modo analogo a MB Frontend Submission.

Controlli del campo del form

Dopo avere inserito il blocco è necessario configurarlo per definire il campo. Alcuni attributi sono comuni a tutti i tipi di campo, altri invece sono specifici per tipo (come textarea e select). Va specificato che quasi tutti i controlli specifici per questo blocco sono relativi al campo e non al div contenitore come nel caso del gruppo di controlli attributi. Essenzialmente questo blocco può essere usato in questi modi:

configurare un campo html completamente personalizzabile
generare uno o più campi dinamicamente da campi wordpress
generare uno o più campi dinamicamente da campi metabox

E' importante anche specificare alcune cose:

se generati dei campi metabox non verrà replicato lo stesso codice html di MB Frontend Submission ma il codice sarà il più possibile simile a quello generato normalmente da questo blocco
se generati dei campi metabox solo alcuni tipi di campo e parametri metabox sono supportati (se un tipo di campo non è supportato verrà generato un ErrorMessage, stessa cosa per alcuni parametri come cloneable)
i campi supportati dei campi metabox sono gli stessi dei campi html
i parametri attualmente supportati dei campi metabox sono:
- hide_from_front
- required (per ora verrà anche aggiunto uno span con asterisco alla label)
- class
- columns
- prepend
- append
- attributi html
- fare attenzione con gli altri parametri (soprattutto quelli relativi a salvataggi personalizzati in quanto genereranno incongruenze)
se generati dei campi dinamici (sia wodpress che metabox) con i valori iniziali impostati automaticamente (vedere controllo sotto) all'id del campo e del contenitore verrà aggiunto il post id corrente
i campi personalizzati predefiniti del framework per ora non saranno mai generati

Controlli comuni

I controlli comuni a tutti i tipi di campo sono tutti visibili nella barra laterale InspectorControl dinamicamente in base alle scelte:

Tipo di campo

E' possibile scegliere la configurazione del campo scegliendo tra:

Html

il campo sarà singolo e completamente personalizzabile come elemento html tramite i controlli dedicati.

Campi wordpress (post)

il campo diventerà uno o più campi wordpress relativi ai post scelti singolarmente tramite i controlli dedicati.

Campi wordpress (commenti)

il campo diventerà uno o più campi wordpress relativi ai commenti scelti singolarmente tramite i controlli dedicati.

Campi metabox (post)

Il campo diventerà tutti i campi metabox registrati a determinato post type. Questa opzione serve a generare automaticamente i campi personalizzati per creare o modificare un post.

Campi metabox (user)

Il campo diventerà tutti i campi metabox registrati agli utenti. Questa opzione serve a generare automaticamente i campi personalizzati per creare o modificare un utente.

Gruppi metabox

Il campo diventerà tutti i campi metabox calcolati dai gruppi metabox specificati: inserire gli id delle metabox separandoli con una virgola. Questa opzione serve a generare liberamente campi dalle metaboxes specificate per eseguire azioni personalizzate.

Campi metabox

Il campo diventerà uno o più campi metabox scelti singolarmente da una metabox: inserire l'id della metabox che contiene i campi e gli id dei campi da generare separando tutti gli argomenti con una virgola. Esempio: ordini,nome,cognome dove ordini è l'id della metabox mentre nome e cognome sono 2 campi contenuti. Questa opzione serve a generare liberamente campi dalla metabox specificata per eseguire azioni personalizzate.

I controlli riservati ai campi dinamici (quindi non i campi html) sono:

Post type

Se selezionato un post type i campi saranno generati solo se registrati al post type selezionato. Per i campi wordpress (esempio titolo e riassunto) verrà controllato se il post type ha il supporto per il campo corrispondente, mentre per i campi metabox appare solo per la scelta campi metabox (post).

Auto imposta i valori iniziali

Se attivato auto imposta i valori iniziali dei campi generati ai valori corrispondenti (serve nei form di modifica), inoltre all'id del campo e del contenitore verrà aggiunto il post ID corrente.

Ordina in colonne

Se attivato genera attorno ai campi html aggiuntivo per replicare indicativamente il comportamento del componente aggiuntivo MB Columns. E' sufficiente che i campi abbiano il parametro columns assegnato, il componente può anche essere disattivato. Se un campo non ha il parametro columns assegnato gli sarà assegnata una larghezza di 12 colonne.

I controlli riservati ai campi wordpress relativi ai post sono:

Titolo del post

Selezionare se si vuole aggiungere un campo testuale per l'inserimento del titolo, sarà possibile anche modificare label, placeholder e aggiungere required.

Contenuto del post

Selezionare se si vuole aggiungere un campo di tipo textarea per l'inserimento del contenuto, sarà possibile anche modificare label, placeholder e aggiungere required. Sarà anche possibile aggiungere TinyMce come per il campo html.

Riassunto del post

Selezionare se si vuole aggiungere un campo di tipo textarea per l'inserimento del riassunto, sarà possibile anche modificare label, placeholder e aggiungere required.

I controlli riservati ai campi wordpress relativi ai commenti sono:

Contenuto del commento

I controlli riservati al campo html sono:

Nome

Stringa che verrà usata come attributo name. Per poter usare il valore spedito tramite un form questo campo è obbligatorio. Come regola generale utilizzare lettere, trattini medi/bassi e numeri e iniziare con una lettera.

Tipo di valore

Eventuale conversione dinamica relativa l'attributo id. Utilizzare se il campo è all'interno di un ciclo query.

Id

Stringa che verrà usata come attributo id, aggiornerà automaticamente anche l'attributo ancora del blocco (in avanzate). Compilare se la label viene visualizzata ( per l'attributo for ) oppure il campo è all'interno di un ciclo query ( in questo caso convertire a valore dinamico ). Come regola generale utilizzare lettere, trattini medi/bassi e numeri e iniziare con una lettera.

Label

Stringa che verrà usata come contenuto del tag label: compilare sempre in quanto se nascosta verrà usata come attributo aria-label.

Nascondi label

Nasconde la label.

Tag

Selezionare il tag del campo compilabile.

Type

Compare se il tag lo richiede, selezionare l'attributo type per completare ad esempio il tag input.

Dati crittografati

Compare solo se il campo è un input type hidden. Se attivato aggiunge automaticamente l'attributo data-to-encrypt all'input in modo che il form contenente il campo crittografi automaticamente il valore. Questo controllo evita semplicemente di doverlo fare manualmente con il controllo attributi. In questo caso probabilmente (ma non necessariamente) il nome del campo sarà un campo wordpress (come post_title) o un campo personalizzato, impostarne il valore utilizzando il controllo valore iniziale.

Placeholder

Compare solo se inerente. Se compilato, aggiungerà l'attributo placeholder al tag del campo.

Disabled

Se true, aggiungerà l'attributo disabled al tag del campo.

Required

Se true, aggiungerà l'attributo required al tag del campo e farà comparire il controlli successivi per Oninvalid.

Tipo di messaggio

Scegliere come verrà visualizzato il messaggio tra le seguenti scelte:

fumetto - classico messaggio del browser per campo invalido ma con un messaggio personalizzato. In questo caso verrà anche aggiunto automaticamente un attributo oninput per il ricontrollo automatico del campo
alert - il messaggio verrà visualizzato in un alert
codice personalizzato - inserire direttamente il codice javascript per visualizzare il messaggio secondo le proprie preferenze

Oninvalid

Inserire qui il messaggio o il codice javascript per far visualizzare un'eventuale notifica di campo invalido all'utente.

Larghezza

Se compilato, verrà aggiunto al tag del campo un attributo style contenente la proprietà width definita. Questo controllo ha associato un gruppo di pulsanti con alcuni valori comuni preassegnati, è comunque sempre scrivibile manualmente.

Valore iniziale

Conversione dinamica: assegnerà automaticamente al campo un valore predefinito.

Controlli specifici per tipo di campo

Vari tipi di campo hanno attributi aggiuntivi richiesti o utili al loro funzionamento. Questi controlli compaiono soltanto per i tipi di campo inerenti dopo agli altri in un pannello dedicato. Tenere presente che per tutti gli attributi non ancora integrati qui è sempre possibile settarli manualmente utilizzando il gruppo di controlli attributi.

Checkbox

I controlli aggiuntivi per gli input di tipo checkbox sono:

Checked

Se attivata la checkbox sarà spuntata di default.

Date

I controlli aggiuntivi per gli input di tipo date sono:

Min

Inserire l'eventuale data minima selezionabile nel formato YYYY-MM-DD.

Max

Inserire l'eventuale data massima selezionabile nel formato YYYY-MM-DD.

Step

Inserire l'eventuale intervallo in giorni selezionabili partendo dalla data minima (oppure odierna se non specificata). Se ad esempio selezioniamo un lunedì come data minima e impostiamo 7 come step potremo selezionare soltanto i lunedì nel selettore data.

Textarea

I controlli aggiuntivi per le textarea sono:

Rows

Setta l'attributo rows.

Cols

Setta l'attributo cols.

TinyMce

Se attivato: la textarea viene sostituita un editor TinyMCE generato dalla funzione wp_editor. E' importante notare che per ora solo la textarea viene sostituita non il wrapper del blocco.

Parametri di configurazione

Se attivato TinyMce è possibile settare qui i parametri di configurazione tramite una conversione dinamica (così da poter utilizzare globali php, funzioni, shortcodes o direttamente una stringa php). Ci sono alcune cose da precisare:

questi parametri rappresentano il parametro $settings della funzione wp_editor, quindi dovrà ritornare un array associativo con queste chiavi
è obbligatorio assegnare un id alla textarea oppure ci saranno errori javascript nel frontend, in quanto questo id sarà il valore del parametro $editor_id
al parametro $content invece come valore predefinito sarà assegnato il risultato del valore iniziale spiegato prima

Se non settato nessun parametro verranno utilizzati dei parametri di default. Potrebbero cambiare ma al momento sono:

[
  'wpautop'             => true,
  'media_buttons'       => false,
  'default_editor'      => '',
  'drag_drop_upload'    => false,
  'textarea_name'       => /*attributo name oppure id textarea*/
  'textarea_rows'       => /*valore attributo rows oppure 20*/,
  'tabindex'            => '',
  'tabfocus_elements'   => ':prev,:next',
  'editor_css'          => '',
  'editor_class'        => '',
  'teeny'               => false,
  'tinymce'             => [
    'language'           => 'it',
    'browser_spellcheck' => false,
    'resize'             => 'vertical'
    'menubar'            => false,
    'branding'           => false,
    'toolbar1'           => 'formatselect, bold, italic, bullist, numlist, blockquote, alignleft, aligncenter, alignright, link, wp_more, spellchecker, fullscreen, wp_adv',
    'toolbar2'           => 'strikethrough, hr, forecolor, pastetext, removeformat, charmap, outdent, indent, undo, redo, wp_help',
    'plugins'            => 'charmap, colorpicker, hr, lists, media, paste, tabfocus, textcolor, fullscreen, wordpress, wpautoresize, wpeditimage, wpemoji, wpgallery, wplink, wpdialogs, wptextpattern, wpview, image'
  ],
  'quicktags' => [
    'buttons' => 'strong,em,underline,ul,ol,li,link,code'
  ]
]

Notare che il parametro name sarà automaticamente sovrascritto, anche se impostato nei parametri, in modo da essere uguale a quello impostato nel blocco.

Select

I controlli aggiuntivi i select sono:

Multiple

Aggiunge l'attributo multiple.

Opzioni statiche

E' possibile aggiungere opzioni a piacere cliccando sul pulsante aggiungi option. Per ogni opzione settare il value, il nome visibile e, se desiderato, anche l'attributo selected. L'attributo selected sarà applicato solo all'ultima opzione con l'attributo (per select senza attributo multiple) e a tutti i tag option (per select con attributo multiple)

Opzioni dinamiche

Le opzioni dinamiche possono essere attivate insieme alle statiche ma al momento compariranno sempre per ultime. Se attivate le opzioni dinamiche comparirà il controllo origine riempimento in cui è possibile decidere come le opzioni saranno configurate selezionando tra:

Campo metabox

Riempire i due campi seguenti:

Id metabox: scrivere l'id dellla metabox (gruppo di campi) che contiene il campo personalizzato
Id campo: scrivere l'id del campo personalizzato (il select) da cui ottenere le opzioni

Nome funzione

Scrivere nel campo apposito il nome della funzione senza argomenti, la funzione deve generare tutti i tags option desiderati. Esempio:

Nome funzione: ListaUtenti

function ListaUtenti() {
    $users = get_users();
    $option = '';    
    foreach( $users as $user ){
        $option .= '<option value="'.$user->ID.'">'.$user->display_name.'</option>'; 
    }
    return $option;
}

Php

Scrivere nella textarea Il codice php per ritornare i tag option. Il codice sarà processato via eval quindi attenzione a cosa si scrive qui. Esempio (stesso risultato di prima):

$users = get_users();
$option = '';    
foreach( $users as $user ){
	$option .= '<option value="'.$user->ID.'">'.$user->display_name.'</option>'; 
}

//ritornare sempre i tags sottoforma di stringa
return $option;

Informazioni aggiuntive

Nel caso di campo del form per caricare file ( quindi input type=file ), ricordarsi di aggiungere al blocco form che lo contiene l'attributo enctype=multipart/form-data per caricare correttamente i files.

Inoltre per caricare valori multipli nei campi supportati aggiungere [] alla fine del nome (esempio: nome_select[] o nome_files[]).