Unlimited Plugins, WordPress themes, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Code
  2. Theme Development

Le Settings API, parte 3: tutto sui menu

by
Difficulty:BeginnerLength:LongLanguages:
This post is part of a series called The Complete Guide to the WordPress Settings API.
The WordPress Settings API, Part 2: Sections, Fields, and Settings
The WordPress Settings API, Part 4: On Theme Options

Italian (Italiano) translation by Fabio Pantano (you can also view the original English article)

A questo punto, abbiamo imparato perché sono importanti le Settings API, tutto sulle sezioni, campi e opzioni, e abbiamo anche configurato un tema sandbox su cui poter sviluppare e analizzare tutte le funzionalità delle API

In questo articolo, daremo un'occhiata a come interfacciarsi al sistema dei menu di WordPress. E' importante osservare che non è un argomento delle Settings API, ma siccome è strettamente legato, è importante familiarizzare con esso.

Siccome i temi e/o i plugin diventano sempre più complessi, è importante conoscere i vari metodi su come includerli nella dashboard di WordPress. In questo articolo, analizzeremo le funzioni dei menu WordPress, quando usarle, quando evitarle e le situazioni in cui sfruttarle al meglio.


Capire i tipi di menu

WordPress offre quattro diversi metodi per includere i propri menu. Approfondiremo ogni menu, i parametri accettati ed esempi di codice su come usarli nei progetti. Punteremo a capire chiaramente come funzionano le API e stabilire una base di partenza per i nostri futuri progetti.

Menu di livello superiore

Le pagine dei menu si riferiscono agli elementi dei menu che si vedono dopo il login iniziale in WordPress. Cioè sono le varie opzioni disponibili nel menu di sinistra, che a sua volta possono contenere ulteriori pagine in sotto-menu.

All About Menus

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

Analizzeremo un esempio pratico tra poco, prima esaminiamo la funzione in se; accetta 7 argomenti (5 obbligatori, 2 facoltativi):

  • Titolo pagina è il testo che appare in cima alla pagina quando si apre il rispettivo menu della pagina.
  • Titolo menu è il testo che appare come voce nel menu a sinistra. Si consiglia di mantenere un nome breve, altrimenti andrà a capo o risulterà più lungo rispetto alle altre voci.
  • Capacità si riferisce agli utenti che possono avere accesso al menu. E' un semplice valore che rappresenta uno dei ruoli disponibili.
  • Slug menu è un identificatore univoco. Identifica questo menu nel contesto di WordPress e si riferisce alla pagina che visualizza le opzioni associate. Fornisce anche un "gancio" con il quale registrare i sotto-menu.
  • Callback è la funzione che definisce come visualizzare il contenuto corrispondente. Può essere una stringa HTML o far riferimento a un file esterno.
  • URL Icona è il percorso dell'icona che si vuole visualizzare accanto alla voce del menu. Puoi usarne una esistente di WordPress o una personale. Questo argomento è facoltativo.
  • Posizione definisce la posizione in cui risiede tale menu nel menu principale di WordPress. Di default, il menu appare alla fine del menu principale, ma con una posizione personalizzata si potrà inserirlo dove si vuole, sopra o sotto di una voce già esistente.

Vediamo un esempio. Aprite il file functions.php della nostra sandbox e aggiungete queste due funzioni:

Potete notare l'uso dell'hook (gancio) admin_menu per registrare il nostro elemento nel menu. Questa particolare funzione viene inserita alla destra del menu di amministrazione in modo tale da consentire a WordPress di generare il menu durante la visualizzazione delle altre voci principali.

Poi procediamo con la configurazione dell'elemento di base del menu. Per mantenere una certa coerenza con gli articoli recenti, ecco una lista con le cose da fare:

  • Aggiungere un nuovo menu in fondo al menu principale di WordPress
  • Gli daremo il nome del nostro tema (cioè "Sandbox")
  • Qualsiasi utente potrà accedervi
  • Non avrà nessuna icona

Tutto facile, no? Procediamo con l'aggiungere il nostro menu. Non copiare e incollare semplicemente il codice. Analizzatelo, leggendo i commenti, e assicuratevi di averlo capito:

