eStats project
Free web statistics

• News
• Download
• Features
• Requirements
• FAQ
• Changelog
• Documentation
• Demo
• To do
• Author
• Contact
• Forum

How to create plugin

Z tego mini opracowania dowiesz się jak napisać wtyczkę zwiększającą funkcjonalność panelu administracyjnego.

^ Wprowadzenie

System prostych wtyczek jest kolejną nowością wprowadzoną w wersji 4.5. Umożliwiają one łatwe rozszerzenie panelu o niemal dowolną funkcjonalność, czy to prostego edytora plików, czy nawet generatora obrazków. Można dzięki nim osiągnąć znacznie więcej, ograniczeniem są głównie pomysły i możliwości PHP ;-).

Wtyczki dostępne są z założenia tylko dla administratora, za pośrednictwem panelu. Nie ma jednak ograniczeń aby stworzyć wtyczkę "samodzielną", jednakże wymagałoby to dopisania lub ponownego wykorzystania kodu eStats aby wygenerować interfejs.

Do skryptu dołączonych jest kilka wtyczek, na których możesz wzorować się tworząc własne.

Wtyczki przechowywane są w folderze pages/plugins/, instalacja i de instalacja polega na dodaniu lub usunięciu całego folderu wtyczki.

^ Budowa

^ Plik główny

Zasadniczym elementem każdej wtyczki jest plik plugin.php, który zawiera jej główny kod i jest dołączany jako zwykła strona. Dzięki temu mamy do dyspozycji wszystkie funkcje i dane, które możemy dowolnie obrabiać i wykorzystywać.

Przykładowy kod wtyczki:

1
2
3
4
5
6
7

<?php
if (!defined ('eStats')) die (); // uniemożliwia uruchomienie wtyczki jako samodzielnego skryptu
$T['page'] = '<p>
Jestem wtyczką, która nic nie robi ;-).
</p>
';
?>

Ta wtyczka wyświetli jedynie tekst "Jestem wtyczką, która nic nie robi ;-)." jako treść strony.

Oczywiście na tym nie kończą się możliwości wtyczek ;-). Możesz obejrzeć przykłady dołączone do skryptu, np. Edytor menu, czy Generator obrazków.

Plik główny może zawierać dowolny kod PHP, najlepiej wykorzystujący funkcje udostępniane przez skrypt główny, aby unikać nadmiaru kodu i spadku wydajności. Wtyczki powinny udostępniać proste funkcje, choć nie ma ograniczeń ;-).

^ Tłumaczenia

Wtyczki powinny posiadać własne pliki tłumaczeń, które są dobierane przez skrypt na podstawie ich dostępności oraz aktualnie wybranego języka. Rządzą się takimi samymi regułami jak zwykłe ciągi z plików językowych (w wersji PHP), czyli są dołączane do tablicy $L.

Przykładowy plik językowy:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

<?php
$L['Configuration files editor'] = 'Edytor plików konfiguracyjnych';
$L['Delete'] = 'Usuń';
$L['Configuration files'] = 'Pliki konfiguracyjne';
$L['Edit'] = 'Edytuj';
$L['Not writeable!'] = 'Brak praw do zapisu!';
$L['Editing of file'] = 'Edycja pliku';
$L['read only mode'] = 'tryb tylko do odczytu';
$L['Creation of backup is prescribed and very cautious editing of each file is recommended!'] = 'Zaleca się utworzenie kopii zapasowej oraz bardzo ostrożną edycję każdego pliku!';
$L['Path to file'] = 'Scieżka dostępu do pliku';
$L['Do You really want to save this file?'] = 'Czy na pewno chcesz zapisać ten plik?';
$L['Dou You really want to delete this file?'] = 'Czy na pewno chcesz usunąć ten plik?';
$L['File deleted successful.'] = 'Plik usunięty pomyślnie.';
$L['An error occured during deleting file!'] = 'Wystąpił błąd podczas usuwania pliku!';
$L['File created successful'] = 'Plik utworzony pomyślnie';
$L['An error occured during creating file!'] = 'Nie można utworzyć pliku!';
$L['File saved successful'] = 'Plik zapisany pomyślnie';
$L['An error occured during saving file!'] = 'Wystąpił błąd przy zapisie pliku!';
?>

