WordPress Settings API, del 3 Alt om menyer

På dette tidspunktet har vi lært hvorfor innstillings-API-en betyr noe, vi har lært alt om seksjoner, felt og innstillinger, og vi har til og med satt opp et Sandbox-tema som vi bruker til å utvikle funksjonalitet når vi undersøker API.

I denne artikkelen skal vi se på hvordan vi kan grensesnittet til WordPress menysystemet. Det er viktig å merke seg at dette egentlig ikke er en del av Innstillings-API, men det er så nært beslektet at vi bør gjøre oss kjent med hvordan vi bruker det.

Da våre temaer og / eller plugins blir mer komplekse, må vi vite alle de forskjellige måtene som vi kan inkludere dem i WordPress Dashboard. I denne artikkelen skal vi se på de ulike WordPress-menyfunksjonene, når de skal brukes, når de skal unngås, og hvilke situasjoner hver funksjon gir seg best til.

Forstå menytyper

WordPress tilbyr fire forskjellige måter å inkludere våre egne menyer. Nedenfor vil vi se på hver meny, parametrene hver aksepterer, og kode eksempler for hvordan de skal brukes i hele prosjektet. Vi tar sikte på å utvikle en klar forståelse av hvordan API fungerer, da den kan legge grunnlag for vårt fremtidige arbeid.

Menyer på toppnivå

Menysider refererer til menyelementene du ser når du logger deg først på WordPress. Det vil si at de er tilgjengelige alternativer i venstre meny som kan inneholde en liste over undermeny sider.

For å introdusere din egen menyside i WordPress Dashboard, bruker du add_menu_page-funksjonen.

Vi tar et kikk på et praktisk eksempel i et øyeblikk, men først la oss se gjennom funksjonen - den aksepterer sju argumenter (fem obligatoriske, to valgfrie):

Side tittel refererer til teksten som vises øverst i nettleservinduet når toppnivå menysiden vises.
Menytittel er teksten som vises i selve menyen. Det er best å holde dette litt kort, ellers vil det vikle seg i menyelementet og se litt ut mot resten av menyelementene.
Evne refererer til hvilke brukere som har tilgang til menyen. Dette er bare en strengverdi som representerer en av de tilgjengelige rollene.
Meny Slug er en unik identifikator som du oppgir. Den identifiserer denne menyen i sammenheng med WordPress og refererer også til siden som viser alternativene som er knyttet til denne menyen. Det gir også en krok med hvilke undermenyelementer som kan registrere seg.
Ring tilbake er funksjonen som definerer innholdet som vises på siden som tilsvarer denne menyen. Dette kan være inline HTML eller referere til en ekstern fil.
Ikon URL er banen til ikonet du vil vise ved siden av menyelementet i WordPress-menyen. Du kan bruke en av WordPress eksisterende ikoner eller bruke en av dine egne. Dette argumentet er valgfritt.
Stilling definerer posisjonen der denne menyen vil ligge i listen over WordPress 'menyelementer. Som standard vises menyen nederst på menyen, men en tilpasset posisjon vil plassere menyen over (eller under) noen av de eksisterende WordPress-menypunktene.

La oss ta en titt på et eksempel. Finn funksjoner.php i WordPress Settings Sandbox og legg til følgende to funksjoner:

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

Vær oppmerksom på at vi bruker admin_menu-kroken for å registrere menyelementet. Denne spesielle funksjonen brenner like etter at grunnleggende administrasjonsmenyen er på plass, slik at du vil registrere menyen din slik at WordPress gjør det mens du viser resten av menyene.

Neste, la oss sette opp det grunnleggende menyelementet. I tråd med artiklene tidligere i denne serien, er det det vi planlegger å gjøre:

Legg til en ny meny nederst på WordPress-menyen
Vi gir navnet på temaet vårt (det vil si "Sandbox")
Det vil være tilgjengelig for alle brukere
Det vil ikke inkludere et ikon

