WordPress Settings API, Del 2 Seksjoner, Felt og Innstillinger

Når det gjelder å utvikle WordPress Themes og Plugins, finnes det en rekke forskjellige måter utviklere lager sine menyer, alternativer og valideringsfunksjonalitet. Saken er, det er egentlig bare en måte å ordentlig gjøre dette i WordPress: Innstillings-API.

Denne serien tar sikte på å være den endelige veiledningen for hvordan du kan dra nytte av WordPress Settings API, slik at du har et enkelt referansepunkt for å utvikle dine temaer og plugins riktig..

I den første artikkelen i denne serien tok vi en bred titt på Innstillinger API og hvorfor det betyr noe. Her skal vi begynne å dykke inn i API og hvordan å dra nytte av alt det tilbyr.

Vi tar en titt på grunnleggende enheter av WordPress-alternativer - seksjoner, felt og innstillinger - og hvordan du kan legge dem inn i det innfødte WordPress Dashboard.

På seksjoner, felt og innstillinger

Før vi kommer til å skrive noen kode, er det viktig å forstå de tre hovedkomponentene i WordPress Settings API.

Enger er individuelle alternativer som vises på menysider. Felt samsvarer med faktiske elementer på skjermen. Det vil si at et felt styres av en tekstboks, radioknapp, avkrysningsboks, etc. Felt representerer en verdi lagret i WordPress-databasen.
seksjoner er en logisk gruppering av felt. Når du jobber med flere felt, vil du sannsynligvis gruppere tilhørende alternativer sammen - Seksjoner representerer denne grupperingen. Videre, hvis arbeidet ditt inneholder flere administrasjonssider, svarer hver seksjon ofte til sin egen menyside (selv om du også kan legge dem til eksisterende seksjoner).
innstillinger er registrert etter at du har definert begge felt og seksjoner. Tenk på Innstillinger som en kombinasjon av feltet og delen som den tilhører.

På dette punktet, ikke bekymre deg hvis du fortsatt er uklart om noen av hovedkomponentene. Vi skal ta en grundig titt på hver komponent sammen med eksempel kildekode som knytter det hele sammen.

En sandkasse for våre innstillinger

For å komme i gang med programmering mot Innstillings-API, la oss sette opp et grunnleggende tema som kan brukes i denne artikkelen og resten av serien. All kildekoden er tilgjengelig på GitHub også.

I din lokale installasjon av WordPress, naviger til "temaer" -katalogen og opprett en ny, tom katalog og kaller den "WordPress-Settings-Sandbox." Legg til følgende tre filer:

style.css - Dette er stilarket for temaet. Den inneholder all metainformasjon for temaet. Det kreves av WordPress
index.php - Dette er standardmalen for temaet. Det kan være tomt først. Det kreves av WordPress
functions.php - Det er her vi skal gjøre mesteparten av vårt arbeid. Vi skal fylle ut dette gjennom hele opplæringen

Legg til følgende kode for style.css:

/ * Tema Navn: WordPress Innstillinger Sandbox Tema URI: DIN URI Beskrivelse: Et enkelt tema som brukes til å vise WordPress Settings API. Forfatter: DITT NAVN Forfatter URI: DIN WEBSITE Versjon: 0.1 Lisens: Copyright 2012 DITT NAVN (E-postadressen din) Dette programmet er gratis programvare; Du kan omfordele den og / eller endre den under vilkårene i GNU General Public License, versjon 2, som publisert av Free Software Foundation. Dette programmet distribueres i håp om at det vil være nyttig, men UTEN NOGEN GARANTI; uten selv den underforståtte garantien om SALGBARHET eller EGNETHET TIL ET BESTEMT FORMÅL. Se GNU General Public License for mer informasjon. Du burde ha mottatt en kopi av GNU General Public License sammen med dette programmet; hvis ikke, skriv til Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA * /

