Wprowadzenie do tworzenia wtyczek WordPress na przykładzie formularza propozycji użytkownika

 Sie, 14 - 2015   liczba komentarzy: 2   CMS

WordPress pluginWordPress jest jednym z najpopularniejszych systemów zarządzania treścią. Jest tak między innymi dlatego, że umożliwia szybkie i łatwe rozszerzanie funkcjonalności poprzez plugin-y, czyli po polsku wtyczki. W sieci można znaleźć wiele dodatków dla tego CMSa. Jednaka co w przypadku, gdy żadna z nich nie spełnia wszystkich naszych oczekiwań? Wtedy warto pomyśleć o napisaniu swojej własnej.

 

Tworzenie rozszerzeń WordPress to temat rzeka, dlatego ten poradnik nie porusza wszystkich możliwych zagadnień z tym związanych, a jedynie wprowadza w świat wtyczek WP.

Jako, że najlepiej uczyć się na przykładach, w tym artykule przedstawię, w jaki sposób można napisać prostą wtyczkę dodającą formularz, przy pomocy którego użytkownik będzie mógł przekazać nam swoją sugestię, propozycję lub pomysł dotyczącą naszej strony lub bloga.

 

Podstawy tworzenia wtyczek

Miejsce, w którym piszemy wtyczki znajduje się w katalogu …/wp_content/plugins. Należy w nim utworzyć osobny katalog o nazwie pisanego rozszerzenia, a w nim plik .php, o takiej samej nazwie. Jest to główny plik, od którego system zacznie uruchamianie naszego kodu. Jeżeli będziemy chcieli w przyszłości opublikować wtyczkę, ważne jest żeby jej nazwa była unikalna, tzn. aby nie zdarzył się konflikt nazewnictwa z innymi dostępnymi wtyczkami.

Pierwsze linijki kodu to komentarz opisujący nasz plugin. Dostarcza systemowi takich informacji jak nazwa, opis, autor, wersja, strona projektu, informacje o licencji, itp. Informacje te będą pokazane w panelu administratora w dziale zarządzania wtyczkami.

WordPress dostarcza nam szereg narzędzi, przy pomocy których jesteśmy w stanie dodać lub zmodyfikować dowolną funkcjonalność i to bez ingerencji w kod samego systemu. Oczywiście istnieje możliwość rozszerzania kodu źródłowego CMSa o własne funkcje, jednak jest to bardzo złe rozwiązanie i do tego mocno niepraktyczne (tak zmodyfikowany kod byłoby ciężko kontrolować, aktualizować oraz udostępniać innym osobom). O wiele lepszym pomysłem jest oddzielenie swojego kodu od źródła WP, a następnie połączenie go z systemem przy pomocy „zaczepów” tzw. hook-ów.

 

 

Hook jest to właśnie słowo klucz i cała esencja tworzenia plugin-ów w systemie WordPress. Przy pomocy hook-ów zmieniamy funkcjonalność naszej strony lub dodajemy swoje rozwiązania. Rozróżniamy dwa podstawowe typy hooków:

  • hook akcji – action – umożliwia dodanie własnej funkcjonalności, obok już istniejącej w systemie
  • hook filtra – filter – umożliwia modyfikację funkcjonalności systemu

Działanie hooków najlepiej pokazać na przykładzie. Załóżmy, że chcielibyśmy w nagłówkach wpisów naszego bloga dołączyć znaczniki protokołu Open Graph, tak aby wskazać portalom społecznościowym jaką treść wpisu mają wyświetlać na swoich stronach.

W pierwszej kolejności piszemy funkcję, której zadaniem będzie wypisanie znaczników w szablonie bloga.

Funkcja wypisuje kolejno poszczególne znaczniki, korzystając przy tym z szeregu funkcji dostępnych w systemie WordPress. Następnie należy wskazać, w którym miejscu na stronie dana funkcja ma zostać uruchomiona.

Hook akcji dodajemy przy pomocą powyższej funkcji, której dwa główne parametry to tag hook-a (wskazuje miejsce uruchomienia, w tym przypadku nagłówek strony) oraz nazwa funkcji.

Teraz wystarczy jedynie w panelu administratora uruchomić wtyczkę i gotowe. Dodaliśmy całkiem nową funkcjonalność bez ingerencji w kod źródłowy WP lub szablonu. Co więcej, tak napisany plugin możemy wykorzystać w innych projektach.

Hook filtra używamy w podobny sposób. Załóżmy, że na końcu znacznika tytułu chcielibyśmy dopisać jakąś stałą treść. Najpierw piszemy funkcję, która będzie zwracała tytuł.

Dodajemy filtr, modyfikujący zawartość tytułu.

Po uruchomieniu wtyczki, przy każdy użyciu funkcji the_title w kodzie strony, treść wynikowa będzie dodatkowo zmieniana przez nasz plugin.

Funkcji, z których możemy korzystać podczas tworzenia naszych rozszerzeń jest masa i nie sposób je wszystkie przedstawić, a tym bardziej zapamiętać. Dlatego stałym źródłem wiedzy, podczas programowania w WP jest dokumentacja: https://codex.wordpress.org oraz oczywiście wujek Google.

 

