Przygotowanie

Na początek ustalmy jaki mamy cel w naszej pracy. W tym poradniku chciałbym pokazać jak dodać tag <ramka> który pozwoli na szybkie tworzenie rameczek z obrazkowym tłem i treścią w środku. Jako tło będzie można ustawić dowolną grafikę spośród zuploadowanych na serwer wpisując jej nazwę jako wartość atrybutu grafika.

Teraz czas na napisanie rozszerzenia. Zaczniemy od stworzenia pliku z rozszerzeniem php. Musimy ten plik umieścić w folderze extensions naszej instalacji MW. U mnie będzie to extensions/nowetagi.php. Tak przygotowany plik musimy podpiąć do skryptu. W tym celu otwieramy plik LocalSettings i mniej więcej po środku dopisujemy linijkę:

require_once("extensions/nowetagi.php");

Włączanie parsowania

Kolejnym krokiem w naszej pracy będzie otwarcie pliku nowetagi.php i dodanie odpowiedniego zdarzenia wewnątrz znaczników php:

$wgHooks['ParserFirstCallInit'][] = 'mojParser';

Powyższa linijka spowoduje, że w momencie jak MediaWiki będzie parsował artykuł to wywoła funkcję mojParser by dowiedzieć się jak parsować tagi obsługiwane przez nasze rozszerzenie. Poniżej tej linijki umieszczamy ciało wspomnianej funkcji:

function mojParser( &$parser ) {
   $parser->setHook( 'ramka', 'parsowanieRamka');
   return true;
}

W podanym przykładzie poinformowaliśmy parser, że tag <ramka> ma być obsługiwany za pomocą funkcji parsowanieRamka(). W obrębie jednej funkcji mojParser możemy dodać nielimitowaną liczbę nowych tagów. Ważne jest tylko aby na końcu zwrócić true.

Funkcja parsująca

Teraz zdefiniujmy funkcję parsowanieRamka().

function parsowanieRamka( $input, $args, $parser, $frame ) {
}

Póki co ciało funkcji jest puste. Musimy bowiem najpierw wyjaśnić co zawierają przekazane argumenty. Jak wiadomo tagi dzielą się na dwuelementowe (<ramka></ramka>) i jednoelementowe (<cytat />). Jeśli parsowany tag składa się z otwarcia i zamknięcia to zmienna $input będzie zawierała to co znajduje się pomiędzy czyli inaczej mówiąc zawartość tagu. Zmienna $args jest zaś tablicą o indeksach identycznych jak atrybuty parsowanego tagu i z wartościami równymi wartościom tych atrybutów. Dla przykładu tag <ramka grafika=”tlo.jpg”>Dowolny tekst</ramka> zostanie podzielony na zmienną $input o wartości Dowolny tekst oraz na jednoelementową tablicę $args gdzie $args['grafika']=’tlo.jpg’. Pozostałe argumenty przekazane funkcji parsowanieRamka() nie są dla nas istotne.

Uzbrojeni w powyższą wiedzę możemy zacząć pisać skrypt który zwróci kod html w miejsce tagu w artykule. Musimy jeszcze tylko pobrać adres URL do grafiki której nazwa została przekazana w atrybucie grafika.

if(!empty($args['grafika'])){
   $file = wfFindFile($args['grafika']);
   $url = $file->getFullUrl();
}

Powyższa instrukcja sprawi, że jeśli zdefiniowano wartość atrybutu grafika to zmienna $url będzie przechowywała bezwzględny adres do tego pliku. Możemy ją teraz użyć przy generowaniu pierwszej części kodu wynikowegoi ustawić obrazek jako tło bloku:

$output = '<div class="ramka" style="background-image: url('.$url.');">';

Teraz trzeba dołączyć do tego treść spomiędzy znaczników. Ale tu należy pamiętać o jednej rzeczy, że tam również może zostać użyta składania wiki i inne tagi. Dlatego też zmienną $input należy jeszcze raz przepuścić przez parser za pomocą specjalnej funkcji:

$output .= $parser->recursiveTagParse( $input, $frame );

Argumentami tej funkcji jest treść do ponownego sparsowania oraz zmienna $frame którą otrzymaliśmy wcześniej jako czwarty argument funkcji parsowanieRamka. Gdy to już mamy możemy zamknąć blok i zwrócić gotowy kod html:

