API-ul de setări WordPress, Partea 3 Totul despre meniuri

În acest moment, am învățat de ce contează API-ul Setări, am învățat totul despre secțiuni, câmpuri și setări și chiar am creat o temă Sandbox pe care o folosim pentru a dezvolta funcționalitatea pe măsură ce explorăm API-ul.

În acest articol, vom examina modul în care putem interfața cu sistemul de meniuri WordPress. Este important să rețineți că aceasta nu este de fapt o parte din API-ul Settings, dar este atât de strâns legată încât ar trebui să ne familiarizăm cu modul în care o folosiți.

Pe măsură ce temele și / sau pluginurile noastre devin mai complexe, trebuie să cunoaștem toate modurile diferite pe care le putem include în Tabloul de bord WordPress. În acest articol, vom analiza diferitele funcții ale meniului WordPress, când să le folosim, când să le evităm și situațiile în care fiecare funcție se potrivește cel mai bine.

Înțelegerea tipurilor de meniu

WordPress oferă patru modalități diferite de a include propriile noastre meniuri. Mai jos, vom arunca o privire asupra fiecărui meniu, parametrii pe care îi acceptă fiecare și exemplifică codul pentru modul de utilizare a acestora pe parcursul proiectelor. Ne propunem să dezvoltăm o înțelegere clară a modului în care funcționează API, deoarece poate pune bazele muncii noastre viitoare.

Meniuri de nivel superior

Paginile de meniu se referă la elementele de meniu pe care le vedeți la prima conectare la WordPress. Acestea sunt opțiunile disponibile în meniul din stânga care pot conține o listă de pagini de submeniu.

Pentru a introduce pagina dvs. de meniu în tabloul de bord WordPress, utilizați funcția add_menu_page.

Vom examina într-un moment un exemplu practic, dar mai întâi să analizăm funcția - acceptă șapte argumente (cinci obligatorii, două opționale):

Titlul paginii se referă la textul care apare în partea de sus a ferestrei browserului ori de câte ori este afișată pagina de meniu de nivel superior.
Titlul meniului este textul care apare în meniul actual. Cel mai bine este să păstrați acest lucru oarecum scurt, altfel se va înfășura în elementul de meniu și ar părea un pic oprit față de restul elementelor de meniu.
capacitate se referă la utilizatorii care au acces la meniu. Aceasta este pur și simplu o valoare de șir care reprezintă unul dintre rolurile disponibile.
Meniu Slug este un identificator unic pe care îl furnizați. Acesta identifică acest meniu în contextul WordPress și se referă, de asemenea, la pagina care afișează opțiunile asociate acestui meniu. De asemenea, oferă un cârlig cu care elementele de submeniu se pot înregistra.
Suna inapoi este funcția care definește conținutul afișat pe pagină care corespunde acestui meniu. Acesta poate fi HTML inline sau se referă la un fișier extern.
Icon URL este calea spre pictograma pe care doriți să o afișați lângă elementul de meniu din meniul WordPress. Aveți posibilitatea să utilizați una dintre pictogramele existente ale WordPress sau să folosiți unul dintre propriile icoane. Acest argument este opțional.
Poziţie definește poziția în care acest meniu va locui în lista elementelor din meniul WordPress. Implicit, meniul apare în partea de jos a meniului, însă o poziție personalizată va plasa meniul deasupra (sau mai jos) oricare dintre elementele de meniu din WordPress existente.

Să aruncăm o privire la un exemplu. Localizați funcțiile.php în caseta de setări WordPress Sandbox și adăugați următoarele două funcții:

funcția sandbox_create_menu_page ()  add_action ('admin_menu', 'sandbox_create_menu_page'); funcția sandbox_menu_page_display ()

Rețineți că folosim cârligul admin_menu pentru a înregistra elementul de meniu. Această funcție particulară apare imediat după ce meniul de bază de administrare este în vigoare, astfel încât doriți să vă înregistrați meniul aici, astfel încât WordPress să îl redă în timp ce afișează restul meniurilor.

Apoi, să setăm elementul de bază din meniu. În conformitate cu articolele anterioare din această serie, iată ce intenționăm să facem:

Adăugați un nou meniu în partea de jos a meniului WordPress
Îi vom da numele temei noastre (adică "Sandbox")
Acesta va fi disponibil tuturor utilizatorilor
Nu va include o pictogramă