Formularz propozycji użytkownika – plugin „Suggestion Box”

Zabieram się za napisanie mojej wtyczki, o której wspominałem na początku artykułu. Nazwałem ją „suggestion box”, czyli pudełko sugestii. Użytkownik będzie mógł wypełnić i wysłać prosty formularz, przedstawiając swoje pomysły na rozwój strony. Informacje te zostaną zapisane w bazie danych, po czym administrator będzie miał do nich dostęp z poziomu panelu zarządzania WP.

W pierwszej kolejności w katalogu …/wp_content/plugins tworzymy katalog suggestions-box, a w nim plik PHP o tej samej nazwie: suggestion-box.php, i dodajemy do niego komentarz opisujący.

Nasza wtyczka została utworzona i jest widoczna na liście w zakładce „Wtyczki” w panelu administratora.

Wtyczka WP gotowa do uruchomienia

Jak widać wszystkie informacje o rozszerzeniu są widoczne obok nazwy wtyczki, która jest gotowa do uruchomienia. Na razie jednak nie ma to większego sensu, ponieważ jest ona pusta. Zabierzmy się więc za napisanie jej podstawowej funkcjonalności.

W pierwszej kolejności stworzymy klasę, która będzie odpowiadała za komunikację z bazą wtyczki z bazą danych. W tym celu posłużymy się klasą wpdb, która jest zbiorem funkcji używanych do interakcji z bazą danych. Instancja tej klasy jest dostępna poprzez zmienną globalną $wpdb. W katalogu wtyczki stwórzmy kolejny katalog includes, a w nim skrypt SuggestionBox.php, zawierający model naszego rozszerzenia.

Klasa zawiera dwie właściwości prywatne, konstruktor oraz cztery metody, które będą wykorzystywane podczas pisania głównego kodu plugin-u.

Właściwości:

  • $table – nazwa tabeli w bazie danych
  • $wpdb – instancja klasy, dostarczającej interfejs to komunikacji z bazą danych

Konstruktor – służy do ustawiania nazwy tabeli oraz obiektu wpdb. Do nazwy tabeli na początek doklejany jest prefix, który był podawany podczas instalacji WordPress-a na serwerze (domyślnie wp_).

Metody:

  • createTable() – tworzy tabele sugestii w bazie danych
  • removeTable() – usuwa tabele sugestii z bazy danych
  • addSuggestion($data) – dodaje nową sugestię
  • getAllSuggestions() – zwraca wszystkie sugestie z bazy danych

Przystępujemy do napisania wtyczki. Nie będzie ona bardzo rozbudowana więc cały kod spokojnie zmieści się w pliku głównym rozszerzenia.

W pierwszej kolejności dołączamy napisany przed chwilą model.

Następnie dodajemy funkcje, które będą uruchamiane podczas włączania i wyłączania wtyczki. Ich zadaniem będzie tworzenie i usuwanie tabeli w bazie danych.

Po włączeniu plugin-u w systemie widzimy, że nowa tabela została utworzona automatycznie w bazie danych.

Nowo utworzona tabela wtyczki Suggestion Box w bazie danych

Utwórzmy funkcję odpowiedzialną za wyświetlanie formularza dla użytkownika.

Jak widać jest to zwykły kod HTML formularza, wyświetlającego na ekranie 3 pola do uzupełnienia przez użytkownika: imię, email oraz sugestię. Dane te, wraz z aktualną datą będą zapisywane do bazy danych.

Teraz napiszmy funkcję obsługującą formularz. Jej zadaniem będzie przechwycenie danych wysyłanych przez użytkownika, przeprowadzenie podstawowej walidacji (pole sugestii musi być uzupełnione) oraz zapisanie danych w tabeli.

Jeżeli pole sugestii nie zostało uzupełnione, użytkownik zobaczy komunikat błędu, natomiast jeżeli wszystko jest ok, to wpis zostanie dodany, dane formularza wyczyszczone, a użytkownik zobaczy potwierdzenie.

Jak widać w powyższych funkcjach, w miejscach które łączę się z bazą, wykorzystuje wcześniej napisany model. Jak widać wykorzystuję również funkcję __(), wszędzie tam gdzie wypisuje jakiekolwiek informacje dla użytkownika. Funkcja ta zwraca tekst automatycznie przetłumaczony przez system zgodnie z ustawieniami języka. Będzie ona przydatna w przyszłości, gdy wpadnę na pomysł wprowadzenia kilku wersji językowych.

Mamy już wszystkie potrzebne funkcje, dodajmy jeszcze style css, które odpowiednio zmienią wygląd niektórych elementów formularza. Utwórzmy nowy katalog css, a w nim plik style.css. Następnie do kodu wtyczki dopiszmy hook akcji i funkcję, których zadaniem będzie dodanie styli do nagłówka strony.

Na uwagę zasługuje funkcja wp_enqueue_style, która przyjmuje kilka parametrów:

  • nazwa identyfikująca styl
  • ścieżka do pliku css
  • tablica zależności
  • wersja
  • media, np. screen, print, All

