Wyjaśnienie, które za jakiś czas zniknie stąd: wpis ten pierwotnie opublikowany był na moim prywatnym blogu, przenoszę go jednak tutaj. Robię to z dwóch powodów. Po pierwsze chce tu scentralizować swoje wszystkie WordPressowe porady, porozrzucane w różnych miejscach sieci. Po drugie –  piszę właśnie kolejne poradniki, ale zajmuje mi to więcej czasu niż założyłem. Żeby zatem nie wyglądało na to, że zapał mi minął, wrzucam teraz ten wpis :)

Zauważyłem, że w sieci jest jakoś wyjątkowo mało poradników jak tworzyć pluginy do WordPressa, szczególnie po polsku (taki jest chyba tylko jeden). No to jest okazja by o czymś napisać :) Bo tak się składa, że wczoraj w ramach ćwiczeń napisałem sobie taki prosty plugin od zera. Teraz popatrzcie jak to zrobiłem i przy okazji nauczcie się sami :)

Założenia: robimy plugin wykopowy

Plugin ma być maksymalnie prosty (w końcu to nasze pierwsze dzieło), bez nadmiaru kodu. Plugin będzie dodawał pod naszymi wpisami odnośnik, który po kliknięciu doda naszą stronę do Wykopu. Dokładniej: wyświetli nam wykopową stronę dodawania z wypełnionymi już polami na odnośnik, tytuł i krótki opis.

Tworzymy plik .php

Utwórz katalog oraz plik .php wewnątrz jego. Katalog i plik powinny (ale nie jest to konieczne) nazywać się tak samo jak nasz plugin; poszczególne wyrazy w nazwie powinny zostać rozdzielone myślnikami. Konwencją jest także rozpoczynanie nazwy pluginu od literek „wp”.

Mój plugin będzie się nazywał „WP Wykop by Muzungu”. Dlatego też utworzyłem katalog o nazwie 'wp-wykop-by-muzungu’, a w nim plik 'wp-wykop-by-muzungu.php’.

Tworzymy opis naszego pluginu

Opis pluginu umieszczamy w naszym pliku .php jako komentarz. Wygląda on mniej więcej tak:

<?php
/*
Plugin Name: WP Wykop by Muzungu
Version: 0.1
Description: Automatically Adds <strong>"Wykop To" button to your posts.
Author: Konrad Karpieszuk
Author URI: http://www.muzungu.pl/
Plugin URI: http://www.muzungu.pl/
*/

Co się stało się? W każdej linijce mamy pewien fragment opisu. I tak:

Plugin Name – to nasz nazwa pluginu.

Version: wersja pluginu w zapisie z kropką oddzielającą podwersje

Description: opis naszego pluginu. Jak widać w przykładzie powyżej możemy w nim użyć tagów HTML

Author: Imię i nazwisko autora pluginu, lub nazwa firmy, która go stworzyła.

Author URI: Odnośnik do strony WWW autora (bloga, profilu na Naszej Klasie… ;) )

Plugin URI: Tu wpisujemy odnośnik do strony, na której plugin będzie opisany.

Sprawdzamy czy nasz plugin został zainstalowany w odpowiednio nowej wersji WordPressa

Właściwie to nie musiałem tego robić, bo ten plugin jest bajecznie prosty i zadziała pewnie nawet w starym WordPressie. Ale podaję jak to się robi, bo może w przyszłości sam stworzysz plugin, który będzie korzystał tylko z najnowszej wersji API tego systemu blogowego.

Oto jak to się robi. W tym samym pliku wpisujemy poniżej:

/* Version check */
global $wp_version;

$exit_msg = '
WP Wykop by Muzungu requires WordPress 2.5 or newer.
<a href="http://codex.wordpress.org/Upgrading_WordPress">
Please update!</a>';

if (version_compare($wp_version, "2.5", "<"))
{
 exit($exit_msg);
}