Ora eseguite il refresh del menu principale di WordPress, dovreste vedere una nuova voce di menu. Facendo click, dovreste visualizzare una pagina vuota.

Ovviamente, questo non è funzionale. Procediamo con la funzione definita poco fa per visualizzare qualcosa a schermo:

La porzione di codice finale sarà la seguente:

A parte l'uso della funzione add_menu_page, c'è da sottolineare che in WordPress ogni elemento del menu ha una pagina corrispondente. Approfondiremo questo aspetto nel corso della serie, ora è importante farlo notare per cominciare a esplorare tutte le varianti dei tipi di menu.

Sebbene sia in gran parte incompleto, lo arricchiremo durante questo articolo e nel resto del tutorial. 

Una nota sul posizionamento: molti sviluppatori considerano l'argomento della posizione una cattiva funzionalità, in quanto andrebbe a confondersi con l'esperienza utente di WordPress. Inoltre se si definisce una posizione e un altro tema, plugin o funziona utilizza la stessa posizione, uno degli elementi verrebbe sovrascritto.

Sotto-menu

I sotto-menu sono semplici menu all'interno di un altro menu genitore. Ovviamente non puoi creare un sotto-menu senza averne creato uno prima. Naturalmente, come abbiamo visto nel precedente articolo, le voci dei sotto-menu possono essere introdotte a voci di menu esistenti, non solo a voci di menu personalizzate.

In questo articolo, inseriremo la pagina di un sotto-menu dentro un elemento menu personalizzato. Ma prima, vediamo la funzione add_submenu_page e i parametri che accetta:

  • Slug genitore si riferisce all'ID del menu genitore al quale appartiene il sotto-menu. Nel nostro caso, useremo lo slug del menu definito prima.
  • Titolo pagina è il testo che apparirà come titolo sul browser quando la pagina viene visualizzata.
  • Titolo menu è il testo della voce di questo sotto-menu che appare nel menu principale di WordPress.
  • Capacità, come per il menu genitore, si riferisce al tipo di utenza abilitata all'accesso di questo particolare menu.
  • Slug menu è l'identificatore unico per questo elemento. Viene usato per identificare questo particolare menu nell'ambiente WordPress.
  • Callback è la funzione usata per presentare la pagina su schermo.

Se si vuole aggiungere un elemento a dei menu già esistenti, fate riferimento al precedente articolo.

Ora registriamo il sotto-menu in un menu esistente. Questo è quello che faremo:

  • Registrare un sotto-menu da aggiungere a un menu già presente
  • Visualizzerà il testo "Opzioni"
  • Sarà disponibile per tutti gli utenti
  • Non avrà alcuna icona

Analizzate il seguente codice, sarà aggiunto direttamente sotto la nostra funzione add_menu_page:

Definiamo anche la funzione callback, che risulterà vuota al momento, e ricordarsi di aggiungerla al file.

Facciamo un refresh al browser, ora si dovrebbero vedere due elementi sotto-menu direttamente sotto il menu "Sandbox". Notare che WordPress crea un sotto-menu a suo modo: un sotto-menu che corrisponde all'elemento del menu applicando la funzione di callback definita. Il secondo è il nuovo sotto-menu che abbiamo definito, sebbene sia senza contenuti.

Quindi procediamo nell'introdurre una pagina base. Aggiornate la funzione di callback con il seguente codice:

Refresh sul browser, si dovrebbe vedere un titolo sulla pagina base cliccando su Options nel sotto-menu.

Anche se non è richiesto, si può in realtà far puntare la voce del menu principale e la voce del menu Options allo stesso contenuto. Aggiornate semplicemente la chiamata nella funzione add_menu_page alla funzione sandbox_options_display che abbiamo appena definito.


Pagine plugin

Se state sviluppando un plugin per WordPress, ci sono tre diversi modi con cui può interfacciarsi con la piattaforma.

In particolare, il plugin...

  1. può funzionare in background e non richiede un menu
  2. può usare entrambe o una delle funzioni analizzate in precedenza per i menu personalizzati
  3. può essere aggiunto a un menu WordPress già esistente 

