WordPressin hookit käytännössä: action- ja filter-koukk...

Tiivistelmä

WordPressin toimintoja voidaan laajentaa ilman, että järjestelmän omia tiedostoja muokataan. Tämä onnistuu hookien eli koukkujen avulla. Ne tarjoavat ennalta määriteltyjä kohtia, joihin teeman tai lisäosan oma koodi voi…

Koukkujen avulla voit esimerkiksi lisätä hallintapaneeliin ilmoituksen, muuttaa automaattisen otteen pituutta tai tarjota oman lisäosan käyttäjille mahdollisuuden muokata sen toimintaa.

WordPressissä on kaksi pääasiallista koukkutyyppiä: action ja filter. Niiden ero liittyy siihen, halutaanko suorittaa jokin tehtävä vai käsitellä eteenpäin välitettävää arvoa. Kun tämä ero tulee tutuksi, myös monet teemojen ja lisäosien koodiesimerkit muuttuvat ymmärrettävämmiksi.

Mitä koukku tarkoittaa käytännössä?

Koukku on nimetty kohta ohjelman suorituksessa. WordPress, teema tai lisäosa kutsuu kyseistä kohtaa, jolloin siihen liitetyt funktiot pääsevät suorittamaan oman osuutensa.

Koukkuun liitettävää funktiota kutsutaan callbackiksi eli takaisinkutsufunktioksi. Se on tavallinen PHP-funktio, jonka WordPress kutsuu sopivassa tilanteessa.

Kokonaisuuteen kuuluu kolme asiaa:

Koukun nimi kertoo, mihin tapahtumaan tai käsittelyvaiheeseen liitytään.
Oma funktio määrittelee suoritettavan koodin.
Rekisteröinti yhdistää funktion kyseiseen koukkuun.

Pelkkä funktion kirjoittaminen ei vielä saa sitä toimimaan oikealla hetkellä. Myös rekisteröinti ja koukun myöhempi käynnistyminen tarvitaan. WordPressin koukkujen toimintaperiaate

Action suorittaa tehtävän

Action-koukku sopii tilanteeseen, jossa halutaan tehdä jotakin tietyssä suoritusvaiheessa. Tehtävä voi olla esimerkiksi asetuksen rekisteröiminen, tyylitiedoston lataamisen määrittely tai ilmoituksen näyttäminen.

Oma funktio liitetään action-koukkuun add_action()-funktiolla:

function oma_sivusto_yllapitoilmoitus() {
    if ( ! current_user_can( 'manage_options' ) ) {
        return;
    }

    echo '<div class="notice notice-info"><p>';
    echo esc_html( 'Muista tarkistaa varmuuskopiot.' );
    echo '</p></div>';
}

add_action(
    'admin_notices',
    'oma_sivusto_yllapitoilmoitus'
);

Esimerkki näyttää ilmoituksen hallinnan ilmoitusalueella käyttäjille, joilla on asetusten hallintaan tarvittava oikeus. esc_html() käsittelee tekstin turvalliseen muotoon HTML-tulostusta varten.

Actionin palautusarvoa ei käytetä koukun tuloksena. Funktion alussa oleva return on silti sallittu: tässä se lopettaa toiminnon, jos käyttäjällä ei ole tarvittavaa oikeutta. Action-koukkujen käyttö

Filter käsittelee arvoa ja palauttaa sen

Filter-koukku sopii tilanteeseen, jossa olemassa olevaa tietoa halutaan muuttaa ennen sen myöhempää käyttöä. Arvo voi olla esimerkiksi teksti, numero, taulukko tai asetus.

Seuraava esimerkki muuttaa automaattisesti muodostettavan artikkeliotteen pituuden:

function oma_sivusto_otteen_pituus( $pituus ) {
    return 30;
}

add_filter(
    'excerpt_length',
    'oma_sivusto_otteen_pituus',
    20
);

Funktio vastaanottaa aiemman pituuden, mutta palauttaa sen tilalle arvon 30. Tämä ei leikkaa tietokantaan tallennettua artikkelia eikä lyhennä käsin kirjoitettua otetta.

Filterissä palautus on olennainen osa toimintaa. Jos arvoa ei tarvitse muuttaa, palauta alkuperäinen arvo. Älä käytä echo-komentoa palauttamisen korvikkeena, koska tulostaminen ja arvon välittäminen ovat eri asioita. Filter-koukkujen käyttö