I tak po kolei, w linii 11. wpisaliśmy w postaci komentarza co robi poniższy kod (to jeden ze standardów kodowania pluginów dla WordPressa: każdą funkcję dokładnie okomentuj, tak aby potem inni mogli ją sobie łatwo przerobić bez zbędnego zagłębiania się w kod).

Następnie w linii 12. wywołujemy zmienną globalną $wp_version, w której przechowywana jest informacja o zainstalowanej wersji WP.

W 14 linijce tworzymy string, który przechowuje komunikat błędu, jaki się pojawi użytkownikowi, jeśli spróbuje nasz plugin zainstalować w zbyt starej wersji WordPressa.

Linie 18-21 to instrukcja warunkowa sprawdzającą wersję WP z wersją wymaganą przez nas (tutaj: 2.5) i jeśli warunek nie jest spełniony, instalacja kończy się wyświetleniem komunikatu, który stworzyliśmy przed chwilą.

Tworzymy kod odnośnika do Wykopu

Następnie musimy stworzyć kod HTML odpowiedzialny za wyświetlenie odnośnika do strony dodawania do Wykopu, w taki sposób, aby od razu zostały przekazane do niej informacje o adresie naszego wpisu, tytule i jego treści. Zrobimy to tworząc funkcję o nazwie WPWykopTo_Link().

Przyjrzyjmy się jednak najpierw jak wygląda odpowiedni odnośnik. Musi on nas kierować do strony http://www.wykop.pl/dodaj i przekazywać parametry metodą GET (czyli dokleić je do adresu strony) takie jak „url”, „title” oraz „desc”.

Zatem do dzieła.

/* Show a Wykop To Link */
function WPWykopTo_Link ()
{
global $post;
// get the URL to the post
$link = urlencode(get_permalink($post->ID));

// get a post title
$title = urlencode($post->post_title);

// get first 350 characters of post and strip it off
// HTML tags

$text = urlencode(substr(strip_tags($post->post_content), 0, 350));

// create a Wykop To link and return it

return '<a href="http://www.wykop.pl/dodaj?url='
.$link.'&title='.$title.'&desc='.$text.'">Wykop To</a>';

}

OK, znów lecimy po kolei i sprawdzamy co zrobiliśmy:

Linia 26: wczytujemy kolejną globalną zmienną, dostarczoną nam prez silnik WordPressa. $post zawiera w sobie wiele informacji o aktualnie przetwarzanym/wyświetlanym wpisie blogowym.

W linii 28. wywołujemy funkcję dostarczoną przez WP get_permalink(), która pobiera stały odnośnik do wpisu. Funkcja operuje tutaj na zmiennej $post->ID (czyli pobiera odnośnik do wpisu o określonym identyfikatorze). Odnośnik „urlenkodujemy” (przetwarzamy tak, aby bezpiecznie się wyświetlił jako parametr w innym URLu) i przypisujemy do zmiennej $link.

Linia 31 przypisuje do zmienne $title tytuł wpisu wyciągnięty z metody „title” obiektu $post. (nie znoszę programowania obiektowego)

W linii 36. na pierwszy rzut oka dzieje się wiele. Na drugi rzut oka jednak łatwo zauważymy, że wszystko co się stało, to pobraliśmy z obiektu $post treść naszego wpisu, usunęliśmy z niego znaczniki HTML, przycięliśmy do długości 350 znaków, także „zurlenkodowaliśmy” i przypisaliśmy do zmiennej $text. Proste? Proste! :)

Linia 40 to już banał. Zwracamy w niej kod HTML odpowiedzialny za wyświetlenie odnośnika do Wykopu. W czasie tego zwracania w odpowiednie miejsca podstawiamy nasze zmienne $link, $title i $text, tak aby utworzyły prawidłowy odnośnik dodający.

Doczepiamy nasz link do końca treści wpisu

Kod HTML utworzony, czas więc go doczepić do końca treści naszego wpisu:

/* Add Wykop To link to the end of the post */
function WPWykopTo_ContentFilter ($content) {
	return $content.WPWykopTo_Link();
}