Per facilitare agli sviluppatori di plugin l'aggiunta delle opzioni a un menu WordPress esistente, le API offrono la seguente funzione: add_plugins_page. 

Ma aspettate. Se avete seguito gli esempi riportati sopra, avrete probabilmente notato che non c'è nessuna differenza di sorta tra add_plugins_page e add_submenu_page. Giusto. add_plugins_page offre la stessa funzionalità di add_submenu_page, ma ci sono due differenze sostanziali:

  1. la funzione plugin è fornita specificatamente per lo sviluppo dei plugin
  2. la funzione aggiunge le opzioni del plugin direttamente nel menu Plugins di primo livello di Wordpress.

Sebbene è possibile usare add_submenu_page per raggiungere lo stesso risultato, consiglio sempre di usare funzioni destinate a casi specifici, anche se fanno la medesima cosa di un'altra funzione API. Con questo approccio puoi comunicare che stai usando le API per come sono state sviluppate rendendo il codice più coerente e allineato con il core della piattaforma.  

Lo sviluppo di un plugin non è lo scopo di questa particolare serie, ma ha la sua importanza. Anche se non modificheremo il nostro tema Sandbox, ho intenzione di fornire comunque un esempio su come usare questa funzione.

Analizziamo gli argomenti che accetta add_plugins_accepts:

  • Titolo pagina è il testo che appare sul browser quando viene visualizzata la pagina del plugin con le opzioni.
  • Titolo menu è il testo della voce del menu che appare nel menu di WordPress. 
  • Capacità, come con il menu genitore, si riferisce al tipo di utenti che hanno accesso al menu.
  • Slug menu è l'identificatore unico per elemento del menu. Viene usato come riferimento del menu nell'ambiente WordPress.
  • Callback è la funzione usata per la visualizzazione della pagina a schermo.

Ecco un semplice esempio per spiegare come funziona. Potete includerlo nel file functions.php ma non fa parte del tema Sandbox su cui stiamo lavorando ma dovrebbe invece essere usato in ambito plugin.

Primo, impostare la chiamata alla funzione API, notare l'uso dell'hook admin_menu:

Poi, configurare la funzione che visualizza la pagina del plugin:

Refresh la dashboard di WordPress, aprire il menu Plugins, noterete una nuova voce di menu . Non male, no?

Il codice finale dovrebbe essere questo:

Ripeto che questa funzione non fa parte del tema Sandbox perché è più orientata ai plugin. Tuttavia, vale la pena fare un accenno per quelli di voi che vogliono sfruttare le Settings API per lo sviluppo di plugin.

Pagine tema

Proprio come con i plugins, WordPress fornisce una funzione API per introdurre i menu per i temi. E' molto simile alla funzione per i menu dei plugin, in cui poter introdurre un sotto-menu a un menu già esistente. La differenza più importante è che il sottomenu viene aggiunto al menu Appearance (Aspetto).

Come con l'esempio visto poco fa con i plugin, daremo uno sguardo anche a come usare questa funzione ma non verrà implementata nel nostro tema Sandbox. E' un semplice modo per dimostrare l'uso della funzione nel caso in cui si vorrà optare per questa soluzione in un personale progetto. 

Primo, analizziamo gli argomenti che accetta add_theme_page. Noterete che sono gli stessi argomenti richiesti per il menu del plugin e molto simili alle funzioni per i sotto-menu visto in precedenza:

add_theme_page accetta i seguenti argomenti:

  • Titolo pagina è il testo che appare nel browser quando la pagine delle opzioni viene visualizzata.
  • Titolo menu è il testo della voce che appare nel menu WordPress.
  • Capacità, come con il menu genitore, si riferisce al tipo di utenti che hanno accesso al menu.
  • Slug menu è l'identificatore unico per elemento del menu. Viene usato come riferimento del menu nell'ambiente WordPress.
  • Callback è la funzione usata per la visualizzazione della pagina a schermo.

Come con le altre funzioni, creeremo un paio di semplici funzioni per mostrare come includerla in un progetto. Notare che la chiamata add_theme_page può essere aggiunta al file functions.php, e a differenza della chiamata add_plugin_page, dovrebbe risiedere qui durante lo sviluppo del tema. 