Actionin ja filterin erot rinnakkain

Koukkutyyppien käytännön erot voi hahmottaa seuraavasti:

Ominaisuus	Action	Filter
Tarkoitus	Suorittaa tehtävä	Käsitellä arvoa
Rekisteröinti	`add_action()`	`add_filter()`
Käynnistäminen	`do_action()`	`apply_filters()`
Palautusarvo	Ei käytetä koukun tuloksena	Välitetään seuraavaan käsittelyvaiheeseen
Tavallinen esimerkki	Hallintailmoituksen näyttäminen	Otteen pituuden muuttaminen

Action ei tarkoita, että funktion pitäisi aina tulostaa jotakin. Se voi esimerkiksi rekisteröidä ominaisuuden tai päivittää tietoa.

Filterin tarkoitus puolestaan on käsitellä sille annettua arvoa hallitusti. Sivuvaikutuksia, kuten sähköpostin lähettämistä filterin sisältä, kannattaa välttää. Sama filteri voi suorittua useita kertoja, jolloin myös lähetys voisi toistua.

Prioriteetti määrää suoritusjärjestyksen

Samaan koukkuun voi liittyä useita funktioita. Niiden järjestystä ohjaa rekisteröinnin kolmas argumentti eli prioriteetti.

Pienempi numero suoritetaan aikaisemmin. Oletusarvo on 10, ja samalla prioriteetilla olevat funktiot suoritetaan niiden rekisteröintijärjestyksessä.

add_filter( 'excerpt_length', 'oma_lyhyt_ote', 10 );
add_filter( 'excerpt_length', 'oma_pidempi_ote', 20 );

Jos molemmat funktiot palauttavat kiinteän pituuden, myöhemmin suoritettu määrää lopputuloksen. Jos jälkimmäinen laskee arvon saamansa syötteen perusteella, molemmat vaikuttavat tulokseen. Prioriteetti ja argumentit

Suuri prioriteettiluku ei takaa, ettei mikään muu muuttaisi arvoa myöhemmin. Selvitä ensin, mitkä muut toiminnot käyttävät samaa koukkua.

Koukun välittämät argumentit tuovat lisätietoa

Koukku voi välittää callbackille useita argumentteja. Ensimmäinen filter-argumentti on muokattava arvo, ja seuraavat voivat tarjota päätöksentekoon tarvittavaa taustatietoa.

Rekisteröinnin neljäs argumentti kertoo, kuinka monta argumenttia oma funktio vastaanottaa:

add_filter(
    'oma_sivusto_kortin_otsikko',
    'oma_sivusto_muokkaa_kortin_otsikkoa',
    10,
    2
);

function oma_sivusto_muokkaa_kortin_otsikkoa(
    $otsikko,
    $artikkeli_id
) {
    if ( 123 === (int) $artikkeli_id ) {
        return 'Aloita tästä';
    }

    return $otsikko;
}

Tämä on omaan koukkuun perustuva esimerkki. Se toimii vasta, kun jossakin kutsutaan samannimistä filteriä ja välitetään sille otsikko sekä artikkelin tunniste.

Argumenttimäärän kasvattaminen ei luo uusia tietoja. Käytettävissä ovat vain koukun lähettämät argumentit.

Omilla koukuilla voi tehdä koodista laajennettavaa

Omaan lisäosaan voidaan lisätä filteri kohtaan, jossa otsikko valmistellaan:

$otsikko = apply_filters(
    'oma_sivusto_kortin_otsikko',
    get_the_title( $artikkeli_id ),
    $artikkeli_id
);

echo esc_html( $otsikko );

Ilman liitettyjä callbackeja alkuperäinen otsikko säilyy. Edellisen esimerkin filter-funktio puolestaan muuttaa artikkelin 123 otsikkoa tässä tulostuskohdassa.

Vastaavasti oma tapahtuma voidaan ilmoittaa actionilla:

do_action(
    'oma_sivusto_raportti_valmis',
    $raportti_id
);

Kutsu sijoitetaan kohtaan, jossa raportti on todella valmistunut. Se ei itsessään muodosta raporttia tai tarkista onnistumista. Omien koukkujen luominen

Nimeä omat koukut yksilöllisellä etuliitteellä ja kuvaa niiden argumentit. Näin toinen kehittäjä tietää, millaista tietoa hän saa käsiteltäväkseen.

