L'API delle impostazioni di WordPress, parte 3 Tutto sui menu

A questo punto, abbiamo imparato perché l'API delle impostazioni è importante, abbiamo imparato tutto su sezioni, campi e impostazioni e abbiamo persino impostato un tema Sandbox che stiamo utilizzando per sviluppare funzionalità mentre esploriamo l'API.

In questo articolo, daremo un'occhiata a come possiamo interfacciarci con il sistema di menu di WordPress. È importante notare che questo non è in realtà una parte dell'API Settings, ma è così strettamente correlato che dovremmo familiarizzare con come usarlo.

Poiché i nostri temi e / o plugin diventano più complessi, abbiamo bisogno di conoscere tutti i vari modi in cui possiamo includerli nel Dashboard di WordPress. In questo articolo, daremo un'occhiata alle varie funzioni del menu di WordPress, quando usarle, quando evitarle e le situazioni alle quali ogni funzione si presta meglio.

Comprensione dei tipi di menu

WordPress offre quattro diversi modi per includere i nostri menu. Di seguito, daremo un'occhiata a ciascun menu, i parametri che ciascuno accetta e gli esempi di codice su come utilizzarli durante i progetti. Il nostro obiettivo è quello di sviluppare una chiara comprensione di come funziona l'API in quanto può gettare le basi per il nostro lavoro futuro.

Menu di primo livello

Le pagine di menu si riferiscono alle voci di menu che vedi quando accedi per la prima volta a WordPress. Cioè, sono le opzioni disponibili nel menu di sinistra che possono contenere un elenco di pagine di sottomenu.

Per introdurre la propria pagina di menu nella Dashboard di WordPress, si utilizza la funzione add_menu_page.

Daremo un'occhiata a un esempio pratico in un momento, ma prima esaminiamo la funzione: accetta sette argomenti (cinque richiesti, due facoltativi):

Titolo della pagina si riferisce al testo che appare nella parte superiore della finestra del browser ogni volta che viene visualizzata la pagina del menu di livello superiore.
Titolo del menu è il testo che appare nel menu attuale. È meglio mantenerlo un po 'breve, altrimenti si avvolgerà nella voce di menu e apparirà un po' contro il resto delle voci di menu.
Capacità si riferisce a quali utenti hanno accesso al menu. Questo è semplicemente un valore stringa che rappresenta uno dei ruoli disponibili.
Menu Slug è un identificatore univoco che fornisci. Identifica questo menu nel contesto di WordPress e si riferisce anche alla pagina che visualizza le opzioni associate a questo menu. Fornisce inoltre un hook con cui gli elementi del sottomenu possono registrarsi.
Richiama è la funzione che definisce il contenuto visualizzato nella pagina che corrisponde a questo menu. Questo può essere inline HTML o fare riferimento a un file esterno.
Icona URL è il percorso dell'icona che si desidera visualizzare accanto alla voce di menu nel menu di WordPress. Puoi usare una delle icone esistenti di WordPress o usarne una tua. Questo argomento è facoltativo.
Posizione definisce la posizione in cui questo menu risiederà nell'elenco delle voci di menu di WordPress. Per impostazione predefinita, il menu viene visualizzato nella parte inferiore del menu, ma una posizione personalizzata posiziona il menu sopra (o sotto) qualsiasi voce di menu WordPress esistente.

Diamo un'occhiata a un esempio. Trova functions.php nella sandbox di WordPress Settings e aggiungi le seguenti due funzioni:

function sandbox_create_menu_page ()  add_action ('admin_menu', 'sandbox_create_menu_page'); function sandbox_menu_page_display ()

Tieni presente che stiamo utilizzando il hook admin_menu per registrare la nostra voce di menu. Questa particolare funzione si attiva subito dopo aver posizionato il menu di amministrazione di base, quindi desideri registrare qui il tuo menu in modo che WordPress lo visualizzi mentre visualizzi il resto dei menu.

Quindi, impostiamo la voce di menu di base. In linea con gli articoli precedenti di questa serie, ecco cosa abbiamo intenzione di fare:

Aggiungi un nuovo menu nella parte inferiore del menu WordPress
Gli daremo il nome del nostro tema (cioè "Sandbox")
Sarà disponibile per tutti gli utenti
Non includerà un'icona

Abbastanza facile, giusto? Andiamo avanti e aggiungere il nostro menu. Ancora una volta, non copiare e incollare semplicemente questo codice. Leggi, osserva i commenti e assicurati di comprendere appieno cosa stiamo facendo:

function sandbox_create_menu_page () add_menu_page ('Sandbox Options', // Il titolo da visualizzare sulla pagina corrispondente per questo menu 'Sandbox', // Il testo da visualizzare per questa voce di menu effettiva 'administrator', // Che tipo degli utenti possono vedere questo menu 'sandbox', // L'ID univoco - cioè lo slug - per questa voce di menu 'sandbox_menu_page_display', // Il nome della funzione da chiamare quando si esegue il rendering del menu per questa pagina "); // end sandbox_create_menu_page add_action ('admin_menu', 'sandbox_create_menu_page');

Ora, aggiorna il tuo menu di amministrazione di WordPress e dovresti vedere una nuova voce di menu. Quando fai clic su di esso, dovresti vedere apparire una pagina vuota.

Ovviamente, questo non è molto funzionale. Escludiamo la funzione di callback definita in precedenza per poterla visualizzare qualcosa sullo schermo:

function sandbox_menu_page_display () // Crea un'intestazione nel contenitore "wrap" predefinito di WordPress $ html = ''; $ html. = 'sandbox
'; $ html. = '
'; // Invia il markup al browser echo $ html;  // termina sandbox_menu_page_display

La versione finale del tuo codice dovrebbe apparire in questo modo:

/ ** * Aggiunge un nuovo menu di primo livello nella parte inferiore del menu di amministrazione di WordPress. * / function sandbox_create_menu_page () add_menu_page ('Sandbox Options', // Il titolo da visualizzare sulla pagina corrispondente per questo menu 'Sandbox', // Il testo da visualizzare per questa voce di menu 'amministratore', // Quale tipo di utenti può vedere questo menu 'sandbox', // L'ID univoco - cioè lo slug - per questa voce di menu 'sandbox_menu_page_display', // Il nome della funzione da chiamare quando si esegue il rendering del menu per questa pagina ") ; // fine sandbox_create_menu_page add_action ('admin_menu', 'sandbox_create_menu_page'); / ** * Rende la visualizzazione di base della pagina del menu per il tema. * / function sandbox_menu_page_display () // Crea un'intestazione nel WordPress predefinito ' avvolgere 'contenitore $ html =''; $ html. = 'sandbox
'; $ html. = '
'; // Invia il markup al browser echo $ html;  // termina sandbox_menu_page_display

Oltre a utilizzare effettivamente la funzione add_menu_page, forse la cosa più delicata è che, in WordPress, ogni voce di menu ha una pagina menu corrispondente. Daremo un'occhiata a questo in modo più approfondito in tutta la serie, ma è importante notare ora mentre iniziamo ad esplorare ciascuno dei vari tipi di menu.

Anche se questo è in gran parte incompleto, lo aggiungeremo a tutto il resto di questo articolo e al resto del tutorial.

Una nota sul posizionamento: Molti sviluppatori considerano l'utilizzo dell'argomento position come una cattiva etichetta, poiché mescola l'esperienza utente predefinita con WordPress. Inoltre, se si definisce una posizione e un altro tema, plugin o funzione utilizza la stessa posizione, una delle voci di menu può essere sovrascritta.

sottomenu

I sottomenu sono come i menu con l'eccezione che appartengono a un altro menu: hanno un genitore. Quindi, ovviamente, non è possibile creare un sottomenu senza prima creare una voce di menu. Naturalmente, come abbiamo visto nell'ultimo articolo, gli elementi di sottomenu possono essere introdotti a voci di menu esistenti, non solo voci di menu personalizzate.

In questo articolo, introdurremo una pagina di sottomenu nella nostra voce di menu personalizzata. Ma prima di farlo, diamo un'occhiata alla funzione add_submenu_page e ai parametri che accetta:

Slug genitore si riferisce all'ID della voce di menu principale a cui questo sottomenu apparterrà. Nel nostro caso, useremo la lumaca del menu che abbiamo definito sopra.
Titolo della pagina è il testo che verrà visualizzato nel titolo del browser quando viene visualizzata la pagina.
Titolo del menu è il testo che verrà visualizzato come voce di menu effettiva nel menu di WordPress.
Capacità, come con il menu genitore, si riferisce a quali tipi di utenti hanno accesso a questo particolare menu.
Menu Slug è l'identificatore univoco per questa voce di menu. È ciò che viene utilizzato per definire questo particolare menu nel contesto di WordPress.
Richiama è la funzione che viene utilizzata per rendere la pagina di questo menu sullo schermo.

Se si desidera aggiungere una voce di menu a uno dei menu esistenti, fare riferimento alla tabella dell'articolo precedente.

Iniziamo registrando un sottomenu per il menu esistente sopra. Vogliamo fare quanto segue:

Registra un sottomenu da aggiungere al menu che abbiamo appena creato
Mostrerà il testo 'Opzioni'
Sarà disponibile per tutti gli utenti
Non includerà un'icona

Controlla il seguente codice: lo aggiungeremo direttamente sotto la nostra chiamata a add_menu_page:

add_submenu_page ('sandbox', // Registra questo sottomenu con il menu definito sopra 'Opzioni Sandbox', // Il testo sul display nel browser quando questa voce di menu è attiva 'Opzioni', // Il testo per questa voce di menu ' amministratore ', // Quale tipo di utente può vedere questo menu' sandbox_options ', // L'ID univoco - lo slug - per questa voce di menu' sandbox_options_display '// La funzione utilizzata per visualizzare il menu di questa pagina sullo schermo);

Non dimenticare di definire il callback, anche se è vuoto. Cioè, non dimenticare di aggiungere questa funzione al tuo file (aggiungeremo di più per un momento):

function sandbox_options_display ()  // end sandbox_options_display

Quando aggiorni il tuo browser, dovresti vedere ora Due sottomenu direttamente sotto il menu "Sandbox". Si noti che WordPress crea un elemento di sottomenu da solo - è una voce di sottomenu che corrisponde alla voce di menu e la funzione di callback definita. Il secondo è la nuova opzione di sottomenu che abbiamo appena definito, anche se non rende alcun contenuto.

Per risolvere il problema, andiamo avanti e introduciamo una pagina di base. Aggiorna la funzione di richiamata del sottomenu per assomigliare a questa:

function sandbox_options_display () // Crea un'intestazione nel contenitore "wrap" predefinito di WordPress $ html = ''; $ html. = 'Opzioni sandbox
'; $ html. = '
'; // Invia il markup al browser echo $ html;  // termina sandbox_options_display

Aggiorna di nuovo il browser e dovresti visualizzare un titolo di pagina di base quando selezioni il nuovo Opzioni voce del sottomenu.

Sebbene ciò non sia necessario, si noti che è possibile avere effettivamente la voce di menu principale e il Opzioni la voce di menu si riferisce allo stesso contenuto - è sufficiente aggiornare la funzione di richiamata nella funzione ad_menu_page al sandbox_options_display funzione che abbiamo appena definito.

Pagine plugin

Se stai sviluppando un plug-in per WordPress, ci sono diversi modi in cui il tuo prodotto può interfacciarsi con la piattaforma.

In particolare, il tuo plugin ...

Può funzionare in background e non richiedere un menu.
Può utilizzare entrambe o una delle funzioni sopra menzionate per creare un menu personalizzato
Può includere se stesso in uno dei menu WordPress esistenti

Per semplificare agli sviluppatori di plug-in di includere le loro opzioni nei menu WordPress esistenti, l'API di WordPress offre la seguente funzione: add_plugins_page.

Ma aspetta. Se hai seguito gli esempi di cui sopra, probabilmente avrai notato che non sembra esserci alcuna differenza visibile tra add_plugins_page e add_submenu_page. Hai ragione. add_plugins_page offre la stessa funzionalità di add_submenu_page, ma ci sono due differenze principali:

Il plugin è fornito specificamente per l'utilizzo nello sviluppo di plugin.
La funzione aggiunge l'opzione del menu plugin direttamente a WordPress ' plugin menu.

Sebbene tu possa certamente usare add_submenu_page per raggiungere lo stesso obiettivo, sono sempre un fan dell'uso di funzioni intese per uno specifico caso d'uso anche se esiste un'altra funzione API che fa lo stesso. Quando lo fai, stai dimostrando che stai utilizzando l'API come previsto dagli sviluppatori e stai rendendo il tuo codice un po 'più coeso in quanto la tua base di codice è più strettamente allineata con il modo in cui interagisce con la piattaforma principale.

Lo sviluppo di plugin non rientra nell'ambito di questa serie particolare, ma non è del tutto irrilevante. Sebbene non vengano apportate modifiche al nostro tema Sandbox, desidero fornire un semplice esempio che mostri come utilizzare questa particolare funzione.

Innanzitutto, esaminiamo gli argomenti che add_plugins_page accetta:

Titolo della pagina è il testo che verrà visualizzato nel titolo del browser quando viene visualizzata la pagina delle opzioni del plug-in.
Titolo del menu è il testo che apparirà come voce di menu del plugin nel menu di WordPress.
Capacità come con il menu genitore, si riferisce a quali tipi di utenti hanno accesso a questo particolare menu.
Menu Slug è l'identificatore univoco per questa voce di menu. È quello che usava per definire questo particolare menu nel contesto di WordPress.
Richiama è la funzione che viene utilizzata per rendere la pagina di questo menu sullo schermo.

Ecco un semplice esempio che dimostra esattamente come usarlo. Nota che puoi includerlo nel tuo file functions.php, ma lo è non parte del tema Sandbox su cui stiamo lavorando e dovrebbe invece essere usato nel contesto di un plugin.

Per prima cosa, configura la chiamata alla funzione API - nota che questo utilizza l'hook admin_menu:

function sandbox_example_plugin_menu () add_plugins_page ('Sandbox Plugin', // Il titolo da visualizzare nella finestra del browser per questa pagina. 'Sandbox Plugin', // Il testo da visualizzare per questa voce di menu 'administrator', // Which il tipo di utenti può vedere questa voce di menu 'sandbox_plugin_options', // L'ID univoco - ovvero lo slug - per questa voce di menu 'sandbox_plugin_display' // Il nome della funzione da chiamare quando si esegue il rendering della pagina per questo menu);  // fine sandbox_example_plugin_menu add_action ('admin_menu', 'sandbox_example_plugin_menu');

Quindi, imposta la funzione che renderizza la visualizzazione del plugin:

function sandbox_plugin_display () // Crea un'intestazione nel contenitore "wrap" predefinito di WordPress $ html = ''; $ html. = 'Opzioni del plugin Sandbox
'; $ html. = 'Al momento non ci sono opzioni. Questo è solo per scopi dimostrativi.
'; $ html. = '
'; // Invia il markup al browser echo $ html;  // termina sandbox_plugin_display

Aggiorna il tuo WordPress Dashboard, passa con il mouse sopra il plugin menu e dovresti notare una nuova voce di menu. Non male, eh?

La versione finale del codice dovrebbe apparire così:

/ ** * Questa funzione introduce un'opzione di menu a tema singolo nel menu 'Plugin' di WordPress *. * / function sandbox_example_plugin_menu () add_plugins_page ('Sandbox Plugin', // Il titolo da visualizzare nella finestra del browser per questa pagina. 'Sandbox Plugin', // Il testo da visualizzare per questa voce di menu 'administrator', / / Quale tipo di utenti può vedere questa voce di menu 'sandbox_plugin_options', // L'ID univoco - cioè lo slug - per questa voce di menu 'sandbox_plugin_display' // Il nome della funzione da chiamare quando si esegue il rendering della pagina per questo menu) ;  // fine sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_plugin_menu'); / ** * Esegue il rendering di una pagina semplice da visualizzare per il menu dei temi definito sopra. * / function sandbox_plugin_display () // Crea un'intestazione nel contenitore "wrap" predefinito di WordPress $ html = ''; $ html. = 'Opzioni del plugin Sandbox
'; $ html. = 'Al momento non ci sono opzioni. Questo è solo per scopi dimostrativi.
'; $ html. = '
'; // Invia il markup al browser echo $ html;  // termina sandbox_plugin_display

Ancora una volta, questa funzione non farà parte del nostro tema Sandbox perché è orientata più verso lo sviluppo di plugin; tuttavia, vale la pena coprire per quelli di voi che sfrutteranno l'API Settings nello sforzo di sviluppo del plugin.

Pagine tematiche

Proprio come con i plugin, WordPress fornisce una funzione API per l'introduzione di menu specifici per temi. È molto simile alla funzione del menu plugin in quanto fornisce un altro modo per introdurre un sottomenu nei menu esistenti. La differenza principale è che il sottomenu è aggiunto al Aspetto menu.

Come nell'esempio di plug-in riportato in precedenza in questo articolo, daremo un'occhiata a come possiamo utilizzare questa funzione, ma non la includeremo nel nostro tema Sandbox. Questo è inteso semplicemente per dimostrare come utilizzare la funzione nel caso in cui si opta per seguire questa strada nel proprio lavoro personale.

Innanzitutto, esamineremo gli argomenti che add_theme_page accetta. Noterai che sono proprio come quelli richiesti per il menu del plugin e molto simili alle funzioni del sottomenu che abbiamo delineato in precedenza:

add_theme_page accetta i seguenti argomenti:

Titolo della pagina è il testo che verrà visualizzato nel titolo del browser quando viene visualizzata la pagina delle opzioni del tema.
Titolo del menu è il testo che apparirà come voce di menu del tema nel menu di WordPress.
Capacità come con il menu genitore, si riferisce a quali tipi di utenti hanno accesso a questo particolare menu.
Menu Slug è l'identificatore univoco per questa voce di menu. È quello che usava per definire questo particolare menu nel contesto di WordPress.
Richiama è la funzione che viene utilizzata per rendere la pagina di questo menu sullo schermo.

Come con le altre funzioni, creeremo un paio di funzioni di esempio che mostrano come includere questo nel tuo progetto. Si noti che la chiamata a add_theme_page può essere aggiunta a functions.php e, a differenza delle chiamate a add_plugin_page, dovrebbero risieda qui quando sviluppi il tuo tema.

Innanzitutto, la chiamata per impostare la voce di menu:

function sandbox_example_theme_menu () add_theme_page ('Sandbox Theme', // Il titolo da visualizzare nella finestra del browser per questa pagina. 'Sandbox Theme', // Il testo da visualizzare per questa voce di menu 'administrator', // Which il tipo di utenti può vedere questa voce di menu 'sandbox_theme_options', // L'ID univoco - ovvero lo slug - per questa voce di menu 'sandbox_theme_display' // Il nome della funzione da chiamare quando si esegue il rendering della pagina per questo menu);  // fine sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu');

Successivamente, configureremo una funzione per il rendering della pagina delle opzioni:

function sandbox_theme_display () // Crea un'intestazione nel contenitore "wrap" predefinito di WordPress $ html = ''; $ html. = 'Opzioni del tema Sandbox
'; $ html. = 'Al momento non ci sono opzioni. Questo è solo per scopi dimostrativi.
'; $ html. = '
'; // Invia il markup al browser echo $ html;  // termina sandbox_theme_display

Ora aggiorna il WordPress Dashboard, passa con il mouse sopra il Aspetto menu e dovresti vedere la tua nuova voce di menu. Semplice!

La versione finale del codice dovrebbe apparire così:

/ ** * Questa funzione introduce un'opzione di menu a tema singolo nel menu 'Aspetto' di WordPress *. * / function sandbox_example_theme_menu () add_theme_page ('Sandbox Theme', // Il titolo da visualizzare nella finestra del browser per questa pagina. 'Sandbox Theme', // Il testo da visualizzare per questa voce di menu 'administrator', / / Quale tipo di utenti può vedere questa voce di menu 'sandbox_theme_options', // L'ID univoco - ovvero lo slug - per questa voce di menu 'sandbox_theme_display' // Il nome della funzione da chiamare quando si esegue il rendering della pagina per questo menu) ;  // fine sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu'); / ** * Esegue il rendering di una pagina semplice da visualizzare per il menu dei temi definito sopra. * / function sandbox_theme_display () // Crea un'intestazione nel contenitore "wrap" predefinito di WordPress $ html = ''; $ html. = 'Opzioni del tema Sandbox
'; $ html. = 'Al momento non ci sono opzioni. Questo è solo per scopi dimostrativi.
'; $ html. = '
'; // Invia il markup al browser echo $ html;  // termina sandbox_theme_display

Per quelli di voi che sono interessati allo sviluppo di temi più avanzati, probabilmente avete considerato i vari modi di implementare più pagine di opzioni per il tema.

Da una parte, possiamo aggiungere più sottomenu a un menu di livello superiore, ma lì è un'alternativa: navigazione a schede. Questo si presta bene quando vuoi introdurre opzioni per il Aspetto menu e non aggiungere ancora un'altra voce di menu alla Dashboard di WordPress. Discuteremo di questo in modo più approfondito nel prossimo articolo.

Quando utilizzare ciascuna funzione

Abbiamo esaminato ciascuno dei quattro modi principali per introdurre le nostre pagine di opzioni in WordPress. Sebbene queste funzioni non facciano specificamente parte dell'API Settings, è importante discuterne perché lavorano così strettamente in congiunzione con esso.

Ma conoscere queste funzioni è solo la metà. Come sviluppatore responsabile per l'integrazione e l'organizzazione delle impostazioni, è importante sapere quando utilizzare ciascuna delle varie funzioni nel loro contesto appropriato.

Sebbene non ci sia una risposta in argento per quando utilizzare ciascuna funzione, ecco alcune linee guida da considerare quando si lavora su funzioni, plug-in e / o temi personalizzati:

Menu di primo livello può essere aggiunto quando c'è un sottomenu che può essere logicamente raggruppato con queste opzioni. Questo si presta a quando hai una collezione importante di impostazioni che non si adattano logicamente a nessuno dei menu WordPress esistenti.
sottomenu appartiene sempre a un menu di livello superiore, personalizzato o preesistente. Dovrebbero essere sempre raggruppati nel menu di primo livello più logico. Se WordPress offre un menu che può fungere da genitore per il tuo sottomenù, allora usalo; non inquinare il menu con un menu di livello superiore ridondante.
Menu Plugin dovrebbe essere usato quando si dispone di semplici opzioni di una sola pagina per il proprio plugin. Se disponi di più pagine di opzioni, valuta la possibilità di creare un menu di livello superiore o di utilizzare la navigazione a schede che esploreremo nel prossimo articolo.
Menu tematici dovrebbe essere utilizzato quando si sviluppa il proprio tema che offre il proprio set di opzioni personalizzate. Se le opzioni possono vivere su una singola pagina, prendi in considerazione l'utilizzo della funzione API di WordPress. Se hai più opzioni, considera l'utilizzo della navigazione a schede. Nota che molti sviluppatori di temi elevano spesso le loro opzioni di tema al menu di livello superiore e va bene lo stesso.

Una parola sui menu personalizzati: Sebbene WordPress ci dia la possibilità di aggiungere i nostri menu di livello superiore, aggiungere a qualsiasi menu esistente e generalmente ci dà la possibilità di fare ciò che vogliamo con la configurazione predefinita, una parte della comunità aggrotta le sopracciglia su questo. Ritengono che la funzionalità personalizzata non dovrebbe interferire con alcuni menu principali. Anche se in definitiva dipende da te, implementa il tuo lavoro con discernimento - le probabilità sono, poche cose che stai facendo sono più importanti della funzionalità principale di WordPress, quindi non mettere il tuo lavoro al di sopra di quello.

Che succede Avanti?

Nel prossimo articolo, applicheremo un po 'di ciò che abbiamo imparato sui menu e inizieremo a introdurre le pagine delle opzioni per il nostro tema Sandbox.

Oltre ad aggiungere pagine di menu, daremo anche un'occhiata alla navigazione a schede e a come possiamo implementarla per funzionare insieme alle nostre pagine di menu.

Nel frattempo, esamina i precedenti articoli di questa serie e non dimenticare di eseguire il checkout della versione corrente di Sandbox delle impostazioni di WordPress su GitHub.

Risorse correlate

Abbiamo coperto un bel po 'di risorse in questo articolo. Ecco un riassunto di tutto ciò che abbiamo usato:

add_menu_page
add_submenu_page
add_plugins_page
add_theme_page
Impostazioni WordPress Sandbox

Codice