Per prima cosa, la chiamata per configurare l'elemento del menu:

Poi, configuriamo la funzione per visualizzare la pagine con le opzioni:

Ora refresh sulla dashboard di WordPress, aprire il menu Appearance (Aspetto), si dovrebbe vedere la nuova voce del menu. Semplice!

Il codice finale dovrebbe essere simile a questo:

Per quelli di voi che sono interessati a sviluppare un tema più avanzato, probabilmente dovrete considerare i vari modi per implementare varie pagine opzione nel tema.

Da un certo punto di vista, possiamo aggiungere più sottomenu ad un menu di primo livello, ma c'è un'alternativa: una navigazione a schede. Questa si presta bene quando si vuole introdurre le opzioni al menu Appearance (Aspetto) senza aggiungere un'altra voce al menu principale di WordPress. Ne discuteremo in maniera più approfondita nel prossimo articolo.


Quando usare ogni funzione

Abbiamo dato uno sguardo a ciascuno dei quattro principali modi per introdurre le nostre pagine opzioni in WordPress. Anche se queste funzioni non fanno specificamente parte delle Settings API, è importante trattarle dato che sono legate strettamente a esse.

Ma la conoscenza di queste funzioni è solo la metà del lavoro. Come sviluppatore responsabile dell'integrazione e dell'organizzazione delle opzioni, è importante sapere quando utilizzarle nel loro giusto contesto.

Anche se non c'è nessuna risposta definitiva su quando utilizzare ciascuna funzione, ecco qui alcune linee guida da considerare quando si lavora su funzioni personalizzate, plugin e/o tema:

  • Menu di primo livello può essere aggiunto quando c'è un sotto-menu che deve logicamente raggruppare una serie di opzioni. Risulta necessario quando si dispone di una importante collezione di opzioni che non rientrano logicamente in uno dei menu WordPress già esistenti.
  • I sotto-menu appartengono sempre a un menu di primo livello, o personalizzato o già presente. Dovrebbero essere raggruppati in modo logico sotto un menu di primo livello. Se WordPress offre un menu da sfruttare come genitore, usatelo. Non popolare la dashboard con ridondanti menu di primo livello. 
  • I menu per plugin dovrebbero essere usati quando si ha una singola pagina di opzioni per il plugin. In caso di pagine a opzioni multiple, considerate di creare un menu di primo livello o una navigazione a schede, che analizzeremo nel prossimo articolo. 
  • I menu per temi dovrebbero essere usati durante lo sviluppo di un proprio tema personale, nel quale inserire una serie di opzioni personalizzate. Se le opzioni non possono stare in una singola pagina, considerate l'uso delle WordPress API. Se avete una serie di opzioni, valutate una navigazione a schede. Molti sviluppatori di temi spesso raggruppano tutte le opzioni relative al tema in un menu di primo livello, ed è un'ottima soluzione.

Un commento sui menu personalizzati: sebbene WordPress fornisca la possibilità di aggiungere menu di primo livello, sfruttare menu già esistenti e in generale fare quello che si vuole a proprio piacimento, una parte della community non approva tale metodologia. Essi sostengono che le funzionalità personalizzate non dovrebbero interferire con il core dei menu di WordPress. Spetta a voi realizzare un lavoro con discernimento, anche se alcune funzionalità che andrete a implementare sono più importanti del core di WordPress, quindi date importanza alla buona riuscita del lavoro finale. 


Cosa ci aspetta?

Nel prossimo articolo andremo ad applicare ciò che abbiamo imparato sui menu e inizieremo a introdurre le pagine di opzioni per il nostro tema.

Oltre alle pagine dei menu, analizzeremo anche la navigazione a schede e come implementarla per farla funzionare congiuntamente alle nostre pagine dei menu.

Nel frattempo, ripassate gli articoli precedenti di questa serie e non dimenticate di dare uno sguardo alla versione della Sandbox su GitHub.


Risorse correlate

Abbiamo studiato un po' di argomenti in questo articolo. Ecco un riepilogo: 

Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.