07 09 10 Użycie filtrów w Wordpresie

Jak zawsze dodany przez : Sylwek, komentarze: ( 5 )

WordPress jest w znacznej mierze oparty na filtrach i akcjach. Niniejszy wpis ma na celu objaśnienie zasady działania oraz sposób użycia tych pierwszych.

Treść poniżej przeznaczona jest dla osób, które znają jezyk PHP na poziomie co najmniej podstawowym.

Co to jest filtr ?

Filtr to rodzaj haka, który WordPress wykorzystuje i udostępnia do modyfikacji łańcuchów znaków przed ich zapisem do bazy danych lub wyświetleniem w przeglądarce. WordPress posiada dwa rodzaje haków, tj. filtry i akcje.
Modyfikacje danych z udziałem filtra są dokonywane za pomocą metody klasy PHP lub funkcji modyfikującej. Możliwe jest wykorzystanie już istniejeącego kodu, niezależnie od tego czy pochodzi on z jądra Wordpresa, funkcji PHP czy klas tworzonych przez osoby trzecie. Innymi słowy podczepić do filtra da się wszystko co ujęto w kod języka PHP.

Funkcja filtra pownna przyjmować co najmniej jeden argument ( za wyjątkiem przypadku gdy modyfikuje ona globalne zmienne) i zwracać łańcuch znaków. Pod jeden filtr można podłączyć wiele funkcji modyfikujących, które kolejno będą zmieniać podane im dane. Z racji tego, że funkcje filtrów są skolejkowane, należy pamiętać, o tym, że każda z nich powninien zwracać zmodyfikowane przez sibie dane. Jeżeli w którejś z nich zapomnimy zwrócić dane cały filtr zwróci null.

Umiejscowienie filtrów w kodzie Wordpresa

Funkcje lub klasy z metodami dla filtrów mogą zostać umieszczone w którymś z plików wtyczki lub w functions.php aktywnego motywu. Na potrzeby tego wpisu użyta zostanie ta druga opcja.

Rejestracja funkcji dla filtra

Po zdefiniowaniu funkcji modyfikującej dane wejściowe w pliku functions.php należy ją dodać do filtra co realizuje się za pomocą funkcji add_filter

Funkcja add_filter przyjmuje cztery argumenty, z których tylko dwa pierwsze są wymagane i są to:
nazwa filtra ( np. the_title, the_content czy pre_kses ),
nazwa funkcji modyfikująca dane ( np. my_func ) ,
waga filtra (np. 1 ),
liczba argumentów jaką przyjmuje funkcja podana jako drugi argument ( np. 2) .

Waga funkcji filtra służy określeniu jej miejsca w kolejce do modyfikacji danych, im mniejsza jej wartość tym później funkcja zostanie wywołana.

Popatrzmy na trywialny przykład, który używa filtra the_title z funkcją, która dodaje gwiazdkę przed pierwszą i za ostatnia literą tytułu wpisu. Kod powinien znaleźć się pliku functions.php

 add_filter("the_title","modify_the_title")
 function modify_the_title($title){
  return '*'. $title . '*';
 }

Wywoływanie funkcji dla filtra

Załóżmy, że chcemy dodać do filtra funkcję modyfikującą, która jest domyślnie zdefiniowana w PHP.

W pliku functions.php umieszczamy linijke kodu jak poniżej:

add_filter('my_own_title_hook',"str_repeat",10,2);

następnie w jednym z plików aktywnego motywu, np. index.php dodajemy kod:

<?php echo apply_filters('my_own_title_hook',get_the_title(),3); ?>

Powyższa linijka kodu, gdy umieszczona w pętli Wordpresa, wyświetli tytuł każdego wpisu 3 razy.

Przykład powyżej, mimo, że niezbyt użyteczny, pokazuje jak dodać własny filtr i wywołać doczepione do niego funkcje wykorzystując funkcję apply_filters.

Funkcja apply_filters, która jako argumenty przyjmuje kolejno nazwę filtra oraz argumenty dla funkcji modyfikującej ( w ilości określonej w funkcji add_filter ) pozwala wywołać wszystkie funkcje podczepione do filtra, jak również tworzyć własne filtry.

Wyrejestrowywanie funkcji filtrów

Do wyrejestrowywania funkcji dla filtra służy funkcja remove_filter. Funkcja ta przyjmuje kilka argumentów i są to kolejno:
nazwa filtra, dla którego dana funkcja ma zostać wyrejstrowana (np. the_title),
nazwa funkcji do wyrejestrownia (np. my_func),
waga wyrejestowywanej funkcji, tak jak została zdefiniowana w funkcji add_filter (np. 3),
liczba akceptowanych argmentów ( np . 3).

Dwa ostatnie argumenty są opcjonalne.

Załóżmy, że chcemy wyrejestrować funkcje odpowiedzialne za wyświetlanie emotikonów w wypisach wpisu.
czego można dokonać umiesczając kod jak poniżej w pliku funcitons.php.

Wyrejestrowywanie wszystkich funkcji modyfikujących dla filtra

Wszystkie funkcje dla określonego filtra można usunąć z pomocą funkcji remove_all_filters.
Funkcja ta przyjmuje nazwę filtra jako pierwszy argument i opcjonalnie wagę funkcji, które mają być usunięte (jak sprecyzowane w funkcji add_action).

Wszystkie funkcje dla filtra the_author można usunąć z pomocą kodu jak poniżej:

remove_all_filters("the_title")

Powyższy kod należy umieścić w pliku functions.php.

Zdefiniowane filtry i zarejestrowane funkcje dla nich

Pełną tablicę filtrów można zobaczyć umiesczając poniższy kod w pliku functions.php

global $wp_filter,$merged_filters;
var_dump($wp_filter);
var_dump($merged_filters);
die();

Nazwy funkcje zarejestrowanych dla wybranego filtra można sprawdzić przy pomocy kodu jak poniżej:

global $wp_filter,$merged_filters;
var_dump($wp_filter['tu_nazwa_filtra]);
die();

Jeżeli chcemy programistycznie sprawdzić czy określona funkcja została dodana do filtra, możemy skorzystać z funkcji has_filter, która przyjmuje nazwę filtra jako pierwszy argument oraz nazwę funkcji do wyszukania jako drugi i zwraca jej wagę lub false w przypadku jej braku.

if(!has_filter('the_title','convert_to_uppercase')){
  add_filter('the_title','convert_to_uppercase');
}

Filtrownanie danych w Wordpresie to dość rozległy temat, powyższe przykłady w żadnym stopniu nie wyczerpują tematu, pokazują jednak jak korzystać z fantastycznej funkcjonalności jaką oferują filtry. Zaprasza do testowania.

Listę domyślnie zdefiniowanych filtrów w Wordpresie można znaleźć w pliku wp-includes/default-filters.php.

Więcej szczegółów na temat poszczególnych filtrów można znaleźć na tej stronie kodeksu Wordpresa.

Kategorie: wordpress
Tagi: akcja, filtr, functions.php