Deretter legger du til følgende kode i index.php:

   Den komplette guiden til innstillingsgrensesnittet | Sandkasse tema    Sandbox Header
 
  Dette er temainnhold.
 
  ©  Alle rettigheter reservert.

Vær oppmerksom på at ovennevnte markering er ekstraordinært enkelt og jeg gjør det ikke anbefaler å bruke dette som grunnlag for temautvikling. Den er skreddersydd for denne serien av artikler og gir bare de måtene som vi vil lese verdier fra Innstillinger API.

I temaer administrasjonsskjerm, oppdater siden, og du bør se det nye Sandbox-temaet vises. Gå videre og aktiver den.

På dette tidspunktet er vi klar til å komme i gang.

Vårt første sett med alternativer

Merk i indeksmalen over, vi har definert tre bestemte innholdsregioner: header, innhold og bunntekst. Ved hjelp av Innstillinger API, la oss opprette en "Generell" seksjon som inneholder tre felt, som hver tilsvarer et av de bestemte innholdsregioner vi nettopp har definert.

Før du skriver kode, finner jeg det alltid nyttig å liste ut nøyaktig hva jeg trenger å gjøre. I dette tilfellet må vi gjøre følgende:

Definer en seksjon som vil bli brukt til å gruppere hvert felt
Legg til tre felt - ett for hver innholdsregion - til delen som er definert ovenfor
Registrer innstillingene med WordPress API.

For å unngå massive blokker av kode og for å sikre at vi dekker alle våre baser, tar vi hvert av de ovennevnte punktene punkt for punkt.

Opprette seksjonen

For å finne vår "Generelle" del av alternativene, må vi bruke add_settings_section-funksjonen i Innstillinger API. I følge WordPress Codex krever add_settings_section tre argumenter:

ID - Dette er den unike identifikatoren for denne delen. Merk at dette er verdien som vil bli brukt til å registrere hvert felt i denne delen. Vær så snill å nevne det uansett, men jeg anbefaler å gjøre det klart for lesbarhets skyld.
Tittel - Denne verdien vil vises øverst på siden i WordPress Dashboard når brukere jobber med alternativene dine.
Ring tilbake - Dette er navnet på en funksjon som vi vil definere som vil gjengi tekst på skjermen for funksjonen. Den kan brukes til en rekke funksjoner. I det enkleste tilfellet kan det brukes til å gi et sett med instruksjoner eller beskrivelser for alternativsiden din.
Side - Denne verdien brukes til å fortelle WordPress på hvilken side alternativene dine skal vises. I en fremtidig artikkel bruker vi dette til å legge til alternativer på våre egne sider. For nå vil vi legge til dette til eksisterende Generelle alternativer side.

Med det, la oss gå videre og definere vår seksjon. Ta en titt på følgende kommentert kode. Vi legger til dette i vår functions.php-fil.

Et ord om kodestykket i denne serien: Ikke bare kopier og lim inn denne koden. Ta deg tid til å lese hver linje, se hvordan argumentene samsvarer med hver API-funksjon som vi dekker, og følg de tilsvarende kommentarene for å sikre at du får tak i det vi gjør:

Velg hvilke områder av innhold du ønsker å vise.

'; // end sandbox_general_options_callback?>

Gir mening? Generelt ser det ikke ut som mye, men navigere til din innstillinger menyen og klikk på Generell. Bla til bunnen av siden, og du bør se den nye delen av alternativene.

Du kan legge til denne delen til noen av sidene under innstillinger Meny. I eksemplet ovenfor har vi passert «generell» som den siste parameteren til add_settings_section, men hvis du vil legge den til på en annen side, kan du gi en annen sidetittel. Her er en referanse for hver av innstillinger sider og tilhørende nøkkel:

Generell, "generell"
Skrive, "skrive"
Lesing, "lesing"
Diskusjon, "diskusjon"
Media, "media"
Personvern, "personvern"
Permalinks, "permalink"

Legge til felt