Destul de ușor, nu? Să mergem mai departe și să adăugăm meniul nostru. Din nou, nu copiați și lipiți acest cod. Citiți-le, rețineți comentariile și asigurați-vă că înțelegeți pe deplin ce facem:

"sandbox_create_menu_page () add_menu_page ('Opțiuni sandbox', // Titlul care va fi afișat pe pagina corespunzătoare pentru acest meniu 'Sandbox', // Textul care va fi afișat pentru acest element de meniu actual 'Administrator' din utilizatori pot vedea acest meniu 'sandbox', // ID-ul unic - adică, slug - pentru acest element de meniu 'sandbox_menu_page_display', // Numele funcției de apelat la redarea meniului pentru această pagină); // end sandbox_create_menu_page add_action ('admin_menu', 'sandbox_create_menu_page');

Acum, reîmprospătați meniul de administrare WordPress și ar trebui să vedeți un nou element de meniu. Când faceți clic pe el, ar trebui să vedeți o pagină necompletată.

Evident, acest lucru nu este foarte funcțional. Să eliminăm funcția de apel invers definită mai devreme pentru afișare ceva pe ecran:

funcția sandbox_menu_page_display () // Creați un antet în containerul implicit al WordPress "wrap" $ html = '„; $ html. = 'Sandbox
„; $ html. = '
„; // Trimiteți marcajul în browserul echo $ html;  // end sandbox_menu_page_display

Versiunea finală a codului dvs. ar trebui să arate astfel:

/ ** * Adaugă un nou meniu de nivel superior în partea de jos a meniului de administrare WordPress. * / function sandbox_create_menu_page () add_menu_page ('Optiuni de nisip', // Titlul care va fi afisat pe pagina corespunzatoare pentru acest meniu 'Nisip', // Textul care va fi afisat pentru acest element de meniu actual 'administrator', // Ce tip de utilizatori pot vedea acest meniu "sandbox", // ID-ul unic - adică, slug - pentru acest element de meniu "sandbox_menu_page_display", // Numele funcției de apelat la redarea meniului pentru această pagină ") ; // // end sandbox_create_menu_page add_action ('admin_menu', 'sandbox_create_menu_page'); / ** * Redă afișarea de bază a paginii de meniu pentru temă. * / function sandbox_menu_page_display () // Creați un antet în WordPress implicit ' wrap 'container $ html ='„; $ html. = 'Sandbox
„; $ html. = '
„; // Trimiteți marcajul în browserul echo $ html;  // end sandbox_menu_page_display

În afară de modul în care se utilizează efectiv funcția add_menu_page, probabil cea mai subtilă eliminare este că, în WordPress, fiecare element de meniu are o pagină de meniu corespunzătoare. Vom analiza acest lucru mai detaliat în întreaga serie, dar este important să notăm acum că vom începe să explorăm fiecare dintre diferitele tipuri de meniuri.

Deși acest lucru este în mare parte incomplet, vom adăuga la acest lucru prin restul acestui articol și restul tutorialului.

O notă privind poziționarea: Mulți dezvoltatori consideră că utilizarea argumentului de poziție este o etichetă proastă, întrucât amestecă experiența implicită cu utilizatorul cu WordPress. În plus, dacă definiți o poziție și o altă temă, pluginul sau funcția utilizează aceeași poziție, unul dintre elementele de meniu poate fi suprascris.

submeniuri

Submeniurile sunt la fel ca meniurile, cu excepția faptului că aparțin unui alt meniu - au un părinte. Deci, evident, nu puteți crea un submeniu fără a crea mai întâi un element de meniu. Desigur, așa cum am văzut în ultimul articol, elementele submeniului pot fi introduse în elementele de meniu existente - nu doar elementele de meniu personalizate.

În acest articol, vom introduce o pagină de submeniu în elementul nostru de meniu personalizat. Dar, înainte de a face acest lucru, să aruncăm o privire la funcția add_submenu_page și parametrii pe care îi acceptă:

Părinte Slug se referă la ID-ul elementului din meniul părinte la care va aparține acest submeniu. În cazul nostru, vom folosi meniul de slujbă definit mai sus.
Titlul paginii este textul care va apărea în titlul browserului atunci când pagina este redată.
Titlul meniului este textul care va apărea ca element de meniu real din meniul WordPress.
capacitate, ca în meniul părinte, se referă la tipurile de utilizatori care au acces la acest meniu.
Meniu Slug este identificatorul unic pentru acest element de meniu. Este ceea ce este folosit pentru a defini acest meniu special în contextul WordPress.
Suna inapoi este funcția utilizată pentru afișarea pe ecran a paginii acestui meniu.

Dacă doriți să adăugați un element de meniu la unul dintre meniurile existente, consultați tabelul din articolul precedent.

Să începem prin înregistrarea unui submeniu pentru meniul existent de mai sus. Vrem să facem următoarele:

Înregistrați un submeniu pentru a fi adăugat la meniul pe care tocmai l-am creat
Acesta va afișa textul "Opțiuni"
Acesta va fi disponibil tuturor utilizatorilor
Nu va include o pictogramă

Verificați următorul cod - vom adăuga acest lucru direct sub apelul nostru la add_menu_page:

add_submenu_page ('sandbox', // Înregistrați acest submeniu cu meniul definit mai sus 'Opțiuni sandbox', // Textul afișat în browser atunci când acest element de meniu este activ 'Opțiuni', // Textul pentru acest element de meniu ' administrator ', // Ce tip de utilizatori pot vedea acest meniu' sandbox_options ', // ID unic - slug - pentru acest element de meniu' sandbox_options_display '// Funcția folosită pentru a reda meniul pentru această pagină pe ecran);

Nu uitați să definiți apelul de apel, chiar dacă acesta este gol. Adică, nu uitați să adăugați această funcție în fișierul dvs. (vom adăuga mai multe pentru moment):

funcția sandbox_options_display ()  // end sandbox_options_display

Când actualizați browserul, ar trebui să vedeți acum Două submeniurile direct sub meniul "Nisip". Observați că WordPress creează un element de submeniu ca atare - un element submeniu care corespunde elementului de meniu și funcția de apel invers definită. A doua este noua opțiune de submeniu pe care tocmai am definit-o, deși nu face conținut.

Pentru a rezolva asta, hai să mergem mai departe și să introducem o pagină de bază. Actualizați funcția de apel invers a submeniului pentru a arăta astfel:

funcția sandbox_options_display () // Creați un antet în containerul implicit de WordPress 'wrap' $ html = '„; $ html. = 'Opțiunile sandbox
„; $ html. = '
„; // Trimiteți marcajul în browserul echo $ html;  // end sandbox_options_display

Reîmprospătați browserul dvs. din nou și ar trebui să vedeți un titlu de pagină de bază atunci când selectați noul Opțiuni submeniu element.

Deși acest lucru nu este necesar, rețineți că aveți de fapt elementul din meniul părinte și Opțiuni elementul de meniu se referă la același conținut - pur și simplu actualizați apelul înapoi în funcția ad_menu_page la sandbox_options_display funcție pe care tocmai am definit-o.

Plugin Pagini

Dacă dezvoltați un plugin WordPress, atunci există câteva modalități diferite pe care produsul dvs. le poate interfața cu platforma.

Mai exact, pluginul dvs. ...

Poate funcționa în fundal și nu necesită un meniu.
Poate utiliza ambele sau una dintre funcțiile menționate mai sus pentru a construi un meniu personalizat
Poate fi inclusă într-unul din meniurile WordPress existente

Pentru a face mai ușor dezvoltatorii de plugin-uri să includă opțiunile lor în meniurile WordPress existente, API-ul WordPress oferă următoarea funcție: add_plugins_page.

Dar asteapta. Dacă ați urmărit împreună cu exemplele de mai sus, probabil ați observat că nu pare să existe nicio diferență distinctă între add_plugins_page și add_submenu_page. Ai dreptate. add_plugins_page oferă aceeași funcționalitate cu add_submenu_page, dar există două diferențe primare:

Pluginul este furnizat special pentru utilizarea în dezvoltarea pluginurilor.
Funcția adaugă opțiunea de meniu pentru pluginuri direct în WordPress ' Plugin-uri meniul.

Deși cu siguranță puteți utiliza add_submenu_page pentru a atinge același obiectiv, sunt întotdeauna un fan al utilizării funcțiilor care sunt destinate unui caz de utilizare specifică, chiar dacă există o altă funcție API care face același lucru. Când faceți acest lucru, demonstrați că utilizați API ca dezvoltatori și că vă faceți codul mai puțin coerent, deoarece codul dvs. este mai strâns aliniat cu modul în care acesta interacționează cu platforma de bază.

Dezvoltarea pluginurilor este în afara sferei acestei serii, dar nu este complet irelevantă. Deși nu se vor face modificări în tema noastră de tip sandbox, vreau să furnizez un exemplu simplu care arată cum să folosești această funcție particulară.

Mai întâi, să examinăm argumentele acceptate de add_plugins_page:

Titlul paginii este textul care va apărea în titlul browserului atunci când pagina de opțiuni a pluginului este redată.
Titlul meniului este textul care va apărea ca element de meniu al pluginului în meniul WordPress.
capacitate ca în meniul părinte, se referă la tipurile de utilizatori care au acces la acest meniu.
Meniu Slug este identificatorul unic pentru acest element de meniu. Este ceea ce a definit acest meniu special în contextul WordPress.
Suna inapoi este funcția utilizată pentru afișarea pe ecran a paginii acestui meniu.

Iată un exemplu simplu care demonstrează exact cum să îl folosiți. Rețineți că puteți include acest lucru în fișierul functions.php, dar este nu parte din tema Sandbox pe care lucrăm și ar trebui folosită în contextul unui plugin.

Mai întâi, configurați apelul la funcția API - observați că acesta utilizează cârligul admin_menu:

function sandbox_example_plugin_menu () add_plugins_page ('Plugin Sandbox', // Titlul care va fi afisat in fereastra browserului pentru aceasta pagina 'Plug-in Sandbox', // Textul care va fi afisat pentru acest meniu 'administrator', // tipul de utilizatori pot vedea acest element de meniu 'sandbox_plugin_options', // ID-ul unic - adică, slug - pentru acest element de meniu 'sandbox_plugin_display' // Numele funcției de apelat la redarea paginii pentru acest meniu);  // end sandbox_example_plugin_menu add_action ('admin_menu', 'sandbox_example_plugin_menu');

Apoi, configurați funcția care va afișa afișarea pluginului:

funcția sandbox_plugin_display () // Creați un antet în containerul implicit al lui WordPress 'wrap' $ html = '„; $ html. = 'Opțiuni plugin Plugin
„; $ html. = 'În prezent nu există opțiuni. Aceasta este doar pentru scopuri demo.
„; $ html. = '
„; // Trimiteți marcajul în browserul echo $ html;  // end sandbox_plugin_display

Reîmprospătați tabloul de bord WordPress, treceți cu mouse-ul peste Plugin-uri și ar trebui să observați un nou element de meniu. Nu-i rău, huh?

Versiunea finală a codului ar trebui să arate astfel:

/ ** * Această funcție introduce o singură opțiune de meniu temă în meniul WordPress 'Plugins' * *. * / function sandbox_example_plugin_menu () add_plugins_page ('Plugin Sandbox', // Titlul care va fi afisat in fereastra browserului pentru aceasta pagina 'Sandbox Plugin', // Textul care va fi afisat pentru acest meniu 'administrator', / / Ce tip de utilizatori pot vedea acest element de meniu 'sandbox_plugin_options', // ID-ul unic - adică, slug - pentru acest element de meniu 'sandbox_plugin_display' // Numele funcției de apelat la redarea paginii pentru acest meniu) ;  // end sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_plugin_menu'); / ** * Reface o pagină simplă pe care să o afișați pentru meniul de teme definit mai sus. * / function sandbox_plugin_display () // Creați un antet în containerul implicit de WordPress 'wrap' $ html = '„; $ html. = 'Opțiuni plugin Plugin
„; $ html. = 'În prezent nu există opțiuni. Aceasta este doar pentru scopuri demo.
„; $ html. = '
„; // Trimiteți marcajul în browserul echo $ html;  // end sandbox_plugin_display

Din nou, această funcție nu va face parte din tema Sandbox, deoarece este orientată mai mult spre dezvoltarea pluginurilor; cu toate acestea, merită să acoperiți pentru cei dintre dvs. că veți folosi API-ul Setări în efortul dvs. de dezvoltare a pluginurilor.

Tematica paginilor

La fel ca în cazul pluginurilor, WordPress oferă o funcție API pentru introducerea unor meniuri specifice temelor. Este foarte asemănător cu funcția din meniul plugin-ului, deoarece oferă încă un alt mod de a introduce un submeniu în meniurile existente. Diferența principală este că submeniul este adăugat la Aspect meniul.

Ca și în cazul exemplului pluginului din acest articol, vom examina modul în care putem folosi această funcție, dar nu o vom include în tema noastră de tip sandbox. Aceasta se referă doar la demonstrarea modului de utilizare a funcției doar în cazul în care optați pentru a merge pe acest traseu în munca personală.

În primul rând, vom examina argumentele acceptate de add_theme_page. Veți observa că ele sunt la fel ca cele necesare pentru meniul plugin-ului și foarte asemănătoare cu funcțiile de submeniu pe care le-am prezentat mai devreme:

add_theme_page acceptă următoarele argumente:

Titlul paginii este textul care va apărea în titlul browserului atunci când pagina de opțiuni a temei este redată.
Titlul meniului este textul care va apărea ca element de meniu al temei din meniul WordPress.
capacitate ca în meniul părinte, se referă la tipurile de utilizatori care au acces la acest meniu.
Meniu Slug este identificatorul unic pentru acest element de meniu. Este ceea ce a definit acest meniu special în contextul WordPress.
Suna inapoi este funcția utilizată pentru afișarea pe ecran a paginii acestui meniu.

Ca și în cazul celorlalte funcții, vom crea câteva exemple de funcții care arată cum să includem acest lucru în proiectul dvs. Rețineți că apelul către add_theme_page poate fi adăugat funcțiilor.php și, spre deosebire de apelurile către add_plugin_page, ar trebui să locuiți aici atunci când vă dezvoltați tema.

În primul rând, apelul pentru configurarea elementului de meniu:

"sandbox_example_theme_menu () add_theme_page ('Themebox', // Titlul care va fi afișat în fereastra browserului pentru această pagină. 'Themebox', // Textul care va fi afișat pentru acest element de meniu 'administrator', // tipul de utilizatori poate vedea acest element de meniu 'sandbox_theme_options', // ID-ul unic - adică, slug - pentru acest element de meniu 'sandbox_theme_display' // Numele funcției de apelat la redarea paginii pentru acest meniu);  // end sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu');

Apoi, vom seta o funcție pentru renderarea paginii cu opțiuni:

funcția sandbox_theme_display () // Creează un antet în containerul implicit de WordPress 'wrap' $ html = '„; $ html. = 'Opțiuni Tematică pentru Opțiuni Sandbox
„; $ html. = 'În prezent nu există opțiuni. Aceasta este doar pentru scopuri demo.
„; $ html. = '
„; // Trimiteți marcajul în browserul echo $ html;  // end sandbox_theme_display

Acum reîmprospătați tabloul de bord WordPress, treceți peste Aspect și ar trebui să vedeți noul element de meniu. Simplu!

Versiunea finală a codului ar trebui să arate astfel:

/ ** * Această funcție introduce o singură opțiune de meniu temă în meniul WordPress 'Appearance' *. * / function sandbox_example_theme_menu () add_theme_page ('Themebox', // Titlul care va fi afisat in fereastra browserului pentru aceasta pagina 'Themebox', // Textul care va fi afisat pentru acest meniu 'administrator', / / Ce tip de utilizatori pot vedea acest element de meniu 'sandbox_theme_options', // ID-ul unic - adică slug - pentru acest element de meniu 'sandbox_theme_display' // Numele funcției de apelat la redarea paginii pentru acest meniu) ;  // end sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu'); / ** * Reface o pagină simplă pe care să o afișați pentru meniul de teme definit mai sus. * / function sandbox_theme_display () // Creați un antet în containerul implicit de WordPress 'wrap' $ html = '„; $ html. = 'Opțiuni Tematică pentru Opțiuni Sandbox
„; $ html. = 'În prezent nu există opțiuni. Aceasta este doar pentru scopuri demo.
„; $ html. = '
„; // Trimiteți marcajul în browserul echo $ html;  // end sandbox_theme_display

Pentru cei care sunteți interesați de dezvoltarea unei teme mai avansate, probabil că ați luat în considerare diferitele modalități de a implementa mai multe pagini de opțiuni pentru tema dvs..

Pe de o parte, putem adăuga mai multe submeniuri la un meniu de nivel superior, dar acolo este o alternativă: navigare cu file. Acest lucru se impune bine atunci când doriți să introduceți opțiuni pentru Aspect meniu și nu adăugați încă un element de meniu în tabloul de bord WordPress. Vom discuta acest lucru în detaliu în următorul articol.

Când să utilizați fiecare funcție

Am analizat fiecare dintre cele patru modalități majore de a introduce propriile pagini de opțiuni în WordPress. Deși aceste funcții nu fac parte din API-ul Setări, este important să discutăm pentru că lucrează atât de strâns în legătură cu acesta.

Dar cunoașterea acestor funcții este doar o jumătate din ea. În calitate de dezvoltator responsabil pentru integrarea și organizarea setărilor, este important să știți când să utilizați fiecare dintre diferitele funcții în contextul propriu.

Deși nu există răspuns pentru glonț de argint pentru momentul utilizării fiecărei funcții, iată câteva reguli care trebuie luate în considerare atunci când lucrați la funcțiile personalizate, pluginurile și / sau tema:

Meniuri de nivel superior pot fi adăugate atunci când există un submeniu care poate fi grupat logic cu aceste opțiuni. Acest lucru se impune atunci când aveți o colecție importantă de setări care nu se încadrează logic în nici unul dintre meniurile WordPress existente.
submeniuri aparțin întotdeauna unui meniu de nivel superior - fie personalizat, fie pre-existent. Acestea ar trebui să fie întotdeauna grupate sub meniul de nivel superior care este cel mai logic. Dacă WordPress oferă un meniu care poate servi drept părinte pentru submeniul dvs., utilizați-l; nu poluează meniul cu un meniu redundant de nivel superior.
Plugin Menus ar trebui să fie utilizate atunci când aveți opțiuni simple, de o pagină pentru plugin-ul dvs. Dacă aveți mai multe pagini cu opțiuni, luați în considerare crearea unui meniu de nivel superior sau luați în considerare utilizarea navigației cu ajutorul cărților pe care o vom explora în următorul articol.
Tematica meniurilor ar trebui să fie utilizate atunci când vă dezvoltați propria temă care oferă propriul set de opțiuni personalizate. Dacă opțiunile pot trăi pe o singură pagină, luați în considerare utilizarea funcției API a WordPress. Dacă aveți mai multe opțiuni, luați în considerare utilizarea navigației cu file. Rețineți că mulți dezvoltatori de teme adesea ridică opțiunile temei la meniul de nivel superior și că este bine.

Un cuvânt despre meniurile personalizate: Deși WordPress ne dă posibilitatea de a adăuga propriile noastre meniuri de nivel superior, adăugăm la orice meniu existent și, în general, ne dă posibilitatea de a face ceea ce vrem cu configurația implicită, o parte din comunitate se încruntă în acest sens. Ei cred că funcționalitatea personalizată nu trebuie să interfereze cu anumite meniuri de bază. Deși depinde în cele din urmă de dvs., implementați-vă munca cu discernământ - șansele sunt, puține lucruri pe care le faceți sunt mai importante decât funcționalitatea de bază a WordPress, așa că nu vă așezați munca deasupra.

Ce este în continuare?

În următorul articol, vom aplica un pic de ceea ce am învățat despre meniuri și vom începe să introducem pagini cu opțiuni pentru tema noastră de tip sandbox.

În plus față de adăugarea de pagini de meniu, vom analiza, de asemenea, navigarea cu file și modul în care o putem implementa pentru a funcționa împreună cu propriile pagini de meniu.

Între timp, revizuiți articolele anterioare din această serie și nu uitați să finalizați versiunea curentă a casetei de setări WordPress Sandbox pe GitHub.

Resurse conexe

Am acoperit destul de puține resurse în acest articol. Iată un rezumat al tuturor lucrurilor pe care le-am folosit:

add_menu_page
add_submenu_page
add_plugins_page
add_theme_page
Setările WordPress Sandbox

Cod