WordPress Settings API, Del 6 Menysidor

I del 3 i denna serie undersökte vi de olika menyfunktioner som WordPress API tillhandahåller. Om du har följt med, vet du att vi redan har ställt in en inställningssida för vårt tema genom att använda add_theme_page fungera. Även om introduktion av menyer och undermenyer inte är explicit del av inställnings API, spelar de en roll vid att skapa anpassad funktionalitet, plugins och / eller teman.

I den här artikeln kommer vi att introducera en ny meny till WordPress-instrumentpanelen som gör att våra tematillbehör finns tillgängliga på annat håll än bara under alternativen "Utseende".

Innan vi börjar: I den här artikeln förutsätter du att du är bekant med inställnings API och temaalternativ. Om du är en nybörjare eller till och med mellan WordPress-utvecklare rekommenderar jag starkt att fånga upp resten av serien innan du dyker in i det här inlägget.

En titt på API: n

Eftersom vi redan har tittat på var och en av menyfunktionerna behöver vi inte omhysa alla funktioner som WordPress har tillgängligt. Istället tar vi en titt på de som vi ska använda och arbetar sedan genom ett praktiskt exempel på hur man använder dem i vårt eget arbete.

Innan vi tittar på varje funktion, låt oss detaljera vad vi planerar att åstadkomma i nästa fas i serien:

Introducera en översta menyn för våra tematillval
Lägg till ett undermenyobjekt som länkar till fliken "Visa alternativ"
Lägg till ett undermenyobjekt som länkar till fliken Sociala alternativ

Relativt enkelt, eller hur? För att göra detta kommer vi att utnyttja följande två funktioner:

add_menu_page som används för att introducera menyalternativ på toppnivå
add_submenu_page som används för att introducera undermenyobjekt till översta menyn.

Vi tar en titt på varje funktionens parametrar och användning när vi implementerar dem i vårt tema.

Observera att resten av den här artikeln bygger på den här versionen av WordPress Settings Sandbox. Om du följer med förvaret, se till att du kolla in det.

Menyn på toppnivå

Det första som vi vill göra är att introducera en översta menyn. Denna meny kommer att visas direkt under menyn "Inställningar" i WordPress instrumentpanel och kommer att tjäna två syften. Menyn ska:

Exponera temat alternativ till WordPress instrumentpanel
Visa en standardalternativssida för temainställningarna

Funktionen tar följande sju argument, de första fem krävs, de två sista är inte:

sidans titel är texten som kommer att göras i webbläsarens titellinje
menu_title är texten som kommer att visas för menyalternativet
förmåga Den roll som användaren måste ha för att komma åt den här menyn
menu_slug är ett unikt värde som identifierar den här menyn. Det är också hur undermenyer registrerar sig med den här menyn.
function_name det kallas när menyn klickas för att visa alternativsidan.
icon_url är sökvägen till ikonen som du vill visa bredvid menyalternativet.
placera är där menyn ska läggas till i förhållande till de andra menyerna i WordPress Dashboard.

I vårt arbete kommer vi att fokusera endast på de fem första parametrarna. Jag diskuterar menypositionering i slutet av denna artikel.

För att komma igång måste vi införa ett samtal till add_menu_page fungera. Enligt WordPress Codex kan administrationsmenyer läggas till med hjälp av admin_menu krok. Tidigare i den här serien skrev vi en funktion som lägger till våra temainställningar på menyn "Utseende". Specifikt skrev vi sandbox_example_theme_menu:

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' // Namn på funktionen som ska ringas när den här sidan visas)  // slut sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu');

Observera i koden ovan att denna funktion var registrerad hos admin_menu krok också. Du bör alltid sträva efter att hålla dina funktioner logiskt konsekventa. Eftersom vi redan har en funktion som registrerar en meny, är den registrerad med lämplig krok, och eftersom vi introducerar liknande funktioner lägger vi till våra nya menyfunktioner till denna funktion.

Lägg till följande samtal till add_menu_page direkt under samtalet ovan:

add_menu_page ('Sandbox Theme', // Det värde som används för att fylla i webbläsarens titelfält när menysidan är aktiv 'Sandbox Theme', // Menyns text i administratörens sidofält 'administrator', // Vilka roller kan för att komma till menyn "sandbox_theme_menu", // Det ID som användes för att binda undermenyalternativ till den här menyn 'sandbox_theme_display' // Återuppringningsfunktionen som används för att göra denna meny);

Som du kan se registrerar vi en meny som visar "Sandbox Theme" både i webbläsarens titellinje och i menyalternativet. Vi exponerar menyn bara för administratörer och vi har gett menyn det unika ID-numret för "sandbox_theme_parent_menu". Vi kommer att återanvända denna parameter i nästa avsnitt.

Det finns en viktig sak som vi behöver förtydliga: Observera att vi har passerat "sandbox_theme_display'som funktion som ska ringas när detta menyalternativ klickas. Minns att i del 3 introducerade vi denna funktion (och vi förfinade den i del 5). Specifikt är det ansvaret för att göra vår sida för flikar på teman.

Genom att skicka detta befintliga funktionsnamn till add_menu_page funktion, utnyttjar vi kod som vi redan har skrivit och vi gör en standardalternativssida för menyalternativet.

Vid den här tiden är vi redo att börja lägga till undermenyer, men innan du går framåt, se till att din funktion ser ut så här:

funktion 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");  // slut sandbox_example_theme_menu

Lägg till undermenyerna

Undermenyer ligner mycket menyer förutom att de "hör till" en befintlig meny. API för att registrera undermenyer är också relativt likartat. Funktionen accepterar sex argument, den första fem krävs, den sista är valfri:

parent_slug hänvisar till det unika ID-numret för det överordnade menyobjektet. I vårat fall, "sandbox_theme_menu".
sidans titel är texten som ska visas i webbläsarens verktygsfält när denna undermenyobjekt är aktiv
menu_title är texten för den här aktuella undermenyobjektet på instrumentpanelen
förmåga är den roll som en användare måste ha åtkomst till det här menyobjektet
menu_slug är det unika ID-numret för det här menyalternativet
function_name det kallas när menyn klickas för att visa alternativsidan

Funktionen är enkel. Vi har två menyalternativ att introducera - en för "Display Options" och en för "Social Options."

Skärmalternativ

Låt oss först introducera en undermenyobjekt för visningsalternativ. Lägg till följande kodkod direkt under add_menu_page ring som vi definierade ovan:

add_submenu_page ('sandbox_theme_menu', // ID-menyn på den översta menysidan som denna undermenyobjekt tillhör 'Display Options', // Det värde som används för att fylla i webbläsarens titelfält när menysidan är aktiv 'Skärmalternativ' // Märken på denna undermenyobjekt som visas i menyn 'administrator', // Vilka roller kan komma åt det här undermenyobjektet 'sandbox_theme_display_options', // Det ID som används för att representera detta undermenyobjekt 'sandbox_theme_display' // Den återupptagna funktionen som används för att göra alternativen för denna undermenyobjekt);

Var och en av parametrarna ovan bör vara tydliga med undantag för det funktionsnamn som vi passerade som sista argumentet. Observera att det är samma funktionsnamn som vi angav i add_menu_page ring upp. Men det här är vettigt, eller hur? Visningsalternativen är trots allt standardfliken som visas när tematillvalen är valda så det skulle vara meningsfullt att det ska visas när toppmenyn är vald och när menyalternativet "Bildalternativ" är valt.

På den här tiden finns det ett viktigt inslag i WordPress att markera: Observera att när du har lagt till ditt första undermenyobjekt, kommer WordPress faktiskt att göra två undermenyalternativ till toppmenyn - ett objekt som duplicerar funktionen på toppnivån meny och ett objekt som motsvarar det undermenyobjekt som du just definierat. Jag tar upp detta eftersom jag enligt min erfarenhet sett utvecklare blir förvirrad över hur (och varför) det händer. Kort sagt är det att WordPress gör det här - det är inget fel med din kod.

Sociala alternativ

Att lägga till ett menyalternativ för de sociala alternativen är nästan precis som att lägga till ett menyalternativ för visningsalternativen. Självklart vill vi bara ändra värdena för titelfältet, menyalternativet och den sida som visas när menyn är vald. Låt oss först lägga upp vårt samtal till add_submenu_page fungera. Det ska se ut så här:

add_submenu_page ("sandbox_theme", "Sociala alternativ", "Sociala alternativ", "administratör", "sandbox_theme_social_options", "sandbox_theme_display");

Spara koden, uppdatera din instrumentpanel, och du bör se menyalternativet "Sociala alternativ" nu tillgängligt under menyn "Sandbox Theme" observera dock att klickar du på det nya undermenyobjektet endast "Displayalternativen". Eftersom vi har passerat "sandbox_theme_display"som funktionsnamn, det är vad vi borde förvänta oss, rätt? Så nu står vi inför en liten utmaning: Hur väljer vi fliken" Sociala alternativ "när man klickar på undermenyobjektet?

Refactoring Vår flikfunktionalitet

Det finns ett par olika alternativ som vi har för att binda det nya undermenyobjektet till den korrekta fliken på temanalternativens sida:

Vi kan definiera en ny funktion som ger de sociala alternativen. Detta skulle kräva att vi gör ytterligare arbete för att introducera en ny funktion, skapa tabbingfunktionalitet så att vi inte bryter upp erfarenheten av den befintliga sidan och duplicerar lite kod.
Vi kan refactor den befintliga sandbox_theme_display funktion för att acceptera en valfri parameter och använd sedan en anonym funktion i add_submenu_page ring för att skicka en parameter till den.

I slutändan är något av dessa alternativ till dig; men jag vill hellre refactor min befintliga funktion än dubbla kod så det är vad jag ska göra under resten av denna artikel.

Först låt oss börja refactoring vår sandbox_theme_display fungera. Låt oss acceptera ett valfritt argument som ska användas för att ange vilken flik vi vill välja. Leta reda på följande signatur i din functions.php fil:

funktion sandbox_theme_display () / * Konsolideras för denna del av artikeln. * / // avsluta sandbox_theme_display

Uppdatera signaturen så att den accepterar ett enda argument och ställer in det till null när det inte är definierat:

funktion sandbox_theme_display ($ active_tab = null) / * Konsolideras för denna del av artikeln. * / // avsluta sandbox_theme_display

Om du är ny i PHP kan du läsa om standardargument på den här sidan.

Kom ihåg från den sista artikeln att vår visningsfunktion faktiskt letar efter ett söksträngsvärde som ska ställas in. Vi vill ändå behålla den funktionen, men vi måste också redogöra för att parametern kan överföras till funktionen. För att utföra denna refactoring, först hitta följande kodrad i sandbox_theme_display fungera:

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

Observera att den här specifika koden endast berör frågesträngsparametrarna. För att kunna redogöra för den nya valfria parametern måste vi introducera logik som först kontrollerar om söksträngsparametern är markerad, om inte, kommer den att kontrollera om funktionens argument är inställt för att visa de sociala alternativen, och om inte, då det kommer som standard till visningsalternativen. Ersätt koden ovan med följande villkor:

om (isset ($ _GET ['flik'])) $ active_tab = $ _GET ['flik'];  annars om ($ active_tab == 'social_options') $ active_tab = 'social_options';  else $ active_tab = 'display_options';  // slut om / annat

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

funktion sandbox_theme_display ($ active_tab = ") ?>

Tandalternativ för sandlåda

"> Visa alternativ"> Sociala alternativ

Vi är inte helt färdiga än. Även om vi har gjort det nödvändiga arbetet för att visa de sociala alternativen om rätt parameter har passerat, har vi inte faktiskt ringt funktionen med en parameter. För att göra detta måste vi refaktorera add_submenu_page funktionen ovanifrån. För närvarande ser funktionsanropet ut så här:

add_submenu_page ("sandbox_theme", "Sociala alternativ", "Sociala alternativ", "administratör", "sandbox_theme_social_options", "sandbox_theme_display");

Vi behöver uppdatera den sista parametern så att den kallar visningsfunktionen och skickar rätt värde för att göra de sociala alternativen. För att göra det skapar vi en anonym funktion:

add_submenu_page ("sandbox_theme_menu", "Sociala alternativ", "Sociala alternativ", "administratör", "sandbox_theme_social_options", create_function (null, "sandbox_theme_display (" social_options ");

Om du är ny i PHP, var noga med att läsa på create_function funktion och anonyma funktioner. Även om de ligger utanför ramen för denna artikel kan de vara kraftfulla (och användbara!) När de används i rätt sammanhang.

Den slutliga versionen av sandbox_example_theme_menu funktionen ska vara enligt följande:

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' // Namn på funktionen som ska ringas när den här sidan visas) add_menu_page ('Sandbox Theme', // Det värde som används för att fylla i webbläsarens titelfält när menysidan är aktiv 'Sandbox Theme', // Menyns text i administratörens sidofält 'administrator', // Vilka roller kan för att komma till menyn "sandbox_theme_menu", // Det ID som användes för att binda undermenyalternativ till den här menyn 'sandbox_theme_display' // Återuppringningsfunktionen som används för att göra denna meny); add_submenu_page ('sandbox_theme_menu', // ID-menyn på den översta menysidan som denna undermenyobjekt tillhör 'Display Options', // Det värde som används för att fylla i webbläsarens titelfält när menysidan är aktiv 'Skärmalternativ' // Märken på denna undermenyobjekt som visas i menyn 'administrator', // Vilka roller kan komma åt det här undermenyobjektet 'sandbox_theme_display_options', // Det ID som används för att representera detta undermenyobjekt 'sandbox_theme_display' // Den återupptagna funktionen som används för att göra alternativen för denna undermenyobjekt); add_submenu_page ("sandbox_theme_menu", "Sociala alternativ", "Sociala alternativ", "administratör", "sandbox_theme_social_options", create_function (null, "sandbox_theme_display (" social_options ");  // slut sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu');

Slutsats

Vid detta tillfälle har vårt tema nu ett eget menyalternativ på toppnivå med alla inställningsflikarna tillgängliga via undermenyobjekt. Även om detta är användbart anser jag att det är viktigt att notera att det finns några blandade åsikter om att införa menyer i WordPress Dashboard. Även om de kan göra ditt arbete mer framträdande och tillgängligt, kan de också störa befintliga WordPress-menyer eller annat arbete från tredje part. speciellt om du försöker placera menyerna någonstans med positionsparametern. Även om det inte finns något absolut rätt eller absolut fel när det gäller att införa menyer, tänk noga på var du exponerar menyerna. Om en befintlig WordPress-meny är meningsfull, registrera ditt arbete som en undermeny.

I nästa inlägg börjar vi ta en titt på de olika inmatningselementen som vi kan använda för att presentera alternativ i vårt WordPress-tema, samt hur man validerar och sanerar data innan serialisering av dem.

Relaterade källor

add_menu_page
add_submenu_page
create_function
anonyma funktioner
WordPress Settings Sandbox 0.5

Koda