Zaczepy – akcje i filtry w WordPress

Zaczepy czyli akcje i filtry w WordPress są ważną funkcjonalnością. Dzięki nim możemy zaczepiać własny kod w danym momencie wczytywania WordPress lub modyfikować dane wyjściowe, bez potrzeby ruszania plików źródłowych WP.

Ten wpis jest pobocznym artykułem do serii WordPress motyw od podstaw, w którym szerzej omawiam zaczepy. O zaczepach pierwszy raz była mowa przy okazji załączania plików CSS i JS do motywu WordPress.

Zaczepy

Hooks are a way for one piece of code to interact/modify another piece of code. They make up the foundation for how plugins and themes interact with WordPress Core, but they’re also used extensively by Core itself.

Zaczepy dzielimy na dwa typy: akcje i filtry.

Akcje

Zaczepy akcji pozwalają na wywołanie funkcji w danym momencie procesu wczytywania WordPress (np. w momencie załączania styli i skryptów lub w momencie, gdy WordPress jest całkowicie załadowany itp..). Akcje zazwyczaj dodają nowe funkcjonalności lub rozszerzają już istniejące.

Proces dodawania akcji polega na napisaniu w PHP własnej funkcji – tutaj jest to funkcja crocoder_scripts(), która załącza arkusz stylów do motywu. Następnie naszą funkcję trzeba przypisać do zaczepu, który wykona wywołanie funkcji.

// Zaczep akcji
function crocoder_scripts(){
  wp_enqueue_style( 'crocoder-style', get_stylesheet_uri() );
}
add_action( 'wp_enqueue_scripts', 'crocoder_scripts' );

Funkcję przypisujemy do odpowiedniej akcji za pomocą add_action() :

//Zaczepianie funkcji do danej akcji
add_action( 
    string $tag, //nazwa zaczepu akcji, do której zaczepiamy naszą funkcję
    callable $function_to_add, //nazwa funkcji, która będziemy wywoływać
    int $priority = 10, //kolejność, w jakiej wywoła się funkcja zaczepiona dla danej akcji (im niższa tym szybciej)
    int $accepted_args = 1 //liczba argumentów, które przyjmuje funkcja
);

W przykładzie mam funkcję o nazwie crocoder_scripts, która za pomocą add_action jest rejestrowana do zaczepu akcji o nazwie wp_enqueue_scripts. To oznacza, że funkcja crocoder_scripts wykona się w momencie załączania przez WordPress skryptów.

Lista akcji dostępnych w WP: https://codex.wordpress.org/Plugin_API/Action_Reference

Filtry

Zaczepy filtrów pozwalają na modyfikację danych zwracanych przez inne funkcje. Podobnie jak z akcją, tutaj też tworzymy w PHP własną funkcję a następnie przypisujemy ja do zaczepu filtru. Po zarejestrowaniu do zaczepu filtru, funkcja staje się filtrem.

//Tworzenie filtra
function crocoder_custom_excerpt_length( $length ) {
    return 20;
}
add_filter( 'excerpt_length', 'crocoder_custom_excerpt_length' );

Funkcja crocoder_custom_excerpt_length() modyfikuje liczbę wyrazów tzw. 'zajawki’ wyświetlanej przez the_excerpt(). Domyślne 55 wyrazów skraca do 20 wyrazów a końcowy rezultat zwraca poprzez return.

Funkcja wywołująca zaczep filtru:

add_filter(
    string $tag, //nazwa zaczepu filtru
    callable $function_to_add, //nazwa funkcji filtru
    int $priority, //kolejność w jakiej będą zastosowane filtry
    int $accepted_args //liczba parametrów przekazanych do funkcji filtru
);

Lista filtrów, które udostępnia WordPress: https://codex.wordpress.org/Plugin_API/Filter_Reference

Wiedza dodatkowa:
wszystkie akcje / filtry zarejestrowane dla danego zaczepu można wywołać funkcjami: do_action() – wywołuje zarejestrowane akcje oraz apply_filters() – wywołuje zarejestrowane filtry. To już jest wiedza przydatna raczej podczas tworzenia pluginów, w motywie, który powstaje w serii nie będę rejestrować własnych zaczepów, więc nie będę tego na razie szczegółowo omawiać.

Podsumowanie