$output .= '</div>';
return $output;

Pełny kod naszego rozszerzenia wygląda tak:

<?php
$wgHooks['ParserFirstCallInit'][] = 'mojParser';

function mojParser( &$parser ) {
   $parser->setHook( 'ramka', 'parsowanieRamka');
   return true;
}

function parsowanieRamka( $input, $args, $parser, $frame ) {
   if(!empty($args['grafika'])){
      $file = wfFindFile($args['grafika']);
      $url = $file->getFullUrl();
   }
   $output = '<div class="ramka" style="background-image: url('.$url.');">';
   $output .= $parser->recursiveTagParse( $input, $frame );
   $output .= '</div>';
   return $output;
}
?>

Nieco więcej o parsowaniu

W powyższym przykładowym rozszerzeniu użyliśmy funkcji $parser->recursiveTagParse();. Jak już pisałem służy ona do tego by sparsować składnię wiki i dodatkowe tagi wewnątrz jakiegoś tekstu. Należy jednak pamiętać, że nie zostaną wtedy podmienione podpisy (~~~~). Tym zajmuję się tzw parser wstępny ale on także w tym wypadku nam nie pomoże. Jest to związane z tym, że tekst wewnątrz tagów dodawanych przez rozszerzenia jest parsowany przy każdym wyświetleniu strony na nowo a w bazie danych ląduje niezmieniony. Z tego też powodu własne tagi nie sprawdzą się w miejscach gdzie użytkownicy będą się podpisywać za pomoca 4 tyld.

Inną sprawą jest to, że należy uważać by nie parsować znaczników html które nie działają na stronach MediaWiki. Np. próba sparsowania tekstu <img src=”adres.png”> spowoduje, że ten kod pojawi się na stronie w formie tekstu a nie obrazka. Można jednak bezpiecznie parsować kod obrazka zapisany w wikiskładni tzn [[Grafika:Plik.png]]. Identyczna sytuacja zachodzi przy odnośnikach. Dlatego należy uważać by nie wrzucać do parsera przypadkowego kodu html a jedynie parsować to co można.

Inny przykład: tag <cytat>

Na koniec zamieszczę jeszcze jeden kod parsowania tagu. Jego składnia wygląda tak: <cytat autor=”Imię Nazwisko”></cytat> a skrypt który go parsuje przedstawia się następująco:

function parsowanieCytat($input, $args, $parser, $frame ) {
   $output = '<blockquote>'.$input.'<div>'.$args['autor'].'</div></blockquote><br style="clear: left;" />';
   return $parser->recursiveTagParse( $output, $frame );
}

Do tego dochodzi jeszcze krótki kod CSS:

blockquote{
  padding-left: 50px;
  background: url('quote.png') left 5px no-repeat;
  margin: 0px 20px 10px 0px;
  font-family: Georgia;
  font-style: italic;
  min-height: 27px;
  float: left;
  color: #333;
  max-width: 500px;
}
blockquote div{
  text-align: right;
  color: #666;
  font-style: normal;
  font-size: 10px;
  font-family: Arial;
  margin-right: 10px;
}

Całość w akcji można zobaczyć na górze tej strony.

WPEngine – o co chodzi?

Opisywana platforma WPEngine ma być połączeniem zalet obecnych dwóch rozwiązań. Za dosyć wysoką cenę 50$ miesięcznie otrzymamy możliwość utworzenia swojego serwisu internetowego z użyciem WordPressa na hostingu idealnie zoptymalizowanym pod tą platformę. Autorzy pomysłu kusza nas  ogromną galerią gotowych wtyczek i skórek. Co więcej możemy także instalować własne rozszerzenia i motywy. Ponadto oto by nasza strona nie padła w okresie wzmożonego ruchu będą dbać odpowiednie narzędzia odpowiedzialne za cachowanie treści, minimalizowanie plików oraz kompresję grafik. Zaś developerzy będą mieli pełny dostęp do logów serwera PHP.

„It’s safer here”

