De WordPress Settings API, deel 6 menupagina's

In deel 3 van deze serie hebben we de verschillende menufuncties bekeken die de WordPress API biedt. Als je meegekeken hebt, weet je dat we al een instellingenpagina voor ons thema hebben ingesteld met behulp van de add_theme_page functie. Hoewel de introductie van menu's en submenu's niet expliciet deel uitmaken van de Settings API, spelen ze een rol bij het bouwen van aangepaste functionaliteit, plug-ins en / of thema's.

In dit artikel gaan we een nieuw menu introduceren in het WordPress-dashboard dat onze thema-opties elders beschikbaar maakt, anders dan alleen onder de opties "Uiterlijk".

Voordat we beginnen: In dit artikel wordt ervan uitgegaan dat u bekend bent met de instellingen-API en de thema-opties. Als je een beginner of zelfs een tussentijdse WordPress-ontwikkelaar bent, raad ik je ten zeerste aan de rest van de serie in te halen voordat je in deze post duikt.

Een blik op de API

Omdat we al naar de menu-functies hebben gekeken, hoeven we niet alle functies opnieuw in te schakelen die WordPress beschikbaar heeft. In plaats daarvan gaan we die bekijken die we gaan gebruiken en vervolgens een praktisch voorbeeld van hoe we ze in ons eigen werk kunnen gebruiken..

Voordat we naar elke functie kijken, laten we eerst zien wat we van plan zijn te bereiken in de volgende fase van deze reeks:

Introduceer een hoofdmenu voor onze thema-opties
Voeg een submenu-item toe dat zal linken naar het tabblad "Weergaveopties"
Voeg een submenu-item toe dat zal linken naar het tabblad "Sociale opties"

Relatief eenvoudig, toch? Om dit te doen, zullen we profiteren van de volgende twee functies:

add_menu_page die wordt gebruikt voor het invoeren van menu-items op het hoogste niveau
add_submenu_page die wordt gebruikt om submenu-items te introduceren in hoofdmenu's.

We zullen de parameters en het gebruik van elke functie bekijken terwijl we ze in ons thema implementeren.

Merk op dat de rest van dit artikel voortbouwt op deze versie van de WordPress Settings Sandbox. Als je de repository volgt, zorg er dan voor dat je het bekijkt.

Het hoofdmenu

Het eerste dat we willen doen is een menu op het hoogste niveau introduceren. Dit menu verschijnt direct onder het menu "Instellingen" in het WordPress-dashboard en zal twee doelen dienen. Het menu zou:

Exposeer de opties van het thema op het WordPress-dashboard
Geef een standaardoptiepagina weer voor de thema-opties

De functie neemt de volgende zeven argumenten, de eerste vijf zijn vereist, de laatste twee zijn niet:

pagina titel is de tekst die in de titelbalk van de browser wordt weergegeven
menu_title is de tekst die voor het menu-item wordt weergegeven
geschiktheid verwijst naar de rol die de gebruiker moet hebben om toegang te krijgen tot dit menu
menu_slug is een unieke waarde die dit menu identificeert. Het is ook hoe submenu's zichzelf registreren bij dit menu.
FUNCTION_NAME die wordt opgeroepen wanneer op het menu wordt geklikt voor het weergeven van de optiepagina.
icon_url is het pad naar het pictogram dat u naast uw menu-item wilt weergeven.
positie is waar het menu moet worden toegevoegd in relatie tot de andere menu's in het WordPress Dashboard.

In ons werk concentreren we ons alleen op de eerste vijf parameters. Ik bespreek de menu-positionering in de conclusie van dit artikel.

Om aan de slag te kunnen gaan, moeten we een telefoontje naar de add_menu_page functie. Volgens de WordPress Codex kunnen beheermenu's worden toegevoegd met behulp van de ADMIN_MENU haak. Eerder in deze serie schreven we een functie die onze thema-opties toevoegt aan het menu "Uiterlijk". In het bijzonder schreven we sandbox_example_theme_menu:

function sandbox_example_theme_menu () add_theme_page ('Sandbox Theme', // De titel die moet worden weergegeven in het browservenster voor deze pagina. 'Sandbox Theme', // De tekst die moet worden weergegeven voor dit menu-item 'beheerder', // Welke type gebruikers kunnen dit menu-item 'sandbox_theme_options', // De unieke ID - dat wil zeggen de slug - zien voor dit menu-item 'sandbox_theme_display' // De naam van de functie die moet worden aangeroepen bij het renderen van de pagina van dit menu);  // einde sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu');

Noteer in de bovenstaande code dat deze functie is geregistreerd bij de ADMIN_MENU haak, ook. U moet er altijd naar streven om uw functies logisch consistent te houden. Omdat we al een functie hebben die een menu registreert, die geregistreerd is met de juiste hook, en omdat we soortgelijke functionaliteit introduceren, zullen we onze nieuwe menufuncties aan deze functie toevoegen.

Voeg de volgende oproep toe aan add_menu_page direct onder de bovenstaande oproep:

add_menu_page ('Sandbox Theme', // De waarde die wordt gebruikt om de titelbalk van de browser te vullen wanneer de menupagina actief is 'Sandbox Theme', // De tekst van het menu in de beheerderszijbalk 'administrator', // Welke rollen zijn in staat om toegang te krijgen tot het menu 'sandbox_theme_menu', // De ID die wordt gebruikt om submenu-items aan dit menu te binden 'sandbox_theme_display' // De callback-functie die wordt gebruikt om dit menu weer te geven);

Zoals je kunt zien, registreren we een menu dat 'Sandbox-thema' weergeeft in zowel de titelbalk van de browser als in het menu-item. We stellen het menu alleen bloot aan beheerders en we hebben het menu het unieke ID van "sandbox_theme_parent_menu". We zullen deze parameter opnieuw gebruiken in de volgende sectie.

Er is één belangrijk ding dat we moeten verduidelijken: merk op dat we zijn geslaagd 'sandbox_theme_display'als de functie die moet worden opgeroepen wanneer op dit menu-item wordt geklikt. Bedenk dat we in Deel 3 deze functie hebben geïntroduceerd (en we hebben het in Deel 5 verfijnd). Het is met name verantwoordelijk voor het weergeven van onze pagina met tabbladen met thema-opties.

Door deze bestaande functienaam door te geven aan de add_menu_page functie gebruiken we de code die we al hebben geschreven en maken we een standaardoptiepagina voor het menu-item.

Op dit moment zijn we klaar om submenu's toe te voegen, maar voordat u verdergaat, moet u ervoor zorgen dat uw functie er precies zo uitziet:

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');  // einde sandbox_voorbeeld_thema_menu

Voeg de submenu's toe

Submenu's lijken veel op menu's behalve dat ze "thuishoren" bij een bestaand menu. De API voor het registreren van submenu's is ook relatief vergelijkbaar. De functie accepteert zes argumenten, waarbij de eerste vijf vereist zijn, de laatste is optioneel:

parent_slug verwijst naar de unieke ID van het bovenliggende menu-item. In ons geval, "sandbox_theme_menu".
pagina titel is de tekst die moet worden weergegeven in de werkbalk van de browser wanneer dit submenu-item actief is
menu_title is de tekst voor dit actuele submenu-item in het dashboard
geschiktheid is de rol die een gebruiker moet hebben om toegang te krijgen tot dit menu-item
menu_slug is de unieke ID voor dit specifieke menu-item
FUNCTION_NAME die wordt opgeroepen wanneer op het menu wordt geklikt om de optiepagina weer te geven

De functie is eenvoudig. We hebben twee menu-items om te introduceren: een voor 'Weergaveopties' en een voor 'Sociale opties'.

Weergaveopties

Laten we eerst een submenu-item introduceren voor weergave-opties. Voeg het volgende blok code direct onder de add_menu_page oproep die we hierboven hebben gedefinieerd:

add_submenu_page ('sandbox_theme_menu', // De ID van de menupagina op het hoogste niveau waartoe dit submenu behoort 'Weergaveopties', // De waarde die wordt gebruikt om de titelbalk van de browser te vullen wanneer de menupagina actief is 'Weergaveopties', // Het label van dit submenu-item dat wordt weergegeven in het menu 'beheerder', // Welke rollen kunnen dit submenu-item openen 'sandbox_theme_display_options', // De id die wordt gebruikt om dit submenu-item 'sandbox_theme_display' weer te geven // De callback-functie die wordt gebruikt om de opties voor dit submenu-item weer te geven);

Elk van de bovenstaande parameters moet duidelijk zijn, met uitzondering van de functienaam die we hebben aangenomen als het laatste argument. Merk op dat het dezelfde functienaam is die we in de add_menu_page noemen. Maar dit is logisch, toch? De "Weergaveopties" is immers het standaardtabblad dat wordt weergegeven wanneer de thema-opties worden geselecteerd, dus het zou logisch zijn dat het zou worden weergegeven wanneer het hoofdmenu wordt geselecteerd en wanneer het menu-item "Weergaveopties" is geselecteerd.

Op dit punt is er een belangrijk kenmerk van WordPress om te benadrukken: Merk op dat wanneer je je eerste submenu-item hebt toegevoegd, WordPress twee submenu-items daadwerkelijk rendert naar het hoofdmenu - één item dat de functie van het hoofdniveau dupliceert menu en een item dat overeenkomt met het item in het submenu dat u zojuist hebt gedefinieerd. Ik breng dit naar voren, omdat ik in mijn ervaring gezien heb dat ontwikkelaars in de war raken over hoe (en waarom) dit gebeurt. Het kort is dat WordPress dit doet - het is niets mis met je code.

Sociale opties

Het toevoegen van een menu-item voor de sociale opties is bijna precies hetzelfde als het toevoegen van een menu-item voor de weergave-opties. Natuurlijk willen we alleen de waarden voor de titelbalk, het menu-item en de pagina die wordt weergegeven wanneer het menu wordt geselecteerd. Laten we eerst onze oproep instellen voor de add_submenu_page functie. Het zou er zo uit moeten zien:

add_submenu_page ('sandbox_theme', 'Social Options', 'Social Options', 'administrator', 'sandbox_theme_social_options', 'sandbox_theme_display');

Sla uw code op, vernieuw uw dashboard en u zou het menu-item "Sociale opties" nu beschikbaar moeten zijn in het menu "Sandbox-thema"; Merk echter op dat klikken op het nieuwe submenu-item alleen de "Weergaveopties" oplevert. Omdat we de "sandbox_theme_display"als de functienaam, dat is wat we zouden moeten verwachten, toch? Dus nu staan we voor een kleine uitdaging: hoe selecteren we het tabblad" Sociale opties "wanneer we op het submenu-item klikken??

Refactoring van onze tab-functionaliteit

Er zijn een aantal verschillende opties die we hebben om het nieuwe submenu-item aan het juiste tabblad op de pagina met thema-opties te koppelen:

We kunnen een nieuwe functie definiëren die de sociale opties weergeeft. Dit vereist dat we wat extra werk doen bij de introductie van een nieuwe functie, tabfunctionaliteit instellen, zodat we de ervaring van de bestaande pagina niet doorbreken en een klein beetje code dupliceren.
We kunnen het bestaande refactoren sandbox_theme_display functie om een optionele parameter te accepteren en gebruik vervolgens een anonieme functie in de add_submenu_page om een parameter door te geven.

Uiteindelijk is een van deze opties aan jou; echter, ik zou liever mijn bestaande functie dan duplicate code refactoren, dus dat is wat ik zal doen in de rest van dit artikel.

Laten we beginnen met het refactoren van onze sandbox_theme_display functie. Laten we een optioneel argument accepteren dat zal worden gebruikt om aan te geven welk tabblad we willen selecteren. Zoek de volgende handtekening in uw functions.php het dossier:

function sandbox_theme_display () / * Geconsolideerd voor dit deel van het artikel. * / // einde sandbox_theme_display

Werk de handtekening bij zodat deze een enkel argument accepteert en deze op nul zet wanneer deze niet is gedefinieerd:

function sandbox_theme_display ($ active_tab = null) / * Geconsolideerd voor dit deel van het artikel. * / // einde sandbox_theme_display

Als je nieuw bent bij PHP, kun je lezen over standaardargumenten op deze pagina.

Onthoud uit het laatste artikel dat onze weergavefunctie eigenlijk op zoek is naar een queryreekswaarde die moet worden ingesteld. We willen die functionaliteit nog steeds behouden, maar we moeten er rekening mee houden dat de parameter ook in de functie kan worden ingevoerd. Om deze refactoring uit te voeren, zoekt u eerst de volgende regel code in de sandbox_theme_display functie:

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

Merk op dat deze specifieke coderegel alleen betrekking heeft op de parameters van de vraagstring. Om rekening te houden met de nieuwe optionele parameter, moeten we een logica introduceren die eerst controleert of de queryparameter voor de query is aangevinkt. Als dit niet het geval is, wordt gecontroleerd of het argument van de functie is ingesteld om de sociale opties weer te geven en zo niet, dan het zal standaard de weergave-opties gebruiken. Vervang de bovenstaande regel code door de volgende voorwaardelijke:

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

De definitieve versie van de functie zou er als volgt uit moeten zien:

function sandbox_theme_display ($ active_tab = ") ?>

Sandbox-thema-opties

"> Weergaveopties"> Sociale opties

We zijn nog niet helemaal klaar. Hoewel we het nodige werk hebben gedaan om de sociale opties weer te geven als de juiste parameter is doorgegeven, hebben we de functie eigenlijk niet gebeld met behulp van een parameter. Om dit te doen, moeten we het add_submenu_page functie van boven. Momenteel ziet de functieaanroep er als volgt uit:

add_submenu_page ('sandbox_theme', 'Social Options', 'Social Options', 'administrator', 'sandbox_theme_social_options', 'sandbox_theme_display');

We moeten de laatste parameter bijwerken zodat deze de weergavefunctie oproept en de juiste waarde doorgeeft voor het weergeven van de sociale opties. Om dat te doen, zullen we een anonieme functie aanmaken:

add_submenu_page ('sandbox_theme_menu', 'Social Options', 'Social Options', 'administrator', 'sandbox_theme_social_options', create_function (null, 'sandbox_theme_display ("social_options");'));

Als je nog niet bekend bent met PHP, lees dan eerst de create_function functie en anonieme functies. Hoewel ze buiten het bestek van dit artikel vallen, kunnen ze krachtig (en nuttig!) Zijn wanneer ze in de juiste context worden gebruikt.

De definitieve versie van de sandbox_example_theme_menu functie moet als volgt zijn:

function sandbox_example_theme_menu () add_theme_page ('Sandbox Theme', // De titel die moet worden weergegeven in het browservenster voor deze pagina. 'Sandbox Theme', // De tekst die moet worden weergegeven voor dit menu-item 'beheerder', // Welke type gebruikers kunnen dit menu-item 'sandbox_theme_options', // De unieke ID - dat wil zeggen de slug - zien voor dit menu-item 'sandbox_theme_display' // De naam van de functie die moet worden aangeroepen bij het renderen van de pagina van dit menu); add_menu_page ('Sandbox Theme', // De waarde die wordt gebruikt om de titelbalk van de browser te vullen wanneer de menupagina actief is 'Sandbox Theme', // De tekst van het menu in de beheerderszijbalk 'administrator', // Welke rollen zijn in staat om toegang te krijgen tot het menu 'sandbox_theme_menu', // De ID die wordt gebruikt om submenu-items aan dit menu te binden 'sandbox_theme_display' // De callback-functie die wordt gebruikt om dit menu weer te geven); add_submenu_page ('sandbox_theme_menu', // De ID van de menupagina op het hoogste niveau waartoe dit submenu behoort 'Weergaveopties', // De waarde die wordt gebruikt om de titelbalk van de browser te vullen wanneer de menupagina actief is 'Weergaveopties', // Het label van dit submenu-item dat wordt weergegeven in het menu 'beheerder', // Welke rollen kunnen dit submenu-item openen 'sandbox_theme_display_options', // De id die wordt gebruikt om dit submenu-item 'sandbox_theme_display' weer te geven // De callback-functie die wordt gebruikt om de opties voor dit submenu-item weer te geven); add_submenu_page ('sandbox_theme_menu', 'Social Options', 'Social Options', 'administrator', 'sandbox_theme_social_options', create_function (null, 'sandbox_theme_display ("social_options");'));  // einde sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu');

Conclusie

Op dit moment heeft ons thema nu een eigen menu-item op het hoogste niveau, waarbij elk tabblad met instellingen toegankelijk is via submenu-items. Hoewel dit nuttig is, vind ik het belangrijk om op te merken dat er een aantal gemixte meningen zijn over het introduceren van menu's in het WordPress Dashboard. Hoewel ze uw werk prominenter en toegankelijker kunnen maken, kunnen ze ook interfereren met bestaande WordPress-menu's of ander werk van derden vooral als u probeert uw menu's ergens te plaatsen met behulp van de positieparameter. Hoewel er geen absolute rechten of absolute fouten zijn als het gaat om het introduceren van menu's, moet je goed nadenken over waar je je menu's blootlegt. Als een bestaand WordPress-menu zinvol is, registreer uw werk dan als een submenu.

In het volgende bericht zullen we beginnen met het bekijken van de verschillende invoerelementen die we kunnen gebruiken om opties in ons WordPress-thema te introduceren en hoe we de gegevens kunnen valideren en zuiveren voordat ze worden geserialiseerd.

Gerelateerde bronnen

add_menu_page
add_submenu_page
create_function
anonieme functies
WordPress Instellingen Sandbox 0.5

Code