Nå som vi har en definert seksjon, kan vi introdusere noen få alternativer. Husk at i vår indeksmal har vi definert tre spesifikke containerelementer: header, innhold og bunntekst.

Selv om vi skal introdusere flere alternativer i løpet av denne serien, skal vi i dag innføre en måte å skifte synligheten til hver av elementene ovenfor.

I likhet med hva vi gjorde med innstillingsseksjonen, liker jeg å finne ut nøyaktig hva vi må gjøre før du skriver noen kode. Siden vi skal bytte hvert av innholdsområdene ...

Vi trenger tre alternativer - en for hvert område av innhold
Siden vi bytter synlighet, kan vi bruke en avkrysningsboks som grensesnittelement

På dette tidspunktet er vi klare til å introdusere det første innstillingsfeltet. For å gjøre dette bruker vi add_settings_field-funksjonen. Denne funksjonen tar seks parametere (fire obligatoriske, to valgfrie). De er som følger:

ID - ID av det aktuelle feltet. Dette vil bli brukt til å lagre og hente verdien gjennom temaet. Jeg anbefaler å navngi dette noe meningsfylt for å forbedre lesbarheten til koden din.
Tittel - Denne verdien gjelder en tittel til feltalternativet på administrasjonssiden. Dette bør være klart som det vil bli lest av sluttbrukerne.
Ring tilbake - Dette er navnet på funksjonen som brukes til å gjengi det aktuelle grensesnittelementet som brukerne vil samhandle med.
Side - I likhet med delen vi skisserte, identifiserer denne parameteren hvilken side dette alternativet skal oppholde seg til. Hvis du bare introduserer et enkelt alternativ, kan du legge det til en eksisterende side i stedet for en seksjon som du har definert.
Seksjon - Dette refererer til delen du har opprettet ved hjelp av add_settings_section-funksjonen. Denne verdien er IDen du angav når du opprettet delen din. Dette er en valgfri parameter.
argumenter - Dette er en rekke argumenter som sendes til tilbakeringingsfunksjonen. Dette er nyttig hvis det er tilleggsinformasjon som du vil inkludere når du gjør alternativelementet ditt. Dette er en valgfri parameter.

Med det sagt, la oss gå videre og definere vårt første innstillingsfelt. Spesielt vil vi introdusere et alternativ for å skifte synligheten til toppteksten.

Først foretar vi et anrop til add_settings_field like under add_settings_section funksjonen anrop i initialiseringsfunksjonen vi skrev i første del av opplæringen. Gå gjennom hver linje og kommentarene for hvert alternativ:

// Neste, vil vi introdusere feltene for å bytte synlighet av innholdselementer. add_settings_field ('show_header', // ID brukes til å identifisere feltet gjennom temaet 'Header', // Etiketten til venstre for alternativgrensesnittelementet 'sandbox_toggle_header_callback', // Navnet på funksjonen som er ansvarlig for å gi alternativgrensesnittet 'Generelt', // Siden som dette alternativet vil bli vist 'general_settings_section', // Navnet på delen som dette feltet tilhører array (// Utvalget av argumenter som skal overføres til tilbakeringingen. I dette tilfellet, bare en beskrivelse. 'Aktiver denne innstillingen for å vise overskriften.'));

Deretter definerer vi tilbakeringingen nevnt i den ovennevnte funksjonen. Denne tilbakeringingen brukes til å gjengi avmerkingsboksen og beskrivelsen på administrasjonssiden:

/ ** * Denne funksjonen gjør grensesnittelementene for å skifte synligheten til headerelementet. * * Den aksepterer en rekke argumenter og forventer at det første elementet i arrayet skal være beskrivelsen * som skal vises ved siden av avmerkingsboksen. * / funksjon sandbox_toggle_header_callback ($ args) // Merk ID og navnattributtet til elementet skal samsvare med ID-nummeret i samtalen til add_settings_field $ html = ''; // Her vil vi ta det første argumentet i arrayet og legge det til en etikett ved siden av avkrysningsboksen $ html. = ' '. $ args [0]. ''; ekko $ html;  // slutt sandbox_toggle_header_callback

