L'API delle impostazioni di WordPress, parte 6 pagine dei menu

Nella parte 3 di questa serie, abbiamo esaminato le varie funzioni di menu fornite dall'API di WordPress. Se hai seguito, allora sai che abbiamo già impostato una pagina delle impostazioni per il nostro tema usando il add_theme_page funzione. Sebbene l'introduzione di menu e sottomenu non facciano esplicitamente parte dell'API Impostazioni, svolgono un ruolo nella creazione di funzionalità, plug-in e / o temi personalizzati.

In questo articolo, introdurremo un nuovo menu per la dashboard di WordPress che renderà le nostre opzioni di tema disponibili altrove oltre alle opzioni "Aspetto".

Prima di iniziare: Questo articolo presume che tu abbia familiarità con l'API Impostazioni e le opzioni del tema. Se sei uno sviluppatore principiante o addirittura intermedio di WordPress, ti raccomando caldamente di riprendere il resto della serie prima di immergerti in questo post.

Uno sguardo all'API

Poiché abbiamo già esaminato ognuna delle funzioni del menu, non è necessario rieseguire tutte le funzioni disponibili in WordPress. Invece, daremo un'occhiata a quelli che useremo e quindi lavoreremo attraverso un esempio pratico di come usarli nel nostro lavoro.

Prima di esaminare ciascuna funzione, vediamo in dettaglio cosa intendiamo realizzare nella prossima fase di questa serie:

Introduci un menu di primo livello per le nostre opzioni tematiche
Aggiungi una voce di sottomenu che si collegherà alla scheda "Opzioni di visualizzazione"
Aggiungi un elemento di sottomenu che si collegherà alla scheda "Opzioni sociali"

Relativamente semplice, giusto? Per fare ciò, trarremo vantaggio dalle seguenti due funzioni:

add_menu_page che viene utilizzato per introdurre voci di menu di livello superiore
add_submenu_page che viene utilizzato per introdurre voci di sottomenu nei menu di livello superiore.

Daremo un'occhiata ai parametri e all'utilizzo di ogni funzione mentre li implementiamo nel nostro tema.

Nota che il resto di questo articolo si basa su questa versione della sandbox delle impostazioni di WordPress. Se stai seguendo il repository, assicurati di verificarlo.

Il menu di primo livello

La prima cosa che vogliamo fare è introdurre un menu di primo livello. Questo menu apparirà direttamente sotto il menu "Impostazioni" nella dashboard di WordPress e avrà due scopi. Il menu dovrebbe:

Esporre le opzioni del tema al dashboard di WordPress
Mostra una pagina di opzioni predefinita per le opzioni del tema

La funzione accetta i seguenti sette argomenti, i primi cinque sono obbligatori, gli ultimi due non sono:

titolo della pagina è il testo che verrà visualizzato nella barra del titolo del browser
menu_title è il testo che verrà visualizzato per la voce di menu
capacità si riferisce al ruolo che l'utente deve avere per accedere a questo menu
menu_slug è un valore univoco che identifica questo menu. È anche il modo in cui i sottomenu si registrano con questo menu.
function_name viene chiamato quando si fa clic sul menu per visualizzare la pagina delle opzioni.
icon_url è il percorso dell'icona che si desidera visualizzare accanto alla voce di menu.
posizione è dove il menu dovrebbe essere aggiunto in relazione agli altri menu nel dashboard di WordPress.

Nel nostro lavoro, ci concentreremo solo sui primi cinque parametri. Discuto il posizionamento del menu nella conclusione di questo articolo.

Per iniziare, avremo bisogno di presentare una chiamata al add_menu_page funzione. Secondo il codice WordPress, i menu di amministrazione possono essere aggiunti utilizzando il admin_menu gancio. In precedenza in questa serie, abbiamo scritto una funzione che aggiunge le opzioni del tema al menu "Aspetto". Nello specifico, abbiamo scritto sandbox_example_theme_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 - cioè lo slug - per questa voce di menu 'sandbox_theme_display' // Il nome della funzione da chiamare quando si esegue il rendering della pagina di questo menu);  // fine sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu');

Nota nel codice sopra che questa funzione è stata registrata con admin_menu gancio, pure. Dovresti sempre cercare di mantenere le tue funzioni logicamente coerenti. Dato che abbiamo già una funzione che registra un menu, che è registrato con l'hook appropriato, e poiché stiamo introducendo funzionalità simili, aggiungeremo le nostre nuove funzioni di menu a questa funzione.