W podobny sposób można dodać do strony dowolny skrypt JavaScript, wykorzystując funkcję wp_enqueue_script.

 

 

Ostatnim krokiem jest zebranie powyżej napisanych funkcji do kupy i pokazanie wstawienie formularza w wybrane miejsce na stronie. W tym celu dodam hook shortcode (nie był wcześniej wspomniany), którego zadaniem jest przypisanie wyniku wskazanej funkcji do specjalnego tagu, który później można użyć na dowolnej stronie.

Powyższy kod łączy napisane wcześniej funkcje w jedną, dostępną pod Tagiem suggestionBox. Teraz wystarczy wybrać stronę, na której chcemy pokazać formularz i gotowe.

Dodanie shortcode wtyczki suggestion box na stronie

Po wejściu na wybraną stronę, pojawia się nasz formularz.

Formularz wtyczki suggestion box

Oczywiście należy przetestować działanie nowo powstałej wtyczki. Po poprawnym wypełnieniu formularza, powinien pojawić się komunikat potwierdzający wysłanie wiadomości, a wpis powinien zostać dodany do tabeli.

Wypełniony formularz wtyczki suggestion box

Po wysłaniu:

Potwierdzenie wysłania formularza suggestion box

A tak wygląda formularz, w przypadku gdy nie wypełnimy pola sugestii:

Błąd formularza wtyczki suggestion box

Jak widać po wysłaniu niepoprawnie wypełnionego formularza, wypełnione dane nie znikają, mimo przeładowania strony.

 

Panel administratora

Na sam koniec zostało stworzenie strony administratora, która będzie pokazywała listę wszystkich sugestii zapisanych w bazie danych.

W pierwszej kolejności dodajemy hook akcji do nawigacji administratora. Wykorzystujemy funkcję add_menu_page, której zadaniem jest dodanie nowego odnośnika do paska nawigacji oraz podpięcie wskazanej funkcji odpowiedzialnej za wyświetlenie zawartości tej utworzonej strony. Funkcja ta pobiera wszystkie wpisy z bazy danych i wyświetla je w postaci tabeli.

Panel administratora suggestion box

 

Podsumowanie

W tym artykule starałem się przedstawić sposób działania wtyczek oraz pokazałem praktyczne wykorzystanie API WordPress-a do stworzenia swojego własnego rozszerzenia. Jak widać nie jest to szczególnie trudne zadanie. Oczywiście omówiony przykład można na różne sposoby rozszerzyć, np. rozbudować panel admina o możliwość sortowania i usuwania wpisów, rozszerzyć formularz o dodatkowe pola, dopisać wysyłanie danych asynchronicznie lub lepiej napisać walidacje przesyłanych danych.

Opisane funkcje stanowią jedynie ułamek możliwości, jakie niesie ze sobą ten CMS. Przy pomocy hook-ów i funkcji jakie dostarcza, można tworzyć naprawdę rozbudowane aplikacje. Oczywiście wymaga to o wiele lepszej organizacji kodu oraz dogłębne zapoznanie się z dokumentacją.

 

Zachęcam do nauki tworzenia własnych wtyczek. Nigdy nie wiadomo, kiedy taka umiejętność może nam się przydać. Pozdrawiam wszystkich czytających i oczywiście proszę o komentarze.


 Komentarze liczba komentarzy: 2

  • Patryk pisze:

    Świetnie opisane, od dłuższego czasu szukałem czegoś opisanego w tak prosty sposób, kolokwialnie ujmując manual jest opisany w sposób zrozumiały dla „przeciętnej małpy” 🙂 Dodatkowo w języku polskim.

    Tworzę w oparciu o ten post swoją wtyczkę do WordPress’a pozwalającą na dokonywanie rezerwacji i mam 2 pytania:

    1. W jaki sposób należy edytować fragment wywołujący w menu panelu Administracyjnego dodatkowy link, tak aby otrzymać sub-menu (przykład: Ustawienia / Posty / Wygląd, po kliknięciu na odnośnik mamy do dyspozycji kilka różnych podstron)

    2. Zakładając że chciałbym aby plugin miał nieco większą funkcjonalność niż tylko odczytanie rekordów z bazy, w jaki sposób powinienem zdefiniować prawidłowo funkcję oraz później się do niej odwołać aby dodać w wyświetlonej tabeli button/odnośnik pozwalający na update danej komórki w bazie. Powiedzmy że mam w tabeli bazy danych pole confirmation_status i powiedzmy, że chciałbym aby po kliknięciu na odnośnik archiwizuj, pole to zaktualizowało swoją wartość tylko dla wskazanego wpisu z 0 na 1.

    • Patryk pisze:

      pierwszy problem rozwiązałem – wystarczyło wywołać wordpress’ową funkcję add_submenu_page(), jednak dalej nie mam pomysłu jak rozwiązać drugi, byłbym wdzięczny za wszelkie wskazówki 🙂


  • Dodaj komentarz

    Twój adres email nie zostanie opublikowany.