Tutaj kod jest krótki. Tworzymy funkcję o zagmatwanej nazwie WPWykopTo_ContentFilter(), która pobierze parametr $content i doklei na jego końcu wynik działania naszej poprzedniej funkcji (czyli WPWykopTo_Link(), czyli kod HTML odnośnika do Wykopu). I tyle.

Informujemy WordPress aby użył naszego filtra

WordPress na tym etapie sam z siebie nie wie jeszcze, że jakaś funkcja już istnieje i przerabia treść wpisów w ten sposób, że dokleja na ich końcu odnośnik do Wykopu. To bardzo dobrze, bo pozwala nam to, teoretycznie (teoretycznie, bo w tym tutorialu nie pokaże jak to się robi; może w następnym rozdziale) na przykład dokleić odnośnik do Wykopu tylko do wpisów wyświetlanych na pojedynczych stronach. Ale w naszym przypadku chcemy aby link był dkolejany do wszystkich wpisów bez wyjątku.

Aby to sprawić używamy tak zwanych „haków” (ang. „hooks”). Haki „podczepiają” nasze funkcje pod silnik WordPressa. W kodzie WordPressa co rusz wpisane są funkcje sprawdzające czy w danym momencie jakiś plugin nie chciałby zmodyfikować działania owego silnika. Jeśli znajdzie taki plugin z odpowiednią instrukcją „hakującą”, pozwala mu zadziałać.

Haki są dwojakiego rodzaju.

Są haki podczepiane w momencie wykonania jakiegoś działania (action) przez WordPressa. Na przykład gdy zarejestruje się nowy użytkownik, gdy ktoś opublikuje nowy komentarz, lub gdy ktoś zamieści nowy wpis. Lub… przykładów jest bardzo wiele. Za zamieszczenie takiego akcyjnego haka odpowiada funkcja add_action(). Jednak teraz jej nie użyjemy.

Są też haki podczepiane w momencie wczytywania strony, których zadaniem jest przefiltrowanie tego, co silnik WordPressa właśnie wypluwa i zmodyfikowanie tej wyplutej zawartości. Takiego właśnie haka teraz użyjemy – chcemy bowiem wyplutą przez WordPressa treść wpisu zmodyfikować tak, że zanim pojawi się ona w przeglądarce odwiedzającego, doklejony do jej końca zostanie nasz wykopowy link. Za przefiltrowanie wordpressowego wyziewu odpowiada funkcja add_filter() i to jest właśnie moment gdy jej użyjemy.

Tutaj kod będzie bajecznie prosty i krótki:

add_filter('the_content', 'WPWykopTo_ContentFilter');
?>

Jak widać funkcja add_filter przyjmuje dwa parametry.

Pierwszy z nich to wskazanie co ma zostać przefiltrowane. W naszym przypadku filtrujemy treść wpisu, więc piszemy tutaj 'the_content’. Pełna lista rzeczy, które można filtrować znajduje się tutaj.

Drugi parametr mówi funkcji jaka nasza funkcja ma zostać zastosowana do filtrowania zawartości pierwszego parametru. Dlatego wpisaliśmy tutaj nazwę naszej funkcji filtrującej 'WPWykopTo_ContentFilter’.

I tyle, to już koniec naszego plugina.

Instalujemy plugin

Powyższe plugin na pewno działa. Ja już to sprawdziłem, a jeśli Ty też chcesz sprawdzić, utworzony na początku katalog 'wp-wykop-by-muzungu’ wgraj do WordPressa w lokalizacji /wp-content/plugins. Następnie przejdź do panelu administracyjnego WordPressa. wybierz tam Plugins > Installed. Na liście pluginów zobaczysz swój plugin. Jeszcze on nie działa.

Aby zadziałał, musisz kliknąć obok niego napis „Activate”. Jeśli nie używasz WordPressa starszego niż 2.6, aktywacja na pewno się powiedzie. Przejdź teraz na stronę swojego bloga, a zobaczysz pod każdym wpisem mały, którki napis „Wykop To” :)

Zobacz też

Jest już dostępny rozdział drugi tego tutorialu.