Platforma WPEngine w przeciwieństwie do typowych hostingów będzie dbało o to czy wszystkie pliki mają dobrze nadane prawa dostępu. Dzięki temu nie ma  możliwości, że przez źle ustawione chmody ktoś usunie nam zdalnie plik. Ponadto będzie można uruchamiać wszystkie wtyczki i skórki w trybie piaskownicy. To znaczy, że możemy sprawdzić działania nowego składnika na swoim blogu ale internauci nie zobaczą od razu efektów tych eksperymentów. Dopiero gdy stwierdzimy, że wszystko działa prawidłowo będziemy mogli zatwierdzić zmiany i oddać nowe funkcjonalności w ręce użytkowników. Taki sposób pracy chroni nas przed uszkodzeniem instalacji WP przez złośliwą wtyczkę. Co więcej wszystkie konta na serwerze są od siebie odseparowane przez co nie ma możliwości ataku na nasz serwis przez innego klienta WPEngine.

Gdzie to można dostać?

Aktualnie aby móc skorzystać z platformy trzeba otrzymać zaproszenie. Na pełne otwarcie usługi przyjdzie nam pewnie jeszcze poczekać. Niemniej już teraz wydaje się, że będzie to doskonałe rozwiązanie dla wszelkich stron firmowych i dużych blogów. Jak to wyjdzie w praniu to się okaże. W każdej chwili można opuścić szeregi klientów WPEngine ale przenoszenie swojego istniejącego serwisu to i tak poważny krok.

Nasze miejsce pracy

Dla naszych banerków najlepiej przygotować osobny folder. W nim umieśćmy obrazek który będzie podstawą naszego dzieła. Ja dla banerka mojej encyklopedii o grach firmy Valve  przygotowałem coś takiego:

Plan jest taki aby pod tytułem strony znajdował się napis n artykuły(ów) o grach Valve gdzie n jest oczywiście liczbą stron. Przed napisaniem tego skryptu musimy jednak zadbać jeszcze o jedną rzecz. Nasz baner będzie generowany w PHP przy każdym zapytaniu. Link do naszego obrazka nie może być jednak linkiem do pliku php, gdyż wtedy nie będzie się wyświetlał w podpisach na forach internetowych. Musimy skorzystać z możliwości jakie daje nam plik .htaccess. Po utworzeniu go w folderze z naszym banerem umieszczaniu w nim poniższy kod:

RewriteEngine On
RewriteRule ^baner.png$ generator.php [L]

Ta instrukcja spowoduje, że chociaż adres będzie prowadził do pliku baner.png to serwer będzie zwracał treść z pliku generator.php.

Generowanie obrazka

Teraz możemy przystąpić do pisania skryptu PHP. Tworzymy więc nasz plik generator.php i na samym jego początku łączymy się z bazą naszej wiki

$serverdb='localhost'; //adres serwera bazy danych
$dbuser='user'; //uzytkownik bazy danych
$dbuserpass='password'; //haslo uzytkownika
$db='database'; //nazwa bazy danych

$link = mysql_connect ($serverdb, $dbuser, $dbuserpass)
   or die (mysql_error());
mysql_select_db ($db);

Gdy jesteśmy już połączeni z bazą możemy pobrać informacje o ilości artykułów. Wyciągniemy ta informację ze specjalnych tabel gdzie są przechowywane tego typu statystyki.

$uchwyt = mysql_query ('SELECT ss_good_articles from wiki_site_stats');
$rekord = mysql_fetch_array($uchwyt);
$ilosc = $rekord['ss_good_articles'];

Teraz, gdy ilość artykułów mamy już w w zmiennej $ilosc możemy napisać część kodu, która odmieni wyraz artykuły na potrzeby naszego napisu i złoży cały tekst w całość.

$jednostki = substr($ilosc, strlen($ilosc)-1, 1);
if($jednostki == 2 || $jednostki == 3 || $jednostki == 4) $art = 'arykuły';
   else $art = 'arykułów';
$tekst = "$ilosc $art o grach Valve";

Gdy to już mamy gotowe nic nie stoi na przeszkodzie by rozpocząć generowanie grafiki.

$image = imagecreatefrompng("baner.png");
$black = imagecolorallocate($image, 0, 0, 0);
imagettftext($image, 10, 0, 250, 45, $black, 'calibri.ttf', $tekst);