Når det gjelder boksen, vær oppmerksom på kommentarene, men ikke bekymre deg for mye om noen av egenskapene du ikke kjenner igjen (for eksempel et anrop til funksjonen merket). Senere i denne serien skal vi se på hvert innspillingselement og deres tilhørende hjelpefunksjoner.

Nå skal din functions.php-fil se slik ut:

Velg hvilke områder av innhold du ønsker å vise.

'; // slutt sandbox_general_options_callback / * ------------------------------------------- ----------------------------- * * Felt tilbakeringinger * ---------------- -------------------------------------------------- ------ * / / ** * Denne funksjonen gjør grensesnittelementene for å skifte synligheten til topptekstelementet. * * Den aksepterer en rekke argumenter og forventer at det første elementet i arrayet skal være beskrivelsen * som skal vises ved siden av avmerkingsboksen. * / funksjon sandbox_toggle_header_callback ($ args) // Merk ID og navnattributtet til elementet samsvarer med ID-nummeret i samtalen til add_settings_field $ html = ''; // Her vil vi ta det første argumentet i arrayet og legge det til en etikett ved siden av avkrysningsboksen $ html. = ' '. $ args [0]. ''; ekko $ html; // ende sandbox_toggle_header_callback?>

På dette punktet, oppdatere Generelle innstillinger side. Du bør se boksen med "Header" -merket og en beskrivelse ved siden av avmerkingsboksen.

Dessverre lagrer det faktisk ikke verdien til databasen ennå.

Registrering av våre innstillinger

For å få feltene våre til å lagre i databasen, må vi registrere dem med WordPress. Å gjøre dette er relativt enkelt - vi trenger bare å benytte register_setting-funksjonen.

Denne funksjonen aksepterer tre argumenter (to obligasjoner, en valgfri):

Alternativgruppe - Dette er faktisk navnet på gruppen av alternativer. Dette kan enten være en eksisterende gruppe alternativer som tilbys av WordPress eller en ID som vi angav når du oppretter vår egen innstillingsseksjon. Dette argumentet kreves.
Alternativ Navn - Dette er ID av feltet som vi registrerer. I vårt tilfelle registrerer vi bare et enkelt felt, men hvis vi registrerte flere felt, må vi ringe denne funksjonen for hvert felt vi registrerer. Vi får se mer om dette på et øyeblikk. Dette argumentet kreves.
Ring tilbake - Dette argumentet krever navnet på en funksjon som vil bli kalt før lagring av dataene i databasen. Dette argumentet er utenfor rammen av denne artikkelen, men vi skal besøke den før serien er over. Dette argumentet er valgfritt.

På dette tidspunkt, la oss registrere innstillingen som vi nettopp har opprettet. Ta en titt på koden nedenfor. Legg til denne koden direkte under anropet til add_settings_field i initialiseringsfunksjonen som vi definerte tidligere i artikkelen. Det er uten tvil det enkleste å følge ut av alle utdragene i denne artikkelen:

// Endelig registrerer vi feltene med WordPress register_setting ('general', 'show_header');

Prøv det - merk av i avkrysningsruten, klikk på Lagre endringer, og merk at når siden oppdateres, har alternativet endret seg. Fjern merket i avkrysningsruten, lagre og se det lagre.

Lett nok, rett?

Legge til de to siste alternativene

Vi må fortsatt presentere alternativene for å bytte synlighet av innholdsområdet og bunntekstområdet. Det er nesten det samme som hvordan vi konfigurerer muligheten for å bytte på overskriften.

Først, la oss definere feltet for visning av innholdsområdet. Dette vil gå under det første anropet til add_settings_field:

add_settings_field ('show_content', 'Content', 'sandbox_toggle_content_callback', 'general', 'general_settings_section', array ('Aktiver denne innstillingen for å vise innholdet.'));

Og la oss sette opp tilbakeringingsfunksjonen:

funksjon sandbox_toggle_content_callback ($ args) $ html = ''; $ html. = ' '. $ args [0]. ''; ekko $ html;  // slutt sandbox_toggle_content_callback

Deretter la oss definere feltet for visning av bunntekstområdet:

add_settings_field ('show_footer', 'Footer', 'sandbox_toggle_footer_callback', 'general', 'general_settings_section', array ('Aktiver denne innstillingen for å vise bunnteksten.'));

Og sette opp tilbakeringingen for dette feltet også:

funksjon sandbox_toggle_footer_callback ($ args) $ html = ''; $ html. = ' '. $ args [0]. ''; ekko $ html;  // ende sandbox_toggle_footer_callback

Til slutt, la oss registrere disse to nye feltene med WordPress. Disse to funksjonsanropene går til bunnen av initialiseringsfunksjonen som vi definerte tidligere i artikkelen.

register_setting ('general', 'show_content'); register_setting ('general', 'show_footer');

Den endelige versjonen av functions.php skal se slik ut:

Velg hvilke områder av innhold du ønsker å vise.

Oppdater nå Generelle innstillinger siden og legg merke til at du har alle tre fullt funksjonelle avmerkingsboksene.

Leser API

Hvilke gode er alternativer hvis vi ikke kan dra nytte av dem gjennom hele vårt tema eller plugin? Vi må kunne lese verdiene for å kunne håndtere våre nye alternativer.

For å gjøre dette må vi bruke get_option-funksjonen. Denne funksjonen godtar to argumenter (en nødvendig, en valgfri):

Alternativ ID - Dette argumentet er feltet ID for verdien du prøver å hente. Dette argumentet kreves.
Standardalternativ - Dette er verdien verdien returnerer hvis funksjonen returnerer en tom verdi (for eksempel hvis alternativet ikke er funnet i databasen). Dette argumentet er valgfritt.

Først, la oss prøve å skifte synligheten til toppteksten. I indeksmalen som vi opprettet tidligere i denne artikkelen, finner du elementet med ID-nummeret til overskriften. Det skal se slik ut:

 Sandbox Header

Deretter la oss ringe til get_option i sammenheng med en betinget. Hvis betingelsene vurderes til ekte (det vil si, alternativet er blitt sjekket på Generelle innstillinger siden), så vil elementet bli vist; Ellers vil elementet ikke vises.

  Sandbox Header

Etter det håper du over til Generelle innstillinger side, sjekk alternativet for å skjule topptekstelementet, og oppdatere hjemmesiden din. Overskriftselementet skal ikke lenger vises.

På dette punktet er det enkelt å gjenta prosessen for innholdet og bunnteksten. Vi må pakke inn innholds- og bunntekstelementene med betingelsene som evaluerer resultatet av get_option-samtaler.

Ta en titt:

  Dette er temainnhold.
 
    ©  Alle rettigheter reservert.

Revisit Generelle innstillinger side, veksle hver avkrysningsboks og oppdatere temasiden. Dine elementer bør hver bytte uavhengig av hverandre.

Neste opp, menysider

Det er det, for nå! Vi har tatt en titt på alle funksjonene som kreves for å introdusere nye seksjoner, felt og innstillinger i WordPress. Selvfølgelig er det mye mer å dekke.

I neste artikkel tar vi en titt på hvordan du legger til egendefinerte menyelementer på WordPress-menyen, og hvordan vi kan presentere egne sider til WordPress Dashboard.

Beslektede ressurser

Vi dekket mye materiale i denne artikkelen. Her er en referanse for alt vi brukte i denne artikkelen.

Introduksjon til Innstillinger API
add_settings_section
add_settings_field
register_setting
get_option
Arbeidseksempel på GitHub

Kode