WordPress Settings API, Del 3 Allt om menyer

Vid denna tidpunkt har vi lärt oss varför inställnings API-värdet är viktigt, vi har lärt oss allt om avsnitt, fält och inställningar och vi har även satt upp ett Sandbox-tema som vi använder för att utveckla funktionalitet när vi utforskar API.

I den här artikeln ska vi titta på hur vi kan koppla samman med WordPress menysystem. Det är viktigt att notera att detta inte är en del av inställnings API, men det är så nära att vi ska bekanta oss med hur vi använder det.

Eftersom våra teman och / eller plugins blir mer komplexa, måste vi veta alla de olika sätten att vi kan inkludera dem i WordPress Dashboard. I den här artikeln ska vi titta på de olika WordPress-menyfunktionerna, när de ska användas, när de ska undvikas och de situationer som varje funktion gör sig bäst av.

Förstå meny typer

WordPress erbjuder fyra olika sätt att inkludera våra egna menyer. Nedan tar vi en titt på varje meny, parametrarna accepterar och kodar exempel för hur man använder dem genom hela projekten. Vi strävar efter att utveckla en tydlig förståelse för hur API fungerar, eftersom det kan lägga grunden för vårt framtida arbete.

Menyn på toppnivå

Menysidor hänvisar till menyalternativen som du ser när du loggar in på WordPress. Det vill säga de är tillgängliga alternativ i den vänstra menyn som kan innehålla en lista med undermenysidor.

För att presentera din egen menysida i WordPress Dashboard använder du funktionen add_menu_page.

Vi tar en titt på ett praktiskt exempel på ett ögonblick, men först låt oss se över funktionen - den accepterar sju argument (fem krävs, två valfria):

Sidans titel hänvisar till texten som visas högst upp i webbläsarfönstret när toppsidans menysida visas.
Menyn Titel är texten som visas i den aktuella menyn. Det är bäst att hålla det lite kort, annars kommer det att gå i menyalternativet och se lite ut mot resten av menyalternativen.
Förmåga refererar till vilka användare som har tillgång till menyn. Det här är helt enkelt ett strängvärde som representerar en av de tillgängliga rollerna.
Menyslak är en unik identifierare som du tillhandahåller. Den identifierar den här menyn i WordPress-sammanhanget och hänvisar också till den sida som visar alternativen som är associerade med den här menyn. Det ger också en krok med vilka undermenyobjekt kan registrera sig.
Ring tillbaka är den funktion som definierar innehållet som visas på sidan som motsvarar den här menyn. Detta kan vara inline HTML eller referera till en extern fil.
Ikonadress är sökvägen till ikonen som du vill visa bredvid menyalternativet i WordPress-menyn. Du kan använda en av WordPress befintliga ikoner eller använda en av dina egna. Detta argument är valfritt.
Placera definierar den position där denna meny kommer att ligga i listan över WordPress-menyalternativ. Som standard visas menyn längst ner i menyn, men en anpassad position kommer att placera din meny ovanför (eller nedan) någon av de befintliga menyalternativen för WordPress.

Låt oss ta en titt på ett exempel. Leta upp functions.php i WordPress Settings Sandbox och lägg till följande två funktioner:

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

Observera att vi använder admin_menu-kroken för att registrera vårt menyalternativ. Den här funktionen brinner strax efter att den grundläggande administrativa menyn är på plats så att du vill registrera din meny här så att WordPress gör det samtidigt som resten av menyerna visas.

Låt oss sedan konfigurera det grundläggande menyalternativet. I överensstämmelse med artiklarna tidigare i denna serie är här vad vi planerar att göra:

Lägg till en ny meny längst ner på WordPress-menyn
Vi ska ge namnet på vårt tema (det vill säga "Sandbox")
Det kommer att vara tillgängligt för alla användare
Det kommer inte att innehålla en ikon