Podany kod kolejno wczytuje obrazek baner.png, tworzy indeks koloru czarnego i na końcu nakłada tekst na załadowaną grafikę. Użyta przy ostatniej operacji funkcja imagettftext przyjmuje kolejno jako argumenty zmienną z obrazkiem, rozmiar czcionki, pochylenie fontu w stopniach, współrzędne umieszczenia napisu, link do pliku z czcionką oraz na końcu treść napisu. W tym przykładzie użyliśmy czcionki calibri.ttf, której plik należy również umieścić w folderze z banerem.

W stronę przeglądarki

Aktualnie w zmiennej $image przechowujemy gotowy obrazek. Przed jego wyświetleniem musimy jednak zamienić co najmniej jedną informację w nagłówku wysyłanym do przeglądarki. Wersja minimalistyczna kodu odpowiedzialnego za wyświetlanie baneru wygląda tak:

header("Content-type: image/jpeg");
imagejpeg($image);

W tym przypadku informujemy tylko, że przesyłana treść jest grafiką, a nie tekstem jak wskazywałoby jego pochodzenie z pliku .php. Później przesyłamy sam obrazek. Jeśli zaś chcemy aby informacje wyświetlane na banerze były zawsze aktualne, musimy wymusić na przeglądarce by za każdym razem na nowo go pobierała z serwera. Użyjemy do tego tricku polegającego na wyłączeniu cachowania grafiki oraz ustawieniu przeszłej daty wygaśnięcia jej ważności.

header("Cache-Control: no-cache, must-revalidate");
header("Expires: Mon, 26 Jul 1997 05:00:00 GMT");
header("Content-type: image/jpeg");
imagejpeg($image);

Podsumowanie

Oto gotowy efekt nasze pracy:

Fajnie wygląda i co najważniejsze spełnia swoje zadania. Należy jednak pamiętać by nie nadużywać opcji wyłączania cachowania przy dużych serwisach by nie obciążyć bazy danych. A przy naprawdę dużych encyklopediach internetowych zalecane jest napisanie skryptu cachującego liczbę artykułów.

Na koniec załączam paczkę z wszystkimi plikami powyższego baneru.

Podstawy dołączania skryptów

Aby dołączyć zewnętrzny skrypt do naszego WP musimy w w skórce naszej witryny odszukać intrukcję wp_head(). Najczęściej można ją odnaleźć w pliku header.php. Tuż przed nią trzeba dopisać dwie funkcję: pierwszą która zarejestruje nowy skrypt, drugą która go dołączy do strony. Schamtycznie wygląda to tak:

wp_register_script($nazwa, $sciezka, $biblioteki, $wersja);
wp_enqueue_script($nazwa);
wp_head();

Teraz wyjaśnię pokrótce co należy wstawiać w miejsce kolejnych zmiennych. $nazwa to wewnętrzna nazwa dołączanego skryptu. Nie ma znaczenia co tam wpiszemy. Ważne tylko by w obu miejscach, przy rejestracji i dołączaniu skryptu, wpisany wyraz był taki sam. $sciezka to jak łatwo się domyślić adres do pliku z naszym kodem. Można tu wykorzystać funkcję get_bloginfo() aby WP sam wstawił aktualny adres strony lub ścieżkę do folderu z skórką. $biblioteki to parametr który musi być tablicą zawierającą listę bibliotek wykorzystywanych przez nasz kod. Dzięki temu WordPress kontroluje kiedy i jakie skrypty są podpinane do strony i nigdy nie zdarzy się, że np. jQuery będzie ładowane dwa razy. Listę dostępnych bibliotek i ich nazw kodowych można sprawdzić tutaj. Ostatni parametr to zmienna $wersja. Po każdorazowej modyfikacji skryptu musimy obowiązkowo zmienić tą liczbę by wymusić na przeglądarkach ponowne pobranie pliku zamiast korzystania z starej wersji z cachu.

Przykładowy pełny kod wygląda tak:

wp_register_script('tinycarousel', get_bloginfo('template_directory') . '/js/jquery.tinycarousel.min.js', array('jquery'), '1.0' );
wp_enqueue_script('tinycarousel');

W powyższym przykładzie zarejestrowaliśmy wtyczkę tinycarousel której plik znajduje się w folderze z skórką i która wymaga biblioteki jQuery. Następnie dołączyliśmy ją do kodu.

Dołączanie warunkowe

