Akcje WordPress

Akcje WordPress

Akcje WordPress to zagadnienie bardzo zbliżone do filtrów WordPress. Służą, w zasadzie, do tego samego. Do modyfikowania zachowań WordPress, bez ingerencji w kod samego systemu, czy też jakikolwiek kod osób trzecich. Pod warunkiem, że ktoś, kto ten kod pisał, raczy nam takich akcji dostarczyć. WordPress, jako taki, oferuje nam ich sporo, dobre wtyczki i szablony – również. Więc sporo nauki przed nami! WordPress daje nam na talerzu listę akcji, wywoływanych w trakcie normalnego uruchamiania WordPress (lista nie uwzględnia oczywiście akcji specyficznych dla szablonów i wtyczek).

Akcje, według niektórych programistów, są ważniejsze od filtrów. W mojej opinii są po prostu częściej wykorzystywane. Bez nich, w zasadzie, się nie da. Dlaczego? Otóż na przykład wtyczki – są uruchamiane dosyć wcześnie. I jeżeli w kodzie wtyczki spróbujemy na przykład odwołać się do użytkownika (choćby sprawdzić, czy jest zalogowany) to okaże się, że nie ma takiej możliwości.

Weźmy taki kod:

wpisany bezpośrednio w pliku wtyczki. Wiecie, co nam pokaże? Zero, niezależnie od tego, czy jesteśmy zalogowanym użytkownikiem, czy nie. A przecież, według dokumentacji, gdy jesteśmy zalogowani, ta funkcja powinna zwrócić ID bieżącego użytkownika. Więc czemu zwraca zero? Ano, dlatego że kod odpowiedzialny za sprawdzenie użytkownika jeszcze się nie wykonał. Możemy, oczywiście, używać tej funkcji, ale dopiero w odpowiednim momencie. Często jest to akcja init – nie raz jeszcze ją zobaczycie… Jak wynika z listy przedstawionej na stronie WordPress, akcja init następuje bezpośrednio po akcji set_current_user – więc wydaje się właściwym miejscem. Spróbujmy tak:

No, teraz – zakładając, że jesteśmy zalogowani – dostajemy piękny, sensowny i konkretny, numer ID użytkownika. Dodatkowo otrzymamy całą stronę i może to być mało czytelne, ale nie chodzi teraz ani o poprawność, ani o czytelność, tylko o fakt, że właśnie tak to działa.

No i właśnie wykorzystaliśmy pierwszą funkcję związaną z akcjami – add_action. A poznamy ich więcej. Ogólnie, do dyspozycji mamy: add_action, has_action, remove_action, remove_all_actions, did_action, do_action oraz do_action_ref_array.

Różnice

Czym więc różni się akcja od filtra? Filtry omówiliśmy, natomiast akcje nie są czarnymi skrzynkami. To tak, jakby okrzyk – hej, jestem akurat w tym miejscu wykonywania kodu, chcesz się przyłączyć? Pozwalają nam na wykonanie konkretnego kodu w konkretnym momencie działania WordPressa.

add_action

Z tej funkcji będziemy korzystać najczęściej, w każdym razie – na początku. Potem zresztą również. Bez niej praktycznie nie da się stworzyć szablonu lub wtyczki WordPress zaawansowanej bardziej od kijka drewnianego. Funkcja ta może przyjąć do czterech parametrów. Pierwszy, to nazwa akcji. Drugi – wywołanie (zobacz różne sposoby wywołań), trzeci (opcjonalny) to priorytet. Jeżeli nie zostanie ustawiony, WordPress przyjmie wartość domyślną – dziesięć. Czwarty, również opcjonalny, parametr to ilość argumentów przekazywana do akcji. Zwróćcie uwagę na ogromne wręcz podobieństwo do funkcji add_filter.

Im większą liczbę wstawisz jako priorytet, tym później (w kolejce danej akcji) się wykona. Traktuj to właśnie jak kolejkę. Kto pierwszy, ten szybciej.