Lätt nog, eller hur? Låt oss fortsätta och lägga till vår meny. Återigen, kopiera inte och klistra in den här koden. Läs det, notera kommentarerna och se till att du förstår helt vad vi gör:

funktion sandbox_create_menu_page () add_menu_page ('Sandbox Options', // Titeln som ska visas på motsvarande sida för denna meny 'Sandbox', // Texten som ska visas för det här aktuella menyalternativet 'administrator', // Vilken typ av användarna kan se denna meny "sandbox", // Det unika ID-det är sluget - för det här menyalternativet "sandbox_menu_page_display", // Namnet på funktionen som ska ringas när menyn visas för den här sidan "); // slut sandbox_create_menu_page add_action ('admin_menu', 'sandbox_create_menu_page');

Uppdatera nu din WordPress-administration meny och du bör se ett nytt menyalternativ. När du klickar på den ska du se en tom sida visas.

Självklart är detta inte särskilt funktionellt. Låt oss stubba den återuppringningsfunktion som vi definierade tidigare för att kunna visas något på skärmen:

funktion sandbox_menu_page_display () // Skapa en rubrik i standardbehållaren WordPress 'wrap' $ html = ''; $ html. = 'Sandlåda
'; $ html. = '
'; // Skicka markeringen till webbläsaren echo $ html;  // slut sandbox_menu_page_display

Den slutliga versionen av din kod ska se ut så här:

/ ** * Lägger till en ny toppmenyn längst ner på WordPress-administrationsmenyn. * / funktion sandbox_create_menu_page () add_menu_page ('Sandbox Options', // Titeln som ska visas på motsvarande sida för denna meny 'Sandbox', // Texten som ska visas för det här aktuella menyalternativet 'administrator', // Vilken typ av användare kan se den här menyn "sandbox", // Det unika ID-det är sluget - för det här menypunktet "sandbox_menu_page_display", // Namnet på funktionen som ska ringas när menyn visas för denna sida ") ; // end sandbox_create_menu_page add_action ('admin_menu', 'sandbox_create_menu_page'); / ** * Ger den grundläggande displayen på menysidan för temat. * / funktion sandbox_menu_page_display () // Skapa en rubrik i standard WordPress ' wrap 'container $ html =''; $ html. = 'Sandlåda
'; $ html. = '
'; // Skicka markeringen till webbläsaren echo $ html;  // slut sandbox_menu_page_display

Annat än hur man faktiskt använder add_menu_page-funktionen är kanske den mest subtila borttagningen att i WordPress har varje menyalternativ en motsvarande menysida. Vi kommer att titta på detta mer ingående i hela serien, men det är viktigt att notera nu när vi börjar utforska var och en av de olika typerna av menyer.

Även om detta i stor utsträckning är ofullständigt, lägger vi till det här genom resten av den här artikeln och resten av handledningen.

En anteckning om positionering: Många utvecklare anser att man använder positionsargumentet som dålig etikett eftersom det blandar upp den vanliga användarupplevelsen med WordPress. Dessutom, om du definierar en position och ett annat tema, plugin eller funktion använder samma position, kan en av menyalternativen skrivas över.

menyer~~POS=HEADCOMP

Undermenyer är precis som menyer med undantag för att de tillhör en annan meny - de har förälder. Så självklart kan du inte skapa en undermeny utan att skapa menyalternativ först. Naturligtvis, som vi såg i den senaste artikeln, kan undermenyalternativ introduceras till befintliga menyalternativ - inte bara anpassade menyalternativ.

I den här artikeln introducerar vi en undermenysida i vårt eget menyalternativ. Men innan du gör det, låt oss ta en titt på add_submenu_page-funktionen och de parametrar som den accepterar:

Föräldra Slug refererar till ID-numret för det överordnade menyobjekt som denna undermeny kommer att tillhöra. I vårt fall använder vi menyns slug som vi definierade ovan.
Sidans titel är texten som kommer att visas i webbläsarens titel när sidan görs.
Menyn Titel är texten som kommer att visas som det aktuella menyalternativet i WordPress-menyn.
Förmåga, som med föräldramenyn, hänvisar till vilka typer av användare som har tillgång till den här menyn.
Menyslak är den unika identifieraren för det här menyalternativet. Det är vad som används för att definiera denna meny inom ramen för WordPress.
Ring tillbaka är den funktion som används för att göra denna menys sida till skärmen.

Om du vill lägga till ett menyalternativ i en av de befintliga menyerna, se tabell i föregående artikel.

Låt oss börja med att registrera en undermeny för den befintliga menyn ovan. Vi vill göra följande:

Registrera en undermeny som ska läggas till i menyn som vi just skapat
Det kommer att visa texten "Alternativ"
Det kommer att vara tillgängligt för alla användare
Det kommer inte att innehålla en ikon

Kolla in följande kod - vi lägger till detta direkt under vårt samtal till add_menu_page:

add_submenu_page ('sandbox', // Registrera den här undermenyn med menyn som definierats ovan 'Sandbox Options', // Texten till skärmen i webbläsaren när det här menyalternativet är aktivt 'Alternativ', // Texten för det här menyalternativet ' Administratör ', // Vilken typ av användare kan se denna meny' sandbox_options ', // Det unika ID-sluget - för det här menyalternativet' sandbox_options_display '// Funktionen brukade göra menyn för denna sida till skärmen);

Glöm inte att definiera återuppringningen, även om den är tom. Det vill säga, glöm inte att lägga till den här funktionen i din fil (vi lägger till mer tillfälligt):

funktion sandbox_options_display ()  // slut sandbox_options_display

När du uppdaterar din webbläsare bör du nu se två undermenyalternativ direkt under "Sandbox" -menyn. Observera att WordPress skapar en undermenyobjekt i sig - det är ett undermenyobjekt som motsvarar menyalternativet och den återuppringningsfunktionen som definierats. Den andra är det nya undermenyalternativet som vi just definierat, men det gör inget innehåll.

För att åtgärda det, låt oss fortsätta och presentera en grundläggande sida. Uppdatera undermenyns återuppringningsfunktion så här:

funktion sandbox_options_display () // Skapa en rubrik i standardbehållaren WordPress 'wrap' $ html = ''; $ html. = 'Sandbox Alternativ
'; $ html. = '
'; // Skicka markeringen till webbläsaren echo $ html;  // slut sandbox_options_display

Uppdatera webbläsaren igen och du bör se en grundläggande sidtitel när du väljer den nya alternativ undermenyobjekt.

Även om detta inte är nödvändigt, notera att du faktiskt kan ha huvudmenyalternativet och alternativ menyalternativet hänvisar till samma innehåll - uppdatera enkelt återuppringningen i ad_menu_page-funktionen till sandbox_options_display funktion som vi just definierat.

Pluginsidor

Om du utvecklar ett WordPress-plugin, finns det några olika sätt att din produkt kan kopplas till plattformen.

Specifikt, din plugin ...

Kan arbeta i bakgrunden och inte kräva en meny.
Kan använda antingen båda eller en av ovan nämnda funktioner för att skapa en anpassad meny
Kan inkludera sig i en av de befintliga WordPress-menyerna

För att underlätta för plugin-utvecklare att inkludera sina alternativ i befintliga WordPress-menyer erbjuder WordPress API följande funktion: add_plugins_page.

Men vänta. Om du har följt med exemplen ovan så har du antagligen märkt att det inte förekommer någon märkbar skillnad mellan add_plugins_page och add_submenu_page. Du har rätt. add_plugins_page har samma funktion som add_submenu_page, men det finns två primära skillnader:

Pluggen tillhandahålls speciellt för användning i plugin-utveckling.
Funktionen lägger till plugins menyalternativ direkt till WordPress ' plugins meny.

Även om du säkert kan använda add_submenu_page för att uppnå samma mål, är jag alltid en fan av att använda funktioner som är avsedda för ett specifikt användarfall även om det finns en annan API-funktion som gör detsamma. När du gör det visar du att du använder API: n som utvecklarna menade och du gör din kod lite mer sammanhängande eftersom din kodbas ligger mer i linje med hur den interagerar med kärnplattformen.

Pluginutveckling ligger utanför ramen för den här serien, men det är inte helt irrelevant. Även om det inte kommer några modifieringar i vårt Sandbox Theme, vill jag ge ett enkelt exempel som visar hur du använder den här funktionen.

Låt oss först granska argumenten som add_plugins_page accepterar:

Sidans titel är texten som kommer att visas i webbläsarens titel när pluginens optionssida görs.
Menyn Titel är texten som kommer att visas som pluginens menyalternativ i WordPress-menyn.
Förmåga som med föräldramenyn, hänvisar till vilka typer av användare som har tillgång till den här menyn.
Menyslak är den unika identifieraren för det här menyalternativet. Det är vad det brukade definiera denna meny inom ramen för WordPress.
Ring tillbaka är den funktion som används för att göra denna menys sida till skärmen.

Här är ett enkelt exempel som visar exakt hur du använder den. Observera att du kan inkludera detta i din functions.php-fil men det är inte en del av Sandbox Theme som vi arbetar på och ska användas i samband med ett plugin, istället.

Först ställer du upp samtalet till API-funktionen - märk att detta använder admin_menu-kroken:

funktion sandbox_example_plugin_menu () add_plugins_page ('Sandbox Plugin', // Titeln som ska visas i webbläsarfönstret för den här sidan. 'Sandbox Plugin', // Texten som ska visas för detta menyalternativ 'administrator', // Vilket typ av användare kan se detta menyalternativ 'sandbox_plugin_options', // Det unika ID-det vill säga sluget - för det här menyalternativet 'sandbox_plugin_display' // Namnet på funktionen som ska ringas när man gör sidan för denna meny);  // slut sandbox_example_plugin_menu add_action ('admin_menu', 'sandbox_example_plugin_menu');

Installera sedan den funktion som gör pluginens display:

funktion sandbox_plugin_display () // Skapa en rubrik i standardbehållaren WordPress 'wrap' $ html = ''; $ html. = 'Sandbox Plugin Alternativ
'; $ html. = 'Det finns för närvarande inga alternativ. Detta är bara för demo ändamål.
'; $ html. = '
'; // Skicka markeringen till webbläsaren echo $ html;  // slut sandbox_plugin_display

Uppdatera din WordPress Dashboard, sväva över plugins menyn och du bör märka ett nytt menyalternativ. Inte illa, va?

Den slutliga versionen av koden ska se ut så här:

/ ** * Den här funktionen introducerar ett menyalternativ för menyn i WordPress 'Plugins' * -menyn. * / funktion sandbox_example_plugin_menu () add_plugins_page ('Sandbox Plugin', // Titeln som ska visas i webbläsarfönstret för denna sida. 'Sandbox Plugin', // Texten som ska visas för detta menyalternativ 'administratör', / / Vilken typ av användare kan se detta menyalternativ 'sandbox_plugin_options', // Det unika ID-det vill säga sluget - för det här menyalternativet 'sandbox_plugin_display' // Namnet på funktionen som ska ringas när den gör sidan för den här menyn) ;  // end sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_plugin_menu'); / ** * Gör en enkel sida att visa för teman menyn definierad ovan. * / funktion sandbox_plugin_display () // Skapa en rubrik i standardbehållaren WordPress 'wrap' $ html = ''; $ html. = 'Sandbox Plugin Alternativ
'; $ html. = 'Det finns för närvarande inga alternativ. Detta är bara för demo ändamål.
'; $ html. = '
'; // Skicka markeringen till webbläsaren echo $ html;  // slut sandbox_plugin_display

Återigen kommer den här funktionen inte att vara en del av vårt Sandbox-tema eftersom det är inriktat mer på plugin-utveckling. Det är dock värt att täcka för dig som kommer att utnyttja inställnings API-programmet i din pluginutvecklingsinsats.

Tema Sidor

Precis som med plugins tillhandahåller WordPress en API-funktion för att införa menyer specifikt för teman. Det ligner mycket på plugin-menyn eftersom det ger ännu ett sätt att introducera en undermeny till befintliga menyer. Den främsta skillnaden är att undermenyn läggs till i Utseende meny.

Precis som med plugin-exemplet tidigare i den här artikeln tar vi en titt på hur vi kan använda den här funktionen men vi kommer inte att inkludera den i vårt Sandbox-tema. Det här är endast avsett att visa hur man använder funktionen om du väljer att gå denna rutt i ditt personliga arbete.

Först ska vi granska de argument som add_theme_page accepterar. Du märker att de är precis som de som krävs för pluginmenyn och mycket liknar de undermenyfunktioner som vi skisserade tidigare:

add_theme_page accepterar följande argument:

Sidans titel är texten som kommer att visas i webbläsarens titel när temas optionssida görs.
Menyn Titel är texten som kommer att visas som temat menyalternativ i WordPress-menyn.
Förmåga som med föräldramenyn, hänvisar till vilka typer av användare som har tillgång till den här menyn.
Menyslak är den unika identifieraren för det här menyalternativet. Det är vad det brukade definiera denna meny inom ramen för WordPress.
Ring tillbaka är den funktion som används för att göra denna menys sida till skärmen.

Som med de andra funktionerna skapar vi ett par exempelfunktioner som visar hur det ingår i ditt projekt. Observera att samtalet till add_theme_page kan läggas till funktioner.php och, till skillnad från samtalen till add_plugin_page, skall bor här när du utvecklar ditt tema.

Först uppmaningen att ställa in menyalternativet:

funktion sandbox_example_theme_menu () add_theme_page ('Sandbox Theme', // Titeln som ska visas i webbläsarfönstret för den här sidan. 'Sandbox Theme', // Texten som ska visas för det här menyalternativet 'administrator', // Which typ av användare kan se detta menyalternativ 'sandbox_theme_options', // Det unika ID-det vill säga sluget - för det här menyalternativet 'sandbox_theme_display' // Namnet på funktionen som ska ringas när den gör sidan för den här menyn);  // slut sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu');

Därefter installerar vi en funktion för att göra alternativsidan:

funktion sandbox_theme_display () // Skapa en rubrik i standardbehållaren WordPress 'wrap' $ html = ''; $ html. = 'Tandalternativ för sandlåda
'; $ html. = 'Det finns för närvarande inga alternativ. Detta är bara för demo ändamål.
'; $ html. = '
'; // Skicka markeringen till webbläsaren echo $ html;  // slut sandbox_theme_display

Uppdatera nu WordPress Dashboard, sväva över Utseende menyn och du bör se ditt nya menyalternativ. Enkel!

Den slutliga versionen av koden ska se ut så här:

/ ** * Den här funktionen introducerar ett menyalternativ för menyn i WordPress "Utseende" * -menyn. * / funktion sandbox_example_theme_menu () add_theme_page ('Sandbox Theme', // Titeln som ska visas i webbläsarfönstret för den här sidan. 'Sandbox Theme', // Texten som ska visas för detta menyalternativ 'administratör', / / Vilken typ av användare kan se detta menyalternativ 'sandbox_theme_options', // Det unika ID-det vill säga sluget - för det här menyalternativet 'sandbox_theme_display' // Namnet på funktionen som ska ringas när man gör sidan för den här menyn) ;  // slut sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu'); / ** * Gör en enkel sida att visa för teman menyn definierad ovan. * / funktion sandbox_theme_display () // Skapa en rubrik i standardbehållaren WordPress 'wrap' $ html = ''; $ html. = 'Tandalternativ för sandlåda
'; $ html. = 'Det finns för närvarande inga alternativ. Detta är bara för demo ändamål.
'; $ html. = '
'; // Skicka markeringen till webbläsaren echo $ html;  // slut sandbox_theme_display

För de av er som är intresserade av att göra mer avancerad temautveckling har du troligt övervägt de olika sätten att implementera flera alternativsidor för ditt tema.

Å ena sidan kan vi lägga till flera undermenyer till en översta menyn, men där är ett alternativ: fliknavigering. Det här låter bra när du vill presentera alternativ till Utseende menyn och lägg inte till ännu ett menyalternativ på WordPress Dashboard. Vi kommer att diskutera detta mer ingående i nästa artikel.

När ska du använda varje funktion

Vi har tittat på var och en av de fyra viktigaste sätten att introducera våra egna sidor till WordPress. Även om dessa funktioner inte är specifikt del av Inställnings API, är det viktigt att diskutera eftersom de fungerar så nära i samband med det.

Men att veta dessa funktioner är bara hälften av det. Som utvecklare ansvarig för integration och organisering av inställningar är det viktigt att veta när man ska använda var och en av de olika funktionerna i sitt ordinarie sammanhang.

Även om det inte finns något silver bullet svar för när du ska använda varje funktion, här är några riktlinjer att överväga när du arbetar med dina anpassade funktioner, plugins och / eller tema:

Menyn på toppnivå kan läggas till när det finns en undermeny som kan grupperas logiskt med dessa alternativ. Detta gör att du har en viktig samling inställningar som inte logiskt passar in i någon av de befintliga WordPress-menyerna.
menyer~~POS=HEADCOMP hör alltid till en översta menyn - antingen anpassad eller existerande. De ska alltid grupperas under den översta menyn som är mest logisk. Om WordPress erbjuder en meny som kan fungera som förälder för din undermeny, använder du den; Förorena inte menyn med en överflödig menynivå.
Plugin Menyer ska användas när du har enkla alternativ på en sida för din plugin. Om du har flera alternativsidor kan du överväga att skapa en översta menyn eller överväga att använda flikarnavigering som vi kommer att undersöka i nästa artikel.
Tema Menyer bör användas när du utvecklar ditt eget tema som erbjuder sin egen uppsättning anpassade alternativ. Om alternativen kan leva på en enda sida, överväg att använda WordPress 'API-funktion. Om du har fler alternativ, överväg att använda fliknavigering. Observera att många temautvecklare ofta höjer tematillvalen till toppmenyn och det är okej också.

Ett ord om anpassade menyer: Även om WordPress ger oss möjligheten att lägga till egna menyer på toppnivå, lägg till någon befintlig meny och ger oss i allmänhet möjligheten att göra vad vi vill ha med standardkonfigurationen, delar en del av samhället det här. De tror att anpassad funktionalitet inte skulle störa vissa kärnmenyer. Även om det i slutänden är upp till dig, implementera ditt arbete med skönhet - oddsen är att få saker du gör är viktigare än WordPress-kärnfunktionalitet, så lägg inte ditt arbete ovanför det.

Vad är nästa??

I nästa artikel kommer vi att tillämpa lite av vad vi har lärt oss om menyer och börja introducera alternativsidor för vårt Sandbox-tema.

Förutom att lägga till menysidor tar vi också en titt på fliknavigering och hur vi kan implementera det för att fungera tillsammans med våra egna menysidor.

Under tiden granska tidigare artiklar i den här serien och glöm inte att kolla den nuvarande versionen av WordPress Settings Sandbox på GitHub.

Relaterade resurser

Vi täckte en hel del resurser i den här artikeln. Här är en sammanfattning av allt vi använde:

add_menu_page
add_submenu_page
add_plugins_page
add_theme_page
WordPress Settings Sandbox

Koda