Enkelt nok, ikke sant? La oss gå videre og legge til vår meny. Igjen, ikke bare kopier og lim inn denne koden. Les det, noter kommentarene, og sørg for at du forstår hva vi gjør:

funksjon sandbox_create_menu_page () add_menu_page ('Sandbox Options', // Tittelen som skal vises på den tilsvarende siden for denne menyen 'Sandbox', // Teksten som skal vises for dette aktuelle menyelementet 'administrator', // Hvilken type av brukerne kan se denne menyen 'sandbox', // Den unike ID - det vil si sluggen - for dette menypunktet 'sandbox_menu_page_display', // Navnet på funksjonen som skal ringes når man gjør menyen til denne siden "); // slutt sandbox_create_menu_page add_action ('admin_menu', 'sandbox_create_menu_page');

Nå oppdaterer du WordPress administrasjonsmenyen, og du bør se et nytt menyelement. Når du klikker på den, bør du se en tom side vises.

Tydeligvis er dette ikke veldig funksjonelt. La oss stub ut tilbakeringingsfunksjonen vi definerte tidligere for å vise noe på skjermen:

funksjon sandbox_menu_page_display () // Opprett et overskrift i standard WordPress 'wrap'-beholder $ html =''; $ html. = 'Sandbox
'; $ html. = '
'; // Send markeringen til nettleseren echo $ html;  // slutt sandbox_menu_page_display

Den endelige versjonen av koden din skal se slik ut:

/ ** * Legger til en ny toppnivå meny nederst på administrasjonsmenyen på WordPress. * / funksjon sandbox_create_menu_page () add_menu_page ('Sandbox Options', // Tittelen som skal vises på den tilsvarende siden for denne menyen 'Sandbox', // Teksten som skal vises for dette aktuelle menyelementet 'administrator', // Hvilken type brukere kan se denne menyen 'sandkasse', // Den unike ID - det vil si sluggen - for dette menypunktet 'sandbox_menu_page_display', // Navnet på funksjonen som skal ringes når man gjør menyen til denne siden ") ; // end sandbox_create_menu_page add_action ('admin_menu', 'sandbox_create_menu_page'); / ** * Gjør det grunnleggende displayet på menysiden for temaet. * / funksjon sandbox_menu_page_display () // Opprett et overskrift i standard WordPress ' pakke 'container $ html =''; $ html. = 'Sandbox
'; $ html. = '
'; // Send markeringen til nettleseren echo $ html;  // slutt sandbox_menu_page_display

Annet enn hvordan man faktisk bruker add_menu_page-funksjonen, er kanskje det mest subtile tatt bort at i WordPress har hvert menyelement en tilsvarende menyside. Vi vil se nærmere på dette i dybden gjennom hele serien, men det er viktig å merke seg nå som vi begynner å utforske hver av de forskjellige menyene.

Selv om dette er stort sett ufullstendig, legger vi til dette gjennom resten av denne artikkelen og resten av opplæringen.

En merknad om posisjonering: Mange utviklere vurderer å bruke stillingsargumentet som dårlig etikett, da det blander opp standardbrukeropplevelsen med WordPress. I tillegg, hvis du definerer en posisjon og et annet tema, plugin eller funksjon bruker samme posisjon, kan en av menypunktene overskrives.

Undermenyer menyer~~POS=HEADCOMP

Undermenyer er som menyer med unntak av at de tilhører en annen meny - de har en forelder. Så, åpenbart, du kan ikke opprette en undermeny uten å lage et menypunkt først. Selvfølgelig, som vi så i den siste artikkelen, kan undermenyelementer bli introdusert til eksisterende menyelementer - ikke bare tilpassede menyelementer.

I denne artikkelen vil vi introdusere en undermeny-side i vårt eget menyelement. Men før du gjør det, la oss ta en titt på add_submenu_page-funksjonen og parametrene som den aksepterer:

Foreldre Slug refererer til IDen til det overordnede menyelementet som denne undermenyen vil tilhøre. I vårt tilfelle bruker vi menypunktet som vi definerte ovenfor.
Side tittel er teksten som vil vises i nettlesertittelen når siden blir gjengitt.
Menytittel er teksten som vil vises som det aktuelle menyelementet i WordPress-menyen.
Evne, som med foreldremenyen, refererer til hvilke typer brukere som har tilgang til denne bestemte menyen.
Meny Slug er den unike identifikatoren for dette menyelementet. Det er det som brukes til å definere denne menyen i sammenheng med WordPress.
Ring tilbake er funksjonen som brukes til å gjøre denne menyens side til skjermen.

Hvis du vil legge til et menyelement i en av de eksisterende menyene, se tabell i forrige artikkel.

La oss begynne med å registrere en undermeny for den eksisterende menyen ovenfor. Vi vil gjøre følgende:

Registrer en undermeny som skal legges til menyen vi nettopp har opprettet
Det vil vise teksten 'Alternativer'
Det vil være tilgjengelig for alle brukere
Det vil ikke inkludere et ikon

Sjekk ut følgende kode - vi legger til dette direkte under vårt anrop til add_menu_page:

add_submenu_page ('sandbox', // Registrer denne undermenyen med menyen som er definert ovenfor 'Sandbox Options', // Teksten til skjermen i nettleseren når dette menyelementet er aktivt 'Options', // Teksten for dette menypunktet ' administrator ', // Hvilken type brukere kan se denne menyen' sandbox_options ', // Den unike ID-sluggen - for dette menypunktet' sandbox_options_display '// Funksjonen som brukes til å gjøre menyen til denne siden til skjermen);

Ikke glem å definere tilbakeringingen, selv om den er tom. Det er, ikke glem å legge denne funksjonen til filen din (vi legger til flere ganger):

funksjon sandbox_options_display ()  // slutt sandbox_options_display

Når du oppdaterer nettleseren din, bør du nå se to undermenyelementer rett under "Sandbox" -menyen. Legg merke til at WordPress oppretter et undermenyelement på egen hånd - det er et undermenyelement som tilsvarer menyelementet og tilbakekallingsfunksjonen som er definert. Det andre er det nye undermenyalternativet som vi nettopp har definert, selv om det ikke gir noe innhold.

For å fikse det, la oss gå videre og introdusere en grunnleggende side. Oppdater undermenyens tilbakeringingsfunksjon for å se slik ut:

funksjon sandbox_options_display () // Opprett et overskrift i standard WordPress 'wrap' container $ html = ''; $ html. = 'Sandbox-alternativer
'; $ html. = '
'; // Send markeringen til nettleseren echo $ html;  // slutt sandbox_options_display

Oppdater nettleseren din igjen, og du bør se en grunnleggende sidetittel når du velger den nye alternativer undermenyelement.

Selv om dette ikke er nødvendig, merk at du faktisk kan ha det overordnede menyelementet og alternativer menyelementet refererer til det samme innholdet - bare oppdatere tilbakeringingen i ad_menu_page-funksjonen til sandbox_options_display funksjon som vi nettopp har definert.

Plugin Pages

Hvis du utvikler et WordPress-plugin, er det noen forskjellige måter at produktet ditt kan grensesnitt med plattformen.

Spesielt din plugin ...

Kan fungere i bakgrunnen og krever ikke en meny.
Kan bruke begge eller en av funksjonene nevnt ovenfor for å bygge en egendefinert meny
Kan inkludere seg selv i en av de eksisterende WordPress-menyene

For å gjøre det enklere for plugin-utviklere å inkludere deres alternativer i eksisterende WordPress-menyer, tilbyr WordPress API følgende funksjon: add_plugins_page.

Men vent. Hvis du har fulgt med eksemplene ovenfor, har du sannsynligvis lagt merke til at det ikke synes å være noen merkbar forskjell mellom add_plugins_page og add_submenu_page. Du har rett. add_plugins_page har samme funksjonalitet som add_submenu_page, men det er to primære forskjeller:

Pluggen er gitt spesielt for bruk i plugin-utvikling.
Funksjonen legger til menypunktet for plugins direkte til WordPress ' plugins Meny.

Selv om du sikkert kan bruke add_submenu_page for å oppnå det samme målet, er jeg alltid en fan av å bruke funksjoner som er beregnet for en bestemt brukstilstand selv om det finnes en annen API-funksjon som gjør det samme. Når du gjør dette, viser du at du bruker API-en som utviklerne har til hensikt, og du gjør koden litt mer sammenhengende, siden kodebasen din er nærmere tilpasset hvordan den samhandler med kjerneplattformen.

Plugin utvikling er utenfor omfanget av denne serien, men det er ikke helt irrelevant. Selv om det ikke blir gjort noen endringer i vårt Sandkasse tema, vil jeg gi et enkelt eksempel som viser hvordan du bruker denne spesielle funksjonen.

La oss først se på argumentene som add_plugins_page aksepterer:

Side tittel er teksten som vil vises i nettlesertittelen når pluginens tilleggsside blir gjengitt.
Menytittel er teksten som vises som pluginets menyelement i WordPress-menyen.
Evne som med foreldremenyen, refererer til hvilke typer brukere som har tilgang til denne bestemte menyen.
Meny Slug er den unike identifikatoren for dette menyelementet. Det er hva det pleide å definere denne menyen i sammenheng med WordPress.
Ring tilbake er funksjonen som brukes til å gjøre denne menyens side til skjermen.

Her er et enkelt eksempel som demonstrerer nøyaktig hvordan du bruker det. Merk at du kan inkludere dette i din functions.php-fil, men det er ikke en del av Sandbox Theme som vi jobber med, og bør brukes i sammenheng med et plugin, i stedet.

Først sett opp anropet til API-funksjonen - merk at dette bruker admin_menu-kroken:

funksjon sandbox_example_plugin_menu () add_plugins_page ('Sandbox Plugin', // Tittelen som skal vises i nettleservinduet for denne siden. 'Sandbox Plugin', // Teksten som skal vises for dette menyelementet 'administrator', // Hvilket type brukere kan se dette menypunktet 'sandbox_plugin_options', // Den unike ID - det vil si sluggen - for dette menypunktet 'sandbox_plugin_display' // Navnet på funksjonen som skal ringes når du gjør siden til denne menyen);  // end sandbox_example_plugin_menu add_action ('admin_menu', 'sandbox_example_plugin_menu');

Deretter sett opp funksjonen som vil gjøre pluginets display:

funksjon sandbox_plugin_display () // Opprett et overskrift i standard WordPress 'wrap' container $ html = ''; $ html. = 'Sandbox Plugin Options
'; $ html. = 'Det finnes for øyeblikket ingen alternativer. Dette er bare for demo formål.
'; $ html. = '
'; // Send markeringen til nettleseren echo $ html;  // slutt sandbox_plugin_display

Oppdater ditt WordPress Dashboard, svever over plugins menyen, og du bør legge merke til et nytt menyelement. Ikke dårlig, huh?

Den endelige versjonen av koden skal se slik ut:

/ ** * Denne funksjonen introduserer et enkelt tema menyalternativ i WordPress 'Plugins' * -menyen. * / funksjon sandbox_example_plugin_menu () add_plugins_page ('Sandbox Plugin', // Tittelen som skal vises i nettleservinduet for denne siden. 'Sandbox Plugin', // Teksten som skal vises for dette menyelementet 'administrator', / / Hvilken type brukere kan se dette menypunktet 'sandbox_plugin_options', // Den unike ID - det vil si sluggen - for dette menypunktet 'sandbox_plugin_display' // Navnet på funksjonen som skal ringes når du gjør siden til denne menyen) ;  // end sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_plugin_menu'); / ** * Gjør en enkel side å vise for tema-menyen som definert ovenfor. * / funksjon sandbox_plugin_display () // Opprett et overskrift i standard WordPress 'wrap' container $ html = ''; $ html. = 'Sandbox Plugin Options
'; $ html. = 'Det finnes for øyeblikket ingen alternativer. Dette er bare for demo formål.
'; $ html. = '
'; // Send markeringen til nettleseren echo $ html;  // slutt sandbox_plugin_display

Igjen, denne funksjonen vil ikke være en del av vårt Sandkasse tema fordi det er rettet mot plugin utvikling; Det er imidlertid verdt å dekke for de av dere som vil utnytte Innstillings-API-en i plugin-utviklingsarbeidet ditt.

Tema Sider

Akkurat som med plugins, gir WordPress en API-funksjon for å introdusere menyer spesielt for temaer. Det ligner veldig på plugin-menyfunksjonen fordi den gir enda en måte å introdusere en undermeny på eksisterende menyer. Den primære forskjellen er at undermenyen legges til i Utseende Meny.

Som med plugin-eksemplet tidligere i denne artikkelen, tar vi en titt på hvordan vi kan bruke denne funksjonen, men vi vil ikke inkludere den i vårt Sandbox-tema. Dette er ment å bare vise hvordan du bruker funksjonen bare hvis du velger å gå denne ruten i ditt personlige arbeid.

Først vurderer vi argumentene som add_theme_page aksepterer. Du vil legge merke til at de er akkurat som de som kreves for plugin-menyen, og ligner på undermenyfunksjonene som vi skisserte tidligere:

add_theme_page aksepterer følgende argumenter:

Side tittel er teksten som vil vises i nettlesertittelen når temaets valgside blir gjengitt.
Menytittel er teksten som vil vises som temaets menyelement i WordPress-menyen.
Evne som med foreldremenyen, refererer til hvilke typer brukere som har tilgang til denne bestemte menyen.
Meny Slug er den unike identifikatoren for dette menyelementet. Det er hva det pleide å definere denne menyen i sammenheng med WordPress.
Ring tilbake er funksjonen som brukes til å gjøre denne menyens side til skjermen.

Som med de andre funksjonene, oppretter vi et par utvalgsfunksjoner som viser hvordan dette inkluderer i prosjektet. Legg merke til at samtalen til add_theme_page kan legges til functions.php, og i motsetning til samtalene til add_plugin_page, bør bor her når du utvikler temaet ditt.

Først, anropet til å sette opp menyelementet:

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 siden for denne menyen);  // end sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu');

Deretter skal vi sette opp en funksjon for å gjøre alternativsiden:

funksjon sandbox_theme_display () // Opprett en overskrift i standard WordPress 'wrap'-beholderen $ html =''; $ html. = 'Temaalternativer for Sandbox
'; $ html. = 'Det finnes for øyeblikket ingen alternativer. Dette er bare for demo formål.
'; $ html. = '
'; // Send markeringen til nettleseren echo $ html;  // slutt sandbox_theme_display

Oppdater nå WordPress Dashboard, svever over Utseende menyen, og du bør se det nye menyelementet. Enkel!

Den endelige versjonen av koden skal se slik ut:

/ ** * Denne funksjonen introduserer et enkelt tema menyalternativ i WordPress 'Utseende' * -menyen. * / 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', / / Hvilken 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 gjør siden til denne menyen) ;  // end sandbox_example_theme_menu add_action ('admin_menu', 'sandbox_example_theme_menu'); / ** * Gjør en enkel side å vise for tema-menyen som definert ovenfor. * / funksjon sandbox_theme_display () // Opprett en overskrift i standard WordPress 'wrap' container $ html = ''; $ html. = 'Temaalternativer for Sandbox
'; $ html. = 'Det finnes for øyeblikket ingen alternativer. Dette er bare for demo formål.
'; $ html. = '
'; // Send markeringen til nettleseren echo $ html;  // slutt sandbox_theme_display

For de av dere som er interessert i å gjøre mer avansert temautvikling, har du sannsynligvis vurdert de ulike måtene å implementere flere tilleggssider for ditt tema.

På den ene siden kan vi legge til flere undermenyer til en toppnivå meny, men der er et alternativ: tabbed navigering. Dette gir seg godt når du vil introdusere alternativer til Utseende menyen og ikke legg til enda et menyelement til WordPress Dashboard. Vi vil diskutere dette i dybden i neste artikkel.

Når skal du bruke hver funksjon

Vi har tatt en titt på hver av de fire viktigste måtene å introdusere våre egne tilleggssider til WordPress. Selv om disse funksjonene ikke er spesifikt del av Innstillings-API, er det viktig å diskutere fordi de jobber så tett sammen med det.

Men å vite disse funksjonene er bare halvparten av det. Som utvikler ansvarlig for integrasjon og organisering av innstillinger, er det viktig å vite når du skal bruke hver av de forskjellige funksjonene i riktig sammenheng.

Selv om det ikke er svar på sølvkulett for når du skal bruke hver funksjon, er det noen retningslinjer du bør vurdere når du jobber med dine tilpassede funksjoner, plugins og / eller tema:

Menyer på toppnivå kan legges til når det er en undermeny som kan logisk grupperes med disse alternativene. Dette gir seg til når du har en viktig samling innstillinger som ikke logisk passer inn i noen av de eksisterende WordPress-menyene.
Undermenyer menyer~~POS=HEADCOMP alltid tilhører en toppnivå meny - enten tilpasset eller eksisterende. De bør alltid grupperes under toppnivå menyen som er mest logiske. Hvis WordPress tilbyr en meny som kan fungere som overordnet for undermenyen din, bruker du den; Forurens ikke menyen med en overflødig meny på overflaten.
Plugin Menyer bør brukes når du har enkle, en-sidede alternativer for pluginet ditt. Hvis du har flere tilleggssider, bør du vurdere å opprette en toppmeny eller vurdere bruk av fanebladnavigasjon som vi vil utforske i neste artikkel.
Tema Menyer bør brukes når du utvikler ditt eget tema som tilbyr sitt eget sett med tilpassede alternativer. Hvis alternativene kan leve på en enkelt side, bør du vurdere å bruke WordPress 'API-funksjon. Hvis du har flere alternativer, bør du vurdere å bruke fanebladnavigasjon. Legg merke til at mange temautviklere ofte løfter deres temaalternativer til toppnivåmenyen, og det er greit også.

Et ord om egendefinerte menyer: Selv om WordPress gir oss muligheten til å legge til våre egne menyer på toppnivå, legger til i hvilken som helst eksisterende meny, og gir oss generelt muligheten til å gjøre det vi vil ha med standardkonfigurasjonen, deler en del av fellesskapet seg på dette. De tror at tilpasset funksjonalitet ikke bør forstyrre visse kjernemenyer. Selv om det til slutt er opp til deg, implementerer arbeidet ditt med skikkelse - odds er, få ting du gjør er viktigere enn WordPress-kjernevirksomhet, så legg ikke arbeidet ditt over det.

Hva skjer neste gang?

I den neste artikkelen skal vi bruke litt av det vi har lært om menyer og begynn å introdusere tilleggssider for våre Sandbox-tema.

I tillegg til å legge til menysider, vil vi også se på flippingsnavigasjon og hvordan vi kan implementere den til å fungere sammen med våre egne menysider.

Gjennomgå tidligere artikler i denne serien, og ikke glem å sjekke den nåværende versjonen av WordPress Settings Sandbox på GitHub.

Beslektede ressurser

Vi dekket ganske mange ressurser i denne artikkelen. Her er et sammendrag av alt vi brukte:

add_menu_page
add_submenu_page
add_plugins_page
add_theme_page
WordPress Settings Sandbox

Kode