Jeśli z naszego skryptu korzystamy tylko na niektórych stronach to nie ma potrzeby dołączania plików przy każdym wyświetleniu witryny. Warto więc dopisać instrukcję warunkową która spowoduje, że nasz kod będzie dołączany jedynie na wybranych stronach. Poniższy przykłąd będzie dołączał dodatkowe pliki tylko na stronie głównej:

if(is_home){
   wp_register_script('tinycarousel', get_bloginfo('template_directory') . '/js/jquery.tinycarousel.min.js', array('jquery'), '1.0' );
   wp_enqueue_script('tinycarousel');
}

Zaś ten kod spowoduje załadowanie skryptu JS jedynie na stronie z id równym 29:

if(is_page('29')){
   wp_register_script('tinycarousel', get_bloginfo('template_directory') . '/js/jquery.tinycarousel.min.js', array('jquery'), '1.0' );
   wp_enqueue_script('tinycarousel');
}

Jako argument w funkcji if podajemy odpowiedni tag warunkowy. Więcej informacji o nich można znaleźć pod tym linkiem.

Rejestracja menu

Zaczynamy od edycji pliku functions.php który znajdziemy w folderze wp-content/themes/(nazwa skórki). Musimy w tym pliku zainicjować menu. Robi się to dosyć prosto. Wystarczy na jego końcu tuż przed znacznikiem ?> dopisać taki krótki skrypt:

add_action( 'init', 'rejestracja_menu' );
function rejestracja_menu(){
   register_nav_menus( array(
      'topmenu' => __('Menu górne'),
      'bocznemenu' => __('Menu główne'),
   ));
}

W powyższym kodzie najpierw dodaliśmy zdarzenie polegające na wywołaniu funkcji rejestracja_menu podczas generowania strony a następnie zdefiniowaliśmy ciało tej funkcji. Użyliśmy w niej funkcji register_nav_menus() która rejestruje jedno lub więcej menu na podstawie przekazanej jej tablicy. W tablicy umieściliśmy dwa menu. Pierwsze o nazwie kodowej topmenu i drugie bocznemenu. Użytkownikowi będą się one wyświetlać kolejno jako Menu górne i Menu główne. Nazwy kodowe istnieją po to by uniknąć problematycznych polskich ogonków i białych znaków. Jeśli chcielibyśmy zdefiniować tylko jedno menu możemy także skorzystać z funkcji register_nav_menu której używa się tak:

register_nav_menu( 'moje-menu', __( 'Menu na stronie' ) );

Umieszczanie menu w skórce

Aby wyświetlić menu na stronie wstawiamy w odpowiednie miejsce w kodzie krótką instrukcję

<?php wp_nav_menu('bocznemenu'); ?>

Jako argument wystarczy podać nazwę kodową wcześniej zdefiniowanego menu. Chętni mogą się jednak pobawić dodatkowymi opcjami. Można np. ustawić w jaki element ma być włożone menu (domyślnie jest wewnątrz diva) oraz jaką ma mieć klasę. Poniższy kod ustawia je tak by było ono wyświetlane bez kontenera a element ul będzie miał klasę mojemenu. Należy pamiętać, że po dodaniu dodatkowych ustawień inaczej definiuje się które menu ma być wyświetlane w tym miejscu.

<?php wp_nav_menu( 'menu=bocznemenu&container=&menu_class=mojemenu' ); ?>

Oczywiście opcji jest o wiele, wiele więcej. Wszystkie do przejrzenia w dokumentacji tej funkcji.

Kompatybilność wsteczna

Na koniec zajmijmy się problemem kompatybilności. Może się on pojawić gdy nie wiemy czy nasza skórka będzie uruchamiana także na wersjach WordPressa wcześniejszych niż 3.0 gdzie funkcje takie jak wp_nav_menu zwyczajnie nie działają. Wtedy przydałoby się by zamiast menu nawigacyjnego pojawiła się zwyczajnie lista stron w danym serwisie. Na szczęście łatwo takie coś wykonać. Wystarczy jedna instrukcja warunkowa w części odpowiedzialnej za wyświetlanie menu:

if ( function_exists( 'wp_nav_menu' ) )
    wp_nav_menu( 'topemenu' );
else
    wp_page_menu( 'show_home=Strona główna&menu_class=pagemenu' );
}