Koodin lataushetki vaikuttaa toimintaan

Callback täytyy rekisteröidä ennen kuin sen kohteena oleva koukku suoritetaan. Myöhässä lisätty funktio ei käynnisty takautuvasti.

Toisaalta liian aikaisin suoritettavassa koukussa kaikki WordPressin tiedot eivät vielä ole käytettävissä. Esimerkiksi sivupyynnön tyyppiä koskevia tarkistuksia ei voi sijoittaa mihin tahansa käynnistysvaiheeseen.

Kun toiminto ei käynnisty, tarkista:

Ladataanko oma PHP-tiedosto?
Onko koukun nimi kirjoitettu oikein?
Onko rekisteröinti tehty ajoissa?
Suoritetaanko koukku kyseisessä pyynnössä?
Lopettaako jokin ehto funktion liian aikaisin?

Erota toisistaan funktion rekisteröinti ja sen suorittaminen. Rekisteröintirivi voi toimia oikein, vaikka callbackia ei kyseisellä sivulla koskaan kutsuttaisi.

Koukkuun liitetyn toiminnon voi poistaa

Aiemmin rekisteröity callback voidaan irrottaa remove_action()– tai remove_filter()-funktiolla:

remove_filter(
    'excerpt_length',
    'oma_sivusto_otteen_pituus',
    20
);

Poistossa tarvitaan sama callback ja prioriteetti kuin rekisteröinnissä. Lisäksi poistamisen täytyy tapahtua rekisteröinnin jälkeen mutta ennen sitä suoritusta, johon haluat vaikuttaa. Koukkujen poistaminen

Nimetty funktio on usein helppo tunnistaa ja irrottaa. Nimettömän funktion poistamiseen tarvitaan viittaus samaan funktio-olioon, joten uuden samanlaisen funktion kirjoittaminen ei riitä.

Vältä kaikkien callbackien poistamista koukusta, jos haluat muuttaa vain yhtä toimintoa. Muuten saatat poistaa samalla muiden lisäosien tarpeellisia ominaisuuksia.

Sijoita muutokset ylläpidettävään paikkaan

Sivuston toiminnalliset muutokset kannattaa yleensä sijoittaa omaan lisäosaan. Näin ne säilyvät käytössä myös teeman vaihtuessa.

Ulkoasuun kiinteästi liittyvä muutos voi kuulua lapsiteemaan. Älä muokkaa WordPressin ydintiedostoja tai ulkopuolisen lisäosan lähdekoodia vain koukun lisäämistä varten, sillä päivitys voi korvata muutokset.

Koodiesimerkit ovat PHP-koodia, eivät lohkoeditoriin liitettäviä sisältöjä. Käytä yksilöllisiä funktionimiä, jotta ne eivät törmää muiden lisäosien määrittelyihin.

Kirjoita myös lyhyt kommentti muutoksen tarkoituksesta. Myöhemmin on hyödyllisempää tietää, miksi otteen pituutta muutetaan, kuin nähdä kommentti, joka vain toistaa funktion nimen.

Testaa sekä haluttu vaikutus että rajaukset

Kokeile muutosta ensin testiympäristössä. Tarkista, että toiminto vaikuttaa oikeaan näkymään ja jättää muut tilanteet ennalleen.

Filteristä pitää palautua oikeantyyppinen arvo jokaisessa suoritushaarassa. Actionissa puolestaan on varmistettava, ettei sama tehtävä toteudu vahingossa monta kertaa.

Huomioi erityisesti tallennuskoukut. Jos callback tallentaa saman sisällön uudelleen, se voi käynnistää itsensä toistuvasti. Myös automaattitallennukset ja versiohistoria voivat vaatia erillisiä rajauksia.

Pidä callbackit pieninä ja selkeinä. Kun yksi funktio vastaa yhdestä ymmärrettävästä tehtävästä, suoritusjärjestyksen, virheiden ja yhteensopivuuden tutkiminen helpottuu.

Liittyvät kategoriat

Artikkeleita 2 032 artikkelia IT 1 958 artikkelia Kotisivut 1 207 artikkelia Nettisivut 1 207 artikkelia Verkkokehitys 1 273 artikkelia Verkkosivut 1 406 artikkelia Verkkotyökalu 1 186 artikkelia WordPress 1 226 artikkelia