Riferimento completo per l’aggiunta di gruppi di campi personalizzati avanzati e campi per codice
Il plug -in Advanced Custom Fields (ACF) supporta la configurazione completa di campi e gruppi in base al codice PHP nel tuo tema o plug-in. Il vantaggio di fare ciò è che tutti i tuoi campi saranno disponibili indipendentemente dall’istanza di WordPress su cui stai lavorando (ad esempio se devi passare da un server locale, di prova e un server live). Puoi impostare tutti i campi nell’amministratore di ACF e utilizzare lo strumento di esportazione per esportarlo in PHP.
Tuttavia, se lo fai frequentemente, potresti notare che l’esportazione PHP di ACF contiene molto codice che rende i tuoi file PHP non necessari. In alcuni casi è meglio scrivere il codice da soli, con il minimo indispensabile, per un codice più pulito nel tuo tema o plugin. Questa guida mira a fornire un riferimento completo su come scrivere manualmente aggiungendo campi e gruppi ACF in PHP. Tieni presente che non entrerà nei dettagli di ciascun tipo di campo poiché presuppone che tu abbia già familiarità con i diversi campi possibili in ACF.
Ma prima; alcune precauzioni
Per mantenere buoni standard di codice e garantire che il tuo sito WordPress non vada in crash, dovresti sempre controllare se le funzioni o le classi utilizzate dal tuo codice esistono effettivamente. Soprattutto quando si tratta di plug-in che possono essere facilmente disattivati o nemmeno installati su un sito, dovresti sempre avvolgere il tuo codice specifico del plug-in in un if-test che controlli se le funzioni che utilizzi esistono, prima di utilizzarle.
Come per ACF puoi farlo verificando se la classe 'acf'esiste o se esiste la funzione per aggiungere campi e gruppi, 'acf_add_local_field_group',. Avvolgi uno di quelli attorno al codice seguente.
if (function_exists('acf_add_local_field_group')) {
// Your ACF specific code here
}
// OR:
if (class_exists('acf')) {
// Your ACF specific code here
}Codice scheletro
Per aggiungere meta box (gruppi) e campi utilizziamo l’hook chiamato acf/init. All’interno della funzione chiamiamo la funzione acf_add_local_field_group()con un array come parametro. All’interno di quell’array c’è la configurazione completa per il gruppo e tutti i suoi campi. I più importanti sono le chiavi dell’array 'fields'e 'location'. Per la chiave dell’array 'fields'si fornisce l’array per tutti i campi e per la chiave 'location'si forniscono le impostazioni di dove dovrebbe apparire la metabox. Questo post entrerà nel dettaglio delle possibili opzioni che hai per ciascuna di queste di seguito.
Questo è il minimo indispensabile per aggiungere un gruppo, a parte i campi e la posizione:
add_action('acf/init', function() {
acf_add_local_field_group([
'key' => 'group_my_fields',
'title' => __('My fields', 'txtdomain'),
'label_placement' => 'top',
'menu_order' => 0,
'style' => 'default',
'position' => 'normal',
'fields' => [],
'location' => [],
]);
});Ogni gruppo ha bisogno di una chiave univoca, ma il nome stesso non ha molta importanza (per noi). Se stai aggiungendo più gruppi, non dimenticare di modificare il 'key'campo. Il titolo della metabox può essere impostato nell’elemento chiave dell’array, hai indovinato, 'title'. Se stai aggiungendo più metabox nella stessa posizione (ad es. durante la modifica del post), puoi controllare quale viene prima fornendo numeri diversi in 'menu_order'.
Puoi controllare il design del metabox fornendo uno dei due defaulteller seamlessin 'style'. Tuttavia, con il nuovo editore Gutenberg questo ha un significato molto meno importante. Lo stesso vale per la chiave 'position'dove ai vecchi tempi si poteva posizionare il metabox sotto il contenuto del post ('normal'), sul lato ('side') o subito dopo il titolo del post ('acf_after_title').
Bene! Immergiamoci nei due elementi più interessanti dell’array; a partire dalla posizione – che definisce dove appare il metabox.
Posizione
Si tratta di ciò che metti nella chiave 'location'. Ma prima di esaminare le possibili opzioni, dobbiamo capire la sua struttura di array.
'location'accetta un array con un array di elementi in un array! Sostenere. Sì, perché è possibile fornire e combinare la logica AND e OR nella posizione (es. "mostra nella modifica del post ma non se il tipo di post è ‘libro’", oppure "mostra nella schermata di modifica dell’utente e crea anche una nuova schermata dell’utente ma per entrambi i casi non se il ruolo corrente è l’autore"). Il modo in cui si indica se è un AND o un OR è strutturando gli array. È molto più facile da mostrare che da spiegare a parole:
Ecco come combinare due elementi di posizione con la logica AND (entrambi devono essere veri):
'location' => [
[
[
// location 1
],
[
// location 2
]
]
]E questo serve per combinare le posizioni con la logica OR (solo una deve essere vera):
'location' => [
[
[
// location 1
]
],
[
[
// location 2
]
]
]Vedi la differenza?
OK, andiamo avanti. Ogni opzione di posizione consiste in una matrice di tre elementi; 'param'che è dove aggiungiamo tutte le diverse posizioni 'operator', e 'value'. L’operatore è come confrontare il valore e può essere '=='uguale o '!='diverso a.
Esaminiamo le possibili opzioni una per una.
Località per tipo di posta
[
'param' => 'post_type',
'operator' => '==',
'value' => 'post'
]Imposta il tipo di post desiderato in 'value'. Tieni presente che non puoi fornire un array di più tipi di post, devi combinare più di questi array in una configurazione AND.
Posizione per stato del post
[
'param' => 'post_status',
'operator' => '==',
'value' => 'publish'
]Imposta lo stato del post desiderato come 'value'. Ancora una volta, tieni presente che non puoi fornire una matrice di più stati dei post, dovrai fornire ogni valore desiderato in una configurazione AND o OR.
Posizione per modello di pagina
[
'param' => 'page_template',
'operator' => '==',
'value' => 'template-name.php'
]Questo viene mostrato solo se la pagina selezionata (o il tipo di post personalizzato con supporto per il modello di pagina) ha scelto il nome del modello di pagina fornito.
Posizione per termine tassonomico assegnato
// Post category only
[
'param' => 'post_category',
'operator' => '==',
'value' => 'category:some-category-slug'
]
// Any taxonomy
[
'param' => 'post_taxonomy',
'operator' => '==',
'value' => 'my_custom_taxonomy:some-category-slug' // <taxonomy name>:<term slug>
]Questa posizione è per quando a un post è assegnato un termine specifico. Dovrai fornire il nome della tassonomia, i due punti e lo slug del termine come valore.
Posizione per tipo di pagina
ACF raggruppa le proprietà speciali per le pagine come "tipo di pagina". Riguarda principalmente il fatto che la pagina corrente sia o meno una pagina padre o figlio, ma anche per il targeting di pagine impostate come prima pagina di WordPress o pagina del blog.
// Front page
[
'param' => 'page_type',
'operator' => '==',
'value' => 'front_page'
]
// Posts page
[
'param' => 'page_type',
'operator' => '==',
'value' => 'posts_page'
]
// Top level page only
[
'param' => 'page_type',
'operator' => '==',
'value' => 'top_level'
]
// Top level page that has children
[
'param' => 'page_type',
'operator' => '==',
'value' => 'parent'
]
// Children level pages
[
'param' => 'page_type',
'operator' => '==',
'value' => 'children'
]Località: tassonomia
Una posizione per la modifica o l’aggiunta di un termine in una tassonomia.
[
'param' => 'taxonomy',
'operator' => '==',
'value' => 'category' // Or 'all' for all taxonomies
]Fornisci il nome della tassonomia come 'value'. Tieni presente che non puoi fornire una matrice di più tassonomie, ma puoi fornire 'all'come target tutte le tassonomie.
Località: utente
Questa posizione serve per aggiungere o modificare un profilo utente.
[
'param' => 'user_form',
'operator' => '==',
'value' => 'all' // 'edit' || 'register'
]Fornire 'edit‘ per indirizzare solo la schermata di modifica degli utenti esistenti, 'register'per indirizzare solo il modulo quando si registra un nuovo utente, o ‘ all'per entrambi i precedenti.
Da ACF 5.6 puoi anche aggiungere gruppi di campi alle voci di menu.
[
'param' => 'nav_menu_item',
'operator' => '==',
'value' => 'all'
]Puoi impostare valueper allapplicare il gruppo a tutte le voci di menu oppure puoi specificare i menu per posizione (località registrate nel tuo tema) o per ID menu. Per l’uso della posizione 'location/<name>', quindi per una posizione denominata ‘ primary‘ puoi impostare il valore su 'location/primary'per applicare il tuo gruppo a un menu assegnato solo a questa posizione. Se vuoi scegliere come target un ID menu specifico, imposta il valore su una stringa di quell’ID.
Posizione: widget
ACF ti fornisce anche una posizione all’interno delle impostazioni del widget senza modificare il codice del widget principale.
[
'param' => 'widget',
'operator' => '==',
'value' => 'tag_cloud' // or 'all' for all widgets
]Puoi scegliere come target tutti i widget con 'all'come 'value'o scegliere come target un widget specifico. Sarà necessario conoscere l'”ID interno" del widget con cui sono registrati.
Posizione: pagina Opzioni ACF (solo Pro)
Con ACF Pro puoi utilizzare ACF per configurare pagine di amministrazione personalizzate.
[
'param' => 'options_page',
'operator' => '==',
'value' => 'acf-options-myoptionspage'
]Fornisci il nome che hai impostato in acf_add_options_page‘s menu_slugas 'value'.
Posizione: blocco (solo Pro 5.8+)
ACF Pro (5.8+) ha una funzione per aggiungere blocchi Gutenberg con campi di ACF e controllarne l’output con PHP. Abbastanza elegante per coloro che non si sono ancora tuffati nell’aggiunta di blocchi Gutenberg personalizzati e del Javascript richiesto.
[
'param' => 'block',
'operator' => '==',
'value' => 'acf/cta' // or 'all' for all ACF blocks
]Campi
Ora entriamo nella parte più interessante; i campi stessi. ACF offre una gamma (veramente) ampia di tipi di campo e lo ribadirò; questa guida non ti mostra cos’è ogni campo e come funzionano o come appaiono.
Nell’array principale fornito 'fields'in acf_add_local_field_group()si fornisce un array in cui ogni campo è il proprio array.
Il minimo assoluto richiesto per ogni campo è il seguente: un unico 'key'che può essere qualsiasi cosa tu voglia e probabilmente non avrai mai bisogno di farvi riferimento. Hai anche bisogno 'name'di quale sia la meta chiave (post, utente, termine) in cui il valore del campo viene salvato come – e questa è quella a cui ti riferirai quando ottieni il valore dei campi. Dovresti fornire un 'label'e infine il cruciale 'type'che definisce quale tipo di campo stiamo gestendo. Il resto dei campi dipende da 'type'come vedremo quando esamineremo ogni tipo di campo di seguito.
Questo è il codice dello scheletro per aggiungere un campo.
'fields' = [
[
'key' => 'field_my_field',
'label' => __('My field', 'txtdomain'),
'name' => 'my_field',
'type' => 'text',
]
]Tieni presente che avrai bisogno di quanto sopra per ogni campo, ma per non ripetere lo stesso codice, ogni tipo di campo sottostante includerà solo 'type'e qualsiasi altro elemento necessario per quel tipo di campo.
Campo: immissione di testo
Il campo più semplice di tutti. Tutto ciò di cui abbiamo veramente bisogno è:
[
'type' => 'text',
]Ma per personalizzare ulteriormente il tuo input di testo puoi anche fornire uno dei seguenti:
[
'default_value' => 'Default value',
'prepend' => 'Prepend text',
'append' => 'Appended text',
]Campo: immissione del numero
[
'type' => 'number',
'min' => 0,
'max' => 100,
'step' => 1,
'default_value' => 'Default value',
'prepend' => 'Prepend text',
'append' => 'Appended text',
]Campo: Area di testo
[
'type' => 'textarea',
'rows' => 5,
'new_lines' => 'wpautop', // 'br' || ''
'default_value' => 'Default value',
]Campo: dispositivo di scorrimento dell’intervallo
[
'type' => 'range',
'min' => 0,
'max' => 100,
'step' => 1,
'default_value' => 50,
'prepend' => 'Prepend text',
'append' => 'Appended text',
]Campo: Password
Come per l’immissione di testo, tranne per il fatto che tutto ciò che digiti sarà coperto da * come ti aspetteresti in un campo password.
[
'type' => 'password',
'prepend' => 'Prepend text',
'append' => 'Appended text',
]Campo: immagine
Seleziona immagine singola.
[
'type' => 'image',
'return_format' => 'array', // 'id' || 'url'
'preview_size' => 'thumbnail',
]Campo: File
Simile all’immagine sopra, tranne per il fatto che non visualizza in anteprima il file.
[
'type' => 'file',
'return_format' => 'array', // 'id' || 'url'
]Puoi anche fornirlo 'mime_types' => '',e impostarlo, ad esempio, 'pdf,docx'per consentire solo file PDF e DOCX.
Campo: Editor WYSIWYG
WYSIWYG è un editor di "What You See Is What You Get", quello che conoscevamo prima dell’arrivo di Gutenberg (TinyMCE).
[
'type' => 'wysiwyg',
'tabs' => 'all', // 'visual' || 'text'
'toolbar' => 'full', // 'basic'
'media_upload' => 1,
'delay' => 0,
]Il parametro 'media_upload'e 'delay'può essere 1 (vero) o 0 (falso).
Campo: Seleziona
[
'type' => 'select',
'allow_null' => 1,
'multiple' => 0,
'ui' => 1,
'return_format' => 'value', // 'array' || 'label'
'choices' => [
'red' => __('Red color', 'txtdomain'),
'blue' => __('Blue color', 'txtdomain')
],
'default_value' => 'red',
]Campo: casella di controllo
[
'type' => 'checkbox',
'layout' => 'horizontal', // 'vertical'
'toggle' => 0,
'return_format' => 'value', // 'array' || 'label'
'choices' => [
'red' => __('Red color', 'txtdomain'),
'blue' => __('Blue color', 'txtdomain')
],
'default_value' => ['red'],
'allow_custom' => 1,
'save_custom' => 0,
]Nota che 'default_value'può essere una matrice di scelte multiple.
Campo: pulsante di opzione
[
'type' => 'radio',
'layout' => 'horizontal', // 'vertical'
'allow_null' => 0,
'return_format' => 'value', // 'array' || 'label'
'choices' => [
'red' => __('Red color', 'txtdomain'),
'blue' => __('Blue color', 'txtdomain')
],
'default_value' => 'red',
'other_choice' => 1,
'save_other_choice' => 0,
]L’impostazione 'other_choice'su true aggiunge un pulsante di opzione aggiuntivo denominato "Altro" con un input di testo in cui l’utente può digitare qualcosa.
Campo: Vero/Falso (commuta)
[
'type' => 'true_false',
'message' => __('Text after toggler', 'txtdomain'),
'default_value' => 1,
'ui' => 1,
'ui_on_text' => __('Yes', 'txtdomain'),
'ui_off_text' => __('No', 'txtdomain'),
]Il 'ui_on_text'e 'ui_off_text'è valido solo se 'ui'è 1, poiché stanno definendo ciò che dovrebbe apparire sullo speciale commutatore dell’interfaccia utente.
Campo: collegamento
Ti dà un pulsante per inserire un collegamento, digitando o scegliendo dal contenuto del tuo sito WordPress (dovrebbe essere familiare aggiungendo un collegamento nel normale editor di WordPress).
[
'type' => 'link',
'return_format' => 'url', // 'array'
]Campo: Posta oggetto
Fornisce una casella di selezione in cui è possibile scegliere tra i contenuti di WordPress. La selezione ti consente di cercare digitando e tutto il contenuto è diviso per tipo di post. Puoi consentire la scelta di più post o solo di uno.
[
'type' => 'post_object',
'allow_null' => 1,
'multiple' => 0,
'return_format' => 'object', // 'id'
'post_type' => '', // or array of post types e.g. ['post', 'page']
'taxonomy' => '', // or array of terms e.g. ['category:term-slug']
]Campo: Relazione
[
'type' => 'relationship',
'return_format' => 'object', // 'id'
'post_type' => '', // or array of post types e.g. ['post', 'page']
'taxonomy' => '', // or array of terms e.g. ['category:term-slug']
'elements' => ['featured_image'], // or ''
'filters' => ['search', 'post_type', 'taxonomy'],
]Campo: scegli i termini in una tassonomia
Il selettore dei termini della tassonomia ha quattro diverse "modalità" o tipi in cui due di esse consentono scelte multiple.
[
'type' => 'taxonomy',
'return_format' => 'object', // 'id'
'taxonomy' => 'category',
'field_type' => 'select', // 'checkbox' || 'radio' || 'multi_select'
'add_term' => 0,
'save_terms' => 0,
]Campo: Seleziona utente
[
'type' => 'user',
'return_format' => 'array', // 'object' || 'id
'role' => '', // or array of roles, e.g. ['author']
'allow_null' => 1,
'multiple' => 0,
]Campo: Google Maps
[
'type' => 'google_map',
'center_lat' => '59.917',
'center_lng' => '10.727',
'zoom' => 14,
'height' => 350,
]Tieni presente che devi fornire una chiave API di GoogleMaps valida ad ACF affinché questo campo funzioni, in questo modo:
add_filter('acf/fields/google_map/api', function($api) {
$api['key'] = 'YOURAPIKEY';
return $api;
});Campo: Selettore data
[
'type' => 'date_picker',
'display_format' => 'd/m/Y',
'return_format' => 'Y-m-d',
'first_day' => 1,
]Campo: selettore data e ora
[
'type' => 'date_time_picker',
'display_format' => 'd/m/Y H:i:s',
'return_format' => 'Y-m-d H:i:s',
'first_day' => 1,
]Campo: Selettore tempo
[
'type' => 'time_picker',
'display_format' => 'H:i',
'return_format' => H:i',
]Campo: Selettore colore
[
'type' => 'color_picker',
'default_value' => '', // or any hex code, e.g. '#FFFFFF'
]Campo: Galleria (solo ACF Pro)
[
'type' => 'gallery',
'return_format' => 'array', // 'id' || 'url'
'preview_size' => 'thumbnail',
'insert' => 'append', // 'prepend'
]Tipi speciali di campi
ACF offre anche alcuni tipi di campo che non salvano un valore di per sé, ma sono più per scopi organizzativi. Per tutti questi impostati 'name'su una stringa vuota.
Messaggio HTML
Se hai bisogno di stampare semplicemente del codice HTML senza che in realtà salvi un valore, puoi usare type 'message'.
[
'type' => 'message',
'message' => '<p>Your HTML here</p>',
'new_lines' => 'wpautop',
'esc_html' => 0,
]Ripetitore (solo ACF Pro)
Un ripetitore contiene una serie di campi che possono essere ripetuti.
[
'type' => 'repeater',
'layout' => 'table', // 'block' || 'row'
'button_label' => __('Add new', 'txtdomain'),
'sub_fields' => [],
]L’elemento sub_fieldssi aspetta una matrice di campi, proprio come hai impostato i campi sopra.
Conclusione
Questa non è affatto una guida esauriente in quanto ACF offre una gamma così ampia di opzioni e personalizzazioni. Ma dovrebbe coprire le opzioni più utilizzate e i casi d’uso personalizzati. Personalmente mi ritrovo a riferirmi a questo abbastanza spesso ogni volta che aggiungo campi ACF per i clienti. E anche per le opzioni più strane questa guida è sufficiente per non dover gonfiare i miei file PHP con il codice di esportazione di ACF. Spero che questo sia stato utile anche per te!