Pliki należy umieścić w katalogu locale/ wtyczki, nadając im nazwy będące identyfikatorami języków z rozszerzeniem .php, np. pl.php.

Umieszczanie ciągów językowych wygląda analogicznie jak w pozostałych częściach skryptu, np:

1

e_i18n ('Delete')

^ Plik konfiguracyjny

Plik konfiguracyjny (format INI) zawiera podstawowe informacje oraz opisy wtyczki w różnych językach (najlepiej przynajmniej w języku angielskim). Ponadto determinuje, czy wtyczka jest aktywna, czy nie. Dane te są wyświetlane na odpowiedniej stronie w panelu administracyjnym. Wyłączonych wtyczek nie można uruchamiać.

Przykładowy plik konfiguracyjny:

1
2
3
4
5
6
7
8
9
10
11
12
13

[Information]
Name = "Configuration files editor"
Author = "Emdek"
URL = "http://estats.emdek.cba.pl"
Version = "1.1.02"
Status = "stable"
Licence = "GPL"
Time = "1200148269"
[Options]
Enabled = 1
[About]
en = "Simple configuration files editor."
pl = "Prosty edytor plików konfiguracyjnych."

Potencjalnie niebezpieczne wtyczki powinny być domyślnie wyłączone (sekcja Options, opcja Enabled ustawiona na 0).

Sekcja About zawiera krótkie opisy wtyczki w wybranych językach (opis w języku angielskim jest wymagany).

Opis pozycji sekcji Information:

• Name - nazwa wtyczki;
• Author - pseudonim lub imię i nazwisko autora;
• URL - link do strony domowej;
• Version - wersja (zalecany format x.x.xx);
• Status - status wtyczki (stable / beta / RC / alfa / pre / inne);
• Licence - licencja;
• Time - czas ostatniej modyfikacji (uniksowy znacznik czasu);

^ Budowa przykładowej wtyczki (Editor)

Wszystkie wymienione pliki są wymagane.

Na diagramie można zobaczyć budowę przykładowego katalogu wtyczki:

• editor/ [wymagany - główny katalog wtyczki, nazwa taka jak jej identyfikator]
  • locale/ [opcjonalny - katalog plików językowych wtyczki]
    • pl.php [opcjonalny - polski plik językowy]
  • plugin.ini [wymagany - plik konfiguracyjny wtyczki]
  • plugin.php [wymagany - główny plik wtyczki]

Poza tymi plikami wtyczki mogą definiować dowolne własne (najlepiej wewnątrz własnego folderu i logicznie uporządkowane). Mogą także zawierać własną dokumentację, szczególnie w przypadku tych bardziej rozbudowanych.

^ Działanie

Poniższy opis dotyczy działania "klasycznych" wtyczek, takich jak te dołączone do skryptu jako przykładowe.

Gdy skrypt otrzyma żądanie załadowania wtyczki, to sprawdza, czy istniej folder o podanym ID i czy opcja konfiguracyjna zezwala na użycie wybranej wtyczki.

Tytuł strony jest ustawiany z użyciem tytułu zawartego w pliku konfiguracyjnym wtyczki. Jeśli nic nie stoi na przeszkodzie, to dołączany jest plik główny wtyczki. Od tego momentu wtyczka "przejmuje kontrolę" i może zrobić wszystko na co pozwalają jej prawa dostępu do plików, dlatego zaleca się używanie jedynie wtyczek z pewnych źródeł lub takich, które potrafimy sami najpierw sprawdzić.

^ Zakończenie

Jeśli stworzysz jakąś przydatną wtyczkę (lub taką, która wydaje się Tobie przydatna ;-)), chcesz się nią pochwalić lub masz jakieś dodatkowe pytania, to pisz w odpowiednim dziale forum :-).

Ostatnia modyfikacja: 2008-02-17 11:22:23 CET

I do not know with what weapons World War III will be fought, but World War IV will be fought with sticks and stones.