Teraz zróbmy jakiś przykład. Oczywiście aby działał, musi być opakowany w jakąś wtyczkę, lub dodany do pliku functions.php aktualnie używanego szablonu (ale dopóki to nie jest Twój szablon, to go nie zmieniaj). Tutaj przeczytasz, jak stworzyć szkielet wtyczki. Po zamknięciu komentarza z opisem możesz dodać ten kod i zadziała! A co sobie zrobimy? Ot, choćby wyświetlanie w panelu administratora co udostępnia nasz szablon. Tak, mniej więcej, wygląda panel administratora teraz:

Możecie zauważyć, że jest to WordPress w wersji 5.0-alpha-43578, włączony motyw to Twenty Seventeen. Nic więcej się nie dzieje (poza działającymi wtyczkami Hello Dolly i Queen Inspirations). Wpisujemy sobie do naszej pseudo wtyczki taki kod:

I dostajemy widok z listą obsługiwanych przez szablon możliwości:

Ten kod należy w zasadzie czytać od tyłu. Funkcja is_admin() nie sprawdza, czy mamy do czynienia z administratorem! To częste nieporozumienie. Ale przypomnijcie sobie – na tym etapie WordPress jeszcze nie wie, czy użytkownik jest w ogóle zalogowany. Wie natomiast, czy zamierzamy wyświetlić front-end (część dla użytkownika) czy back-end (panel administratora) – i właśnie to zwraca nam ta funkcja. Jeżeli będzie wyświetlany panel administratora, to do akcji wp_dashboard_setup dodaj naszą funkcję moj_plugin_wp_dashboard_setup. Oczywiście, ponieważ korzystamy z funkcji WordPressa, moglibyśmy to zrobić i w innym miejscu. Jednak WordPress ma parę takich standardów, że pewne akcje należy wywoływać w odpowiednich miejscach. Będziemy sobie to jeszcze omawiać – aby korzystać z zasobów WordPress zgodnie ze standardami.

Co robi nasza funkcja? Ano, dodaje widżet (widget), który opisze nam możliwości aktualnie wybranego szablonu. Nie jest to funkcjonalność bardzo potrzebna, tym niemniej – pokazuje, ile możemy zrobić. Widżet następnie wywołuje naszą funkcję do wyświetlania danych, gdzie sobie pobieramy dane, porównujemy z listą ogólnie dostępnych możliwości a następnie wyświetlamy te, których na liście nie ma – dzięki temu obsłużymy tym kodem nawet najnowszą wersję WordPress.

Formalnie, jest to alias add_filter.

has_action

Teraz będzie niespodzianka, o której wcześniej nie wspomniałem, w każdym razie wprost, chcąc na spokojnie omówić absolutne podstawy akcji. Otóż akcje są w zasadzie tożsame z filtrami (o podobieństwie nadmieniałem wielokrotnie). I tak has_action jest de facto aliasem dla has_filter więc odsyłam do tej funkcji.

remove_action

To z kolei alias remove_filter.

remove_all_actions

Alias remove_all_filters.

did_action

To akurat nie jest alias, więc opisuję. Funkcja wymaga dokładnie jednego parametru, nazwy akcji. Zwraca wartość liczbową, odpowiadającą liczbie wywołań akcji. Czyli jeżeli akcja była wcześniej wywoływana trzy razy, funkcja zwróci trzy.

do_action

Wywołanie wszystkich funkcji, przypisanych do danej akcji. Nazwę akcji podajemy jako pierwszy parametr. Jako kolejne możemy podać w zasadzie dowolne dane, które chcemy przekazać do wykorzystania w momencie wykonywania kodu. Warto, w newralgicznych miejscach kodu, umieszczać takie wywołania, na pewno pomogą innym programistom.

do_action_ref_array

To takie wygodne uproszczenie funkcji do_action, które pozwala na przekazanie parametrów nie jako kolejnych argumentów funkcji, ale jako tablicy.