Aggiungi la seguente chiamata a add_menu_page direttamente sotto la chiamata sopra:

add_menu_page ('Sandbox Theme', // Il valore utilizzato per popolare la barra del titolo del browser quando la pagina del menu è attiva 'Sandbox Theme', // Il testo del menu nella barra laterale dell'amministratore 'administrator', // Quali ruoli sono in grado per accedere al menu 'sandbox_theme_menu', // L'ID usato per associare gli elementi del sottomenu a questo menu 'sandbox_theme_display' // La funzione di callback usata per rendere questo menu);

Come puoi vedere, stiamo registrando un menu che visualizzerà "Tema Sandbox" sia nella barra del titolo del browser sia nella voce di menu. Stiamo esponendo il menu solo agli amministratori e abbiamo dato al menu l'ID univoco di "sandbox_theme_parent_menu". Riutilizzeremo questo parametro nella prossima sezione.

C'è una cosa importante che dobbiamo chiarire: si noti che abbiamo superato "sandbox_theme_display'come la funzione da chiamare quando si fa clic su questa voce di menu. Ricordiamo che nella parte 3 abbiamo introdotto questa funzione (e l'abbiamo perfezionata nella parte 5). In particolare, è responsabile del rendering della pagina delle opzioni del tema a schede.

Passando questo nome di funzione esistente al add_menu_page funzione, stiamo sfruttando il codice che abbiamo già scritto e stiamo rendendo una pagina di opzioni predefinita per la voce di menu.

A questo punto, siamo pronti per iniziare ad aggiungere sottomenu ma prima di andare avanti, assicurati che la tua funzione assomigli esattamente a questa:

function sandbox_example_theme_menu () add_theme_page ('Sandbox Theme', 'Sandbox Theme', 'administrator', 'sandbox_theme_options', 'sandbox_theme_display'); add_menu_page ('Sandbox Theme', 'Sandbox Theme', 'administrator', 'sandbox_theme_menu', 'sandbox_theme_display');  // termina sandbox_example_theme_menu

Aggiungi i sottomenu

I sottomenu sono molto simili ai menu tranne che "appartengono" a un menu esistente. Anche l'API per la registrazione dei sottomenu è relativamente simile. La funzione accetta sei argomenti, i primi cinque sono obbligatori, l'ultimo è facoltativo:

parent_slug si riferisce all'ID univoco della voce di menu principale. Nel nostro caso, "sandbox_theme_menu".
titolo della pagina è il testo da rendere nella barra degli strumenti del browser quando questa voce di sottomenu è attiva
menu_title è il testo di questo effettivo sottomenu nella dashboard
capacità è il ruolo che un utente deve avere per accedere a questa voce di menu
menu_slug è l'ID univoco per questa particolare voce di menu
function_name viene chiamato quando si fa clic sul menu per visualizzare la pagina delle opzioni

La funzione è semplice. Abbiamo due voci di menu da introdurre: una per "Opzioni di visualizzazione" e una per "Opzioni sociali".

Opzioni di visualizzazione

Innanzitutto, introduciamo un elemento di sottomenu per le opzioni di visualizzazione. Aggiungi il seguente blocco di codice direttamente sotto add_menu_page chiama ciò che abbiamo definito sopra:

add_submenu_page ('sandbox_theme_menu', // L'ID della pagina del menu di livello superiore a cui questo elemento del sottomenu appartiene 'Opzioni di visualizzazione', // Il valore utilizzato per popolare la barra del titolo del browser quando la pagina del menu è attiva 'Opzioni di visualizzazione', // L'etichetta di questa voce di sottomenu viene visualizzata nel menu 'administrator', // Quali ruoli sono in grado di accedere a questo elemento di sottomenu 'sandbox_theme_display_options', // L'ID utilizzato per rappresentare questo elemento di sottomenu 'sandbox_theme_display' // La funzione di callback utilizzata per visualizzare le opzioni per questo elemento di sottomenu);

Ciascuno dei parametri precedenti dovrebbe essere chiaro ad eccezione del nome della funzione che abbiamo passato come argomento finale. Si noti che è lo stesso nome di funzione che abbiamo fornito nel add_menu_page chiamata. Ma questo ha senso, giusto? Dopo tutto, la "Opzioni di visualizzazione" è la scheda predefinita che viene visualizzata quando vengono selezionate le opzioni del tema, quindi avrebbe senso che fosse visualizzato quando il menu di primo livello è selezionato e quando è selezionata la voce di menu "Opzioni di visualizzazione".

A questo punto, c'è una caratteristica importante di WordPress da evidenziare: si noti che una volta aggiunto il primo elemento del sottomenu, WordPress renderà effettivamente due voci di sottomenu al menu di primo livello - una voce che duplica la funzione del livello principale menu e una voce corrispondente all'elemento del sottomenu appena definito. Ne parlo perché, nella mia esperienza, ho visto gli sviluppatori confondersi su come (e perché) questo accade. In breve, WordPress sta facendo questo: non c'è niente di sbagliato nel tuo codice.

Opzioni sociali

Aggiungere una voce di menu per le opzioni social è quasi esattamente come aggiungere una voce di menu per le opzioni di visualizzazione. Ovviamente, vogliamo solo modificare i valori per la barra del titolo, la voce di menu e la pagina che viene visualizzata ogni volta che viene selezionato il menu. Per prima cosa, impostiamo la nostra chiamata al add_submenu_page funzione. Dovrebbe sembrare come questo:

add_submenu_page ('sandbox_theme', 'Opzioni sociali', 'Opzioni sociali', 'amministratore', 'sandbox_theme_social_options', 'sandbox_theme_display');

Salva il tuo codice, aggiorna la tua dashboard e dovresti vedere la voce di menu "Opzioni sociali" ora disponibile nel menu "Tema Sandbox"; tuttavia, si noti che facendo clic sulla nuova voce di sottomenu viene visualizzata solo la "Opzioni di visualizzazione". Dal momento che abbiamo superato il "sandbox_theme_display"come il nome della funzione, è quello che dovremmo aspettarci, giusto? Quindi ora ci troviamo di fronte a una piccola sfida: come selezioniamo la scheda" Opzioni sociali "quando clicchi sulla voce del sottomenu?

Refactoring Our Tab Funzionalità

Ci sono un paio di diverse opzioni che abbiamo per legare il nuovo elemento del sottomenu alla scheda corretta sulla pagina delle opzioni del tema:

Possiamo definire una nuova funzione che rende disponibili le opzioni sociali. Ciò richiederebbe un ulteriore lavoro per introdurre una nuova funzione, impostando la funzionalità di tabulazione in modo da non interrompere l'esperienza della pagina esistente e duplicare un po 'di codice.
Possiamo refactoring l'esistente sandbox_theme_display funzione per accettare un parametro opzionale e quindi utilizzare una funzione anonima in add_submenu_page chiamare per passare un parametro ad esso.

In definitiva, una di queste opzioni dipende da te; tuttavia, preferirei rifattare la mia funzione esistente piuttosto che duplicare il codice, quindi è quello che farò nel resto dell'articolo.

Per prima cosa, iniziamo a rifare il nostro sandbox_theme_display funzione. Facciamolo accettare un argomento opzionale che verrà usato per indicare quale scheda vogliamo selezionare. Individua la seguente firma nel tuo functions.php file:

function sandbox_theme_display () / * Consolidato per questa parte dell'articolo. * / // end sandbox_theme_display

Aggiorna la firma in modo che accetti un singolo argomento e la imposta su null quando non è definita:

function sandbox_theme_display ($ active_tab = null) / * Consolidato per questa parte dell'articolo. * / // end sandbox_theme_display

Se non conosci PHP, puoi leggere gli argomenti predefiniti in questa pagina.

Ricorda dall'ultimo articolo che la nostra funzione di visualizzazione sta effettivamente cercando un valore di stringa di query da impostare. Vogliamo ancora mantenere tale funzionalità, ma dobbiamo tenere conto del fatto che il parametro può essere passato anche alla funzione. Per eseguire questo refactoring, innanzitutto individuare la seguente riga di codice nel file sandbox_theme_display funzione:

$ active_tab = isset ($ _GET ['tab'])? $ _GET ['tab']: 'display_options';

Si noti che questa particolare riga di codice riguarda solo i parametri della stringa di query. Per tenere conto del nuovo parametro opzionale, dobbiamo introdurre la logica che prima controlla se il parametro della stringa di query è spuntato, altrimenti, controllerà se l'argomento della funzione è impostato per visualizzare le opzioni social e, in caso contrario, allora imposterà automaticamente le opzioni di visualizzazione. Sostituisci la riga di codice sopra con le seguenti condizioni:

if (isset ($ _GET ['tab'])) $ active_tab = $ _GET ['tab'];  else if ($ active_tab == 'social_options') $ active_tab = 'social_options';  else $ active_tab = 'display_options';  // end if / else

La versione finale della funzione dovrebbe assomigliare a questa:

function sandbox_theme_display ($ active_tab = ") ?>

Opzioni del tema Sandbox

"> Opzioni di visualizzazione"> Opzioni sociali

Non abbiamo ancora finito. Anche se abbiamo svolto il lavoro necessario per visualizzare le opzioni social se è stato passato il parametro corretto, non abbiamo effettivamente chiamato la funzione utilizzando un parametro. Per fare questo, abbiamo bisogno di refactoring il add_submenu_page funzione dall'alto. Attualmente, la chiamata alla funzione ha il seguente aspetto:

add_submenu_page ('sandbox_theme', 'Opzioni sociali', 'Opzioni sociali', 'amministratore', 'sandbox_theme_social_options', 'sandbox_theme_display');

Dobbiamo aggiornare il parametro finale in modo che chiami la funzione di visualizzazione e trasmetta il valore corretto per il rendering delle opzioni social. Per farlo, creeremo una funzione anonima:

add_submenu_page ('sandbox_theme_menu', 'Opzioni sociali', 'Opzioni sociali', 'amministratore', 'sandbox_theme_social_options', create_function (null, 'sandbox_theme_display ("social_options");'));

Se sei nuovo in PHP, assicurati di leggere il create_function funzionalità e funzioni anonime. Sebbene siano al di fuori degli scopi di questo articolo, possono essere potenti (e utili!) Se usati nel contesto appropriato.

La versione finale di sandbox_example_theme_menu la funzione dovrebbe essere la seguente:

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 - cioè lo slug - per questa voce di menu 'sandbox_theme_display' // Il nome della funzione da chiamare quando si esegue il rendering della pagina di questo menu); add_menu_page ('Sandbox Theme', // Il valore utilizzato per popolare la barra del titolo del browser quando la pagina del menu è attiva 'Sandbox Theme', // Il testo del menu nella barra laterale dell'amministratore 'administrator', // Quali ruoli sono in grado per accedere al menu 'sandbox_theme_menu', // L'ID usato per associare gli elementi del sottomenu a questo menu 'sandbox_theme_display' // La funzione di callback usata per rendere questo menu); add_submenu_page ('sandbox_theme_menu', // L'ID della pagina del menu di livello superiore a cui questo elemento del sottomenu appartiene 'Opzioni di visualizzazione', // Il valore utilizzato per popolare la barra del titolo del browser quando la pagina del menu è attiva 'Opzioni di visualizzazione', // L'etichetta di questa voce di sottomenu viene visualizzata nel menu 'administrator', // Quali ruoli sono in grado di accedere a questo elemento di sottomenu 'sandbox_theme_display_options', // L'ID utilizzato per rappresentare questo elemento di sottomenu 'sandbox_theme_display' // La funzione di callback utilizzata per visualizzare le opzioni per questo elemento di sottomenu); add_submenu_page ('sandbox_theme_menu', 'Opzioni sociali', 'Opzioni sociali', 'amministratore', 'sandbox_theme_social_options', create_function (null, 'sandbox_theme_display ("social_options");'));  // fine sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu');

Conclusione

A questo punto, il nostro tema ha ora la propria voce di menu di primo livello con ciascuna delle schede delle impostazioni accessibili tramite voci di sottomenu. Anche se questo è utile, credo sia importante notare che ci sono alcune opinioni contrastanti sull'introduzione di menu nel Dashboard di WordPress. Sebbene possano rendere il tuo lavoro più visibile e accessibile, possono anche interferire con i menu WordPress esistenti o con altri lavori di terze parti particolarmente se si tenta di posizionare i menu da qualche parte usando il parametro position. Sebbene non esista un errore assoluto o assoluto quando si tratta di introdurre i menu, riflettere attentamente su dove vengono visualizzati i menu. Se un menu WordPress esistente ha senso, registra il tuo lavoro come sottomenu.

Nel prossimo post, inizieremo a dare uno sguardo ai vari elementi di input che possiamo usare per introdurre opzioni nel nostro tema WordPress, nonché come convalidare e disinfettare i dati prima di serializzarli.

Fonti correlate

add_menu_page
add_submenu_page
create_function
funzioni anonime
Impostazioni WordPress Sandbox 0.5

Codice