WordPress Settings API, Del 6 Menysider

I del 3 av denne serien undersøkte vi de ulike menyfunksjonene som WordPress API gir. Hvis du har fulgt med, vet du at vi allerede har satt opp en innstillingsside for temaet vårt ved å bruke add_theme_page funksjon. Selv om innføring av menyer og undermenyer ikke er eksplisitt en del av Innstillings-API, spiller de en rolle i å bygge tilpasset funksjonalitet, plugin og / eller temaer.

I denne artikkelen kommer vi til å introdusere en ny meny til WordPress-dashbordet som vil gjøre våre temaalternativer tilgjengelige andre steder enn bare under alternativene "Utseende".

Før vi kommer i gang: Denne artikkelen antar at du er kjent med Innstillings-API og temaalternativer. Hvis du er en nybegynner eller en mellomliggende WordPress-utvikler, anbefaler jeg på det sterkeste å ta opp resten av serien før du dykker inn i dette innlegget.

En titt på API

Fordi vi allerede har sett på hver av menyfunksjonene, trenger vi ikke å rehash hver av funksjonene som WordPress har tilgjengelig. I stedet ser vi på de vi skal bruke, og deretter jobber vi gjennom et praktisk eksempel på hvordan du bruker dem i vårt eget arbeid.

Før vi ser på hver funksjon, la oss detaljere hva vi planlegger å oppnå i neste fase av denne serien:

Sett inn en toppmeny for våre temaalternativer
Legg til et undermenyelement som vil koble til kategorien "Visningsalternativer"
Legg til et undermenyelement som vil koble til kategorien "Sosiale valg"

Relativt enkelt, ikke sant? For å gjøre dette, vil vi dra nytte av følgende to funksjoner:

add_menu_page som brukes til å introdusere toppnivå menyelementer
add_submenu_page som brukes til å introdusere undermenyelementer til toppnivå menyer.

Vi tar en titt på hver funksjonens parametere og bruk når vi implementerer dem i vårt tema.

Vær oppmerksom på at resten av denne artikkelen bygger på denne versjonen av WordPress Settings Sandbox. Hvis du følger med depotet, må du sjekke det ut.

Toppnivåmenyen

Det første vi ønsker å gjøre er å presentere en toppmeny. Denne menyen vil vises direkte under "Innstillinger" -menyen i WordPress-dashbordet og vil tjene to formål. Menyen skal:

Utsett temaets alternativer til WordPress dashboard
Vis en standardalternativerside for temaalternativer

Funksjonen tar følgende syv argumenter, de fem første er påkrevet, de to siste er ikke:

side tittel er teksten som blir gjengitt i nettleserens tittellinje
menu_title er teksten som vil bli vist for menyelementet
evne refererer til hvilken rolle brukeren må ha for å få tilgang til denne menyen
menu_slug er en unik verdi som identifiserer denne menyen. Det er også hvordan undermenyer registrerer seg med denne menyen.
FUNCTION_NAME det kalles når menyen klikkes for å vise opsjonssiden.
icon_url er banen til ikonet du vil vise ved siden av menyelementet.
stilling er hvor menyen skal legges i forhold til de andre menyene i WordPress Dashboard.

I vårt arbeid blir vi bare fokusert på de fem første parameterne. Jeg diskuterer menyposisjonering i konklusjonen av denne artikkelen.

For å komme i gang må vi innføre et anrop til add_menu_page funksjon. Ifølge WordPress Codex kan administrasjonsmenyer legges til ved hjelp av admin_menu kroken. Tidligere i denne serien skrev vi en funksjon som legger til våre temaalternativer til "Utseende" -menyen. Spesielt skrev vi sandbox_example_theme_menu:

funksjon sandbox_example_theme_menu () add_theme_page ('Sandbox Theme', // Tittelen som skal vises i nettleservinduet for denne siden. 'Sandbox Theme', // Teksten som skal vises for dette menyelementet 'administrator', // Hvilket type brukere kan se dette menypunktet 'sandbox_theme_options', // Den unike ID - det vil si sluggen - for dette menypunktet 'sandbox_theme_display' // Navnet på funksjonen som skal ringes når du gjengir denne menyens side);  // end sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu');

Merk i koden ovenfor at denne funksjonen var registrert hos admin_menu krok også. Du bør alltid strebe for å holde funksjonene dine logisk konsistente. Siden vi allerede har en funksjon som registrerer en meny, er den registrert med riktig krok, og siden vi introduserer lignende funksjonalitet, legger vi til våre nye menyfunksjoner til denne funksjonen.

Legg til følgende anrop til add_menu_page direkte under anropet ovenfor:

add_menu_page ('Sandbox Theme', // Verdien som brukes til å fylle ut tittellinjen i nettleseren når menysiden er aktiv 'Sandbox Theme', // Menyens tekst i administratorens sidebar 'administrator', // Hvilke roller kan for å få tilgang til menyen 'sandbox_theme_menu', // ID brukes til å binde undermenyelementer til denne menyen 'sandbox_theme_display' // Tilbakeringingsfunksjonen som brukes til å gjengi denne menyen);

Som du kan se registrerer vi en meny som viser "Sandbox Theme" i både tittellinjen og i menyelementet. Vi utsetter kun menyen til administratorer, og vi har gitt menyen den unike IDen til "sandbox_theme_parent_menu". Vi vil bruke denne parameteren på nytt i neste avsnitt.

Det er en viktig ting som vi trenger å klargjøre: Merk at vi har passert 'sandbox_theme_display'som funksjonen som skal ringes når dette menyelementet klikkes. Husk at i del 3 vi introduserte denne funksjonen (og vi raffinerte den i del 5). Nærmere bestemt er det ansvarlig for å gjengi vår faneblad for temaalternativer.

Ved å sende dette eksisterende funksjonsnavnet til add_menu_page funksjon, utnytter vi kode som vi allerede har skrevet, og vi gjør en standardalternativerside for menyelementet.

På dette tidspunktet er vi klare til å begynne å legge til undermenyer, men før du går videre, må du kontrollere at funksjonen din ser ut akkurat slik:

funksjon 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');  // slutt sandbox_eksempel_tema_meny

Legg til undermenyene

Undermenyer ligner på menyer med unntak av at de tilhører en eksisterende meny. APIen for registrering av undermenyer er også relativt lik. Funksjonen aksepterer seks argumenter, de fem første er nødvendig, den siste er valgfritt:

parent_slug refererer til den unike IDen til det overordnede menyelementet. I vårt tilfelle "sandbox_theme_menu".
side tittel er teksten gjengitt i nettleserens verktøylinje når dette undermenyelementet er aktivt
menu_title er teksten for dette aktuelle undermenyelementet i dashbordet
evne er den rollen som en bruker må ha for å få tilgang til dette menyelementet
menu_slug er den unike IDen for dette bestemte menyelementet
FUNCTION_NAME det kalles når menyen klikkes for å vise opsjonssiden

Funksjonen er enkel. Vi har to menyelementer å introdusere - en for "Visningsalternativer" og en for "Sosiale valg."

Visningsalternativer

Først, la oss introdusere et undermenyelement for visningsalternativer. Legg til følgende blokk kode direkte under add_menu_page ring som vi definerte ovenfor:

add_submenu_page ('sandbox_theme_menu', // IDen på toppnivå menysiden som dette undermenyelementet tilhører 'Skjermalternativer', // Verdien som brukes til å fylle ut tittellinjen i nettleseren når menysiden er aktiv 'Skjermalternativer', // Etiketten til denne undermenyelementet som vises i menyen 'administrator', // Hvilke roller kan få tilgang til dette undermenyelementet 'sandbox_theme_display_options', // IDen som brukes til å representere dette undermenyelementet 'sandbox_theme_display' // Den tilbakekallingsfunksjonen som brukes å gjøre alternativene for denne undermenyelementet);

Hver av de ovennevnte parametrene skal være klar med unntak av funksjonsnavnet som vi passerte som det endelige argumentet. Legg merke til at det er samme funksjonsnavn som vi oppgav i add_menu_page anrop. Men dette gir mening, ikke sant? Tross alt er "Visningsalternativer" standardfanen som vises når temaalternativer er valgt, så det ville være fornuftig at det skulle gjengis når toppmenyen er valgt, og når menyelementet "Visningsalternativer" er valgt.

På dette punktet er det en viktig funksjon av WordPress å markere: Merk at når du først har lagt til ditt første undermenyelement, vil WordPress faktisk gjengi to undermenyelementer til toppnivåmenyen - ett element som dupliserer funksjonen på toppnivå meny og ett element som tilsvarer undermenyelementet som du nettopp har definert. Jeg tar opp dette fordi, etter min erfaring, har jeg sett utviklere forvirret om hvordan (og hvorfor) dette skjer. Kort sagt er det at WordPress gjør dette - det er ikke noe galt med koden din.

Sosiale valg

Å legge til et menyelement for de sosiale alternativene, er nesten like å legge til et menyelement for skjermalternativene. Selvfølgelig vil vi bare endre verdiene for tittellinjen, menyelementet og siden som vises når menyen er valgt. La oss først sette opp vårt anrop til add_submenu_page funksjon. Det skal se slik ut:

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

Lagre koden, oppdater dashbordet, og du bør se menypunktet "Sosiale valg" nå tilgjengelig under "Sandbox Theme" -menyen. Vær imidlertid oppmerksom på at klikke på det nye undermenyelementet bare gjør "Visningsalternativer". Siden vi har passert "sandbox_theme_display"som funksjonsnavn, det er det vi burde forvente, ikke sant? Så nå står vi overfor en liten utfordring: Hvordan velger vi kategorien" Sosiale valg "når du klikker på undermenyelementet?

Refactoring Vår Tab Funksjonalitet

Det er et par forskjellige alternativer vi har for å knytte det nye undermenyelementet til riktig faneblad på temaalternativer-siden:

Vi kan definere en ny funksjon som utgjør de sosiale alternativene. Dette ville kreve at vi gjør noe ekstra arbeid med å introdusere en ny funksjon, sette opp tabbing-funksjonalitet slik at vi ikke bryter opplevelsen av den eksisterende siden, og dupliserer litt kode.
Vi kan refactor den eksisterende sandbox_theme_display fungere for å godta en valgfri parameter og deretter bruke en anonym funksjon i add_submenu_page ring for å sende en parameter til den.

Til slutt, noen av disse alternativene er opp til deg; men jeg vil helst refactor min eksisterende funksjon enn duplikat kode, så det er hva jeg skal gjøre gjennom resten av denne artikkelen.

Først, la oss begynne å refactoring vår sandbox_theme_display funksjon. La oss akseptere et valgfritt argument som vil bli brukt til å indikere hvilken kategori vi vil velge. Finn følgende signatur i din functions.php fil:

funksjon sandbox_theme_display () / * Konsolidert for denne delen av artikkelen. * / // slutt sandbox_theme_display

Oppdater signaturen slik at den aksepterer et enkelt argument og setter det til null når det ikke er definert:

funksjon sandbox_theme_display ($ active_tab = null) / * Konsolidert for denne delen av artikkelen. * / // slutt sandbox_theme_display

Hvis du er ny i PHP, kan du lese om standardargumenter på denne siden.

Husk fra den siste artikkelen at vår visningsfunksjon faktisk ser etter en søkeordstrenge som skal settes. Vi ønsker fortsatt å opprettholde den funksjonaliteten, men vi må også regne med at parameteren også kan sendes inn i funksjonen. For å utføre denne refactoring, må du først finne følgende linje med kode i sandbox_theme_display funksjon:

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

Legg merke til at denne bestemte koden er bare opptatt av søkeordsparametrene. For å ta hensyn til den nye valgfrie parameteren, må vi introdusere logikk som først kontrollerer om spørringsstrengeparameteren er merket, hvis ikke, vil den sjekke for å se om funksjonens argument er satt til å vise de sosiale alternativene, og hvis ikke, da det vil bli standard på skjermalternativene. Erstatt koden ovenfor med følgende vilkår:

hvis (isset ($ _GET ['tab'])) $ active_tab = $ _GET ['tab'];  annet hvis ($ active_tab == 'social_options') $ active_tab = 'social_options';  else $ active_tab = 'display_options';  // slutt hvis / annet

Den endelige versjonen av funksjonen skal se slik ut:

funksjon sandbox_theme_display ($ active_tab = ") ?>

Temaalternativer for Sandbox

"> Visningsalternativer"> Sosiale valg

Vi er ikke helt ferdige ennå. Selv om vi har gjort det nødvendige arbeidet for å vise de sosiale alternativene hvis riktig parameter har blitt bestått, har vi ikke faktisk kalt funksjonen ved hjelp av en parameter. For å gjøre dette må vi refactor the add_submenu_page funksjonen ovenfor. For øyeblikket ser funksjonsanropet ut slik:

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

Vi må oppdatere den endelige parameteren slik at den kaller skjermfunksjonen og sender den riktige verdien for å gjengi de sosiale alternativene. For å gjøre det, oppretter vi en anonym funksjon:

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

Hvis du er ny i PHP, må du lese den på create_function funksjon og anonyme funksjoner. Selv om de er utenfor rammen av denne artikkelen, kan de være kraftige (og nyttige!) Når de brukes i riktig sammenheng.

Den endelige versjonen av sandbox_example_theme_menu funksjonen bør være som følger:

funksjon sandbox_example_theme_menu () add_theme_page ('Sandbox Theme', // Tittelen som skal vises i nettleservinduet for denne siden. 'Sandbox Theme', // Teksten som skal vises for dette menyelementet 'administrator', // Hvilket type brukere kan se dette menypunktet 'sandbox_theme_options', // Den unike ID - det vil si sluggen - for dette menypunktet 'sandbox_theme_display' // Navnet på funksjonen som skal ringes når du gjengir denne menyens side); add_menu_page ('Sandbox Theme', // Verdien som brukes til å fylle ut tittellinjen i nettleseren når menysiden er aktiv 'Sandbox Theme', // Menyens tekst i administratorens sidebar 'administrator', // Hvilke roller kan for å få tilgang til menyen 'sandbox_theme_menu', // ID brukes til å binde undermenyelementer til denne menyen 'sandbox_theme_display' // Tilbakeringingsfunksjonen som brukes til å gjengi denne menyen); add_submenu_page ('sandbox_theme_menu', // IDen på toppnivå menysiden som dette undermenyelementet tilhører 'Skjermalternativer', // Verdien som brukes til å fylle ut tittellinjen i nettleseren når menysiden er aktiv 'Skjermalternativer', // Etiketten til denne undermenyelementet som vises i menyen 'administrator', // Hvilke roller kan få tilgang til dette undermenyelementet 'sandbox_theme_display_options', // IDen som brukes til å representere dette undermenyelementet 'sandbox_theme_display' // Den tilbakekallingsfunksjonen som brukes å gjøre alternativene for denne undermenyelementet); add_submenu_page ('sandbox_theme_menu', 'Social Options', 'Social Options', 'administrator', 'sandbox_theme_social_options', create_function (null, 'sandbox_theme_display ("social_options");'));  // end sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu');

Konklusjon

På dette tidspunktet har vårt tema nå sitt eget toppnivå menyelement med hver av innstillingsfanene som er tilgjengelige via undermenyelementer. Selv om dette er nyttig, tror jeg det er viktig å merke seg at det er noen blandede meninger om å innføre menyer i WordPress Dashboard. Selv om de kan gjøre arbeidet ditt mer fremtredende og tilgjengelig, kan de også forstyrre eksisterende WordPress-menyer eller andre tredjepartsarbeid spesielt hvis du forsøker å plassere menyene dine et sted ved hjelp av posisjonsparameteren. Selv om det ikke er absolutt feil eller absolutt feil når det gjelder å introdusere menyer, tenk nøye på hvor du utsetter menyene dine. Hvis en eksisterende WordPress-meny er fornuftig, registrerer du arbeidet som en undermeny.

I neste innlegg begynner vi å ta en titt på de ulike innspillingselementene som vi kan bruke til å introdusere alternativer i vårt WordPress-tema, samt hvordan vi kan validere og sanitisere dataene før serialisering av dem.

Beslektede kilder

add_menu_page
add_submenu_page
create_function
anonyme funksjoner
WordPress Innstillinger Sandbox 0.5

Kode