[ O PunBB ] [ Dla developerów ] [ Najczęściej Zadawane Pytania ] [ Instalacja i Aktualizacja ]

Poniżej znajdują się przydatne informacje dla programistów, którzy rozpoczynają przygodę z modyfikowaniem PunBB. Pamiętaj, że najlepszą nauką jest analiza przykładów. Tutaj znajdziesz tylko podstawowe zagadnienia związane z API forum, jednak po jakimś czasie może się okazać, że jest to dla Ciebie za mało.

Skrypt extern.php służy do pobierania różnych informacji z naszego forum i umieszczania ich poza nim, w formie skryptu PHP lub kanału RSS. Potrafi on wyświetlić listę najpopularniejszych wątków (sortowanych przez datę rozpoczęcia lub napisania ostatniego posta), listę aktywnych użytkowników oraz proste statystyki forum. Skrypt może być wywoływany zdalnie przez adres URL (dla RSS), przez include() lub korzystając z SSI.

Skrypt jest kontrolowany przez zmienne zawarte w adresie URL. Dostępne są różne opcje, jak na przykład: action (rodzaj wyświetlanych informacji), show (liczba wątków do wyświetlenia), forum (ID forum, z którego mają być pokazane tematy) oraz type (HTML lub RSS).

Konfiguracja i parametry syndykacji:

1. Action:

• active (pokazuje najbardziej aktywne wątki) (HTML lub RSS)
• new (pokazuje najnowsze wątki) (HTML lub RSS)
• online (pokazuje liczbę użytkowników online) (HTML)
• online_full (jak powyżej, ale pokazuje pełną listę) (HTML)
• stats (pokazuje statystyki forum) (HTML)

2. Show: Liczba z przedziału 1 do 50. Ta opcja jest ignorowana przy RSS. Domyślną wartością jest 15.
3. Fid: Z jednego lub więcej ID for (oddzielone przecinkami bez spacji). Jeśli nie zdefiniowano to wszystkie wątki dostępne nie tylko dla gości będą pokazywane.
4. Type: RSS. Cokolwiek innego oznacza HTML.


Kilka przykładów korzystających z PHP include():

» Pokazuje najbardziej aktywne wątki z wszystkich for:
include(’host.com/forums/extern.php?action=active’);
» Pokazuje 10 najnowszych postów z for o ID 5, 6 oraz 7:
include(’host.com/forums/extern.php?action=new&show=10&fid=5,6,7’);
» Pokazuje użytkowników online:
include(’host.com/forums/extern.php?action=online’);
» Pokazuje użytkowników online z pełną listą:
include(’host.com/forums/extern.php?action=online_full’);
» Pokazuje statystyki forum:
include(’host.com/forums/extern.php?action=stats’);
*host.com/forums zamieniamy na adres naszego forum (np. http://strona.pl/forum)

Podstawowa integracja forum PunBB oraz Twojego serwisu będzie bardzo prosta, jeżeli choć w małym stopniu rozumiesz zagadnienia języka PHP. Przez korzystanie ze skryptu common.php otrzymasz dostęp do wszystkich podstawowych i przydatnych zmiennych globalnych, jak na przykład $db czy $pun_user. Jednakże przed skorzystaniem z common.php i takiej zmiennej musisz zdefiniować PUN_ROOT. Ciąg ten jest używany do rozpoznawania ścieżki skryptu forum i musi być prawidłowy, gdyż inaczej skrypt nie zadziała. Przykładowo:
- Twój serwis znajduje się w /home/user/public_html/
- Twoje forum w /home/user/public_html/forums/
Więc Twój kod PHP powinien być następujący:

define(’PUN_ROOT’, ‘./forums/’); require PUN_ROOT.’include/common.php’;

Po jednorazowym załadowaniu common.php przez funkcję include, otrzymujesz dostęp do wszystkich przydatnych zmiennych i funkcji PunBB. Zapewne będziesz zainteresowany zmienną $pun_user, która zawiera wszystkie informacje dotyczące zalogowanego użytkownika. Następną interesującą zmienną jest $db, dzięki której można wykonywać operacje w bazie danych forum. Poniżej znajdziesz najprostszy przykład wykorzystania zmiennych i funkcji skryptu.

Witaj <?php echo pun_htmlspecialchars($pun_user[’username’]); ?>!

Po zdefiniowaniu PUN_ROOT, możesz wykorzystać szereg innych opcji z common.php. Najbardziej interesującymi są PUN_TURN_OFF_MAINT oraz PUN_QUIET_VISIT. Jeśli PUN_TURN_OFF_MAINT zostało zdefiniowane zaraz po common.php, PunBB nie wyświetli informacji podczas prac konserwacyjnych nad forum. Przeważnie nie chcesz, żeby taka wiadomość widniała na stronie głównej, więc zdefiniowanie tej opcji jest dobrym pomysłem. Innym przykładem jest funkcja PUN_QUIET_VISIT, która zapobiega aktualizacji danych użytkownika przy pobycie w serwisie, co oznacza brak zmiany daty ostatniego logowania i pokazania na liście użytkowników, bez pobytu na forum. To także w większości przypadków jest rozsądne wyjście. Nie ważne jaką wartość przypiszesz definicji, ale musi być ona większa niż zero, zaś dobrym pomysłem jest podawanie 1. Mały przykład:

define(’PUN_TURN_OFF_MAINT’, 1);
define(’PUN_QUIET_VISIT’, 1);

Pamiętaj, że te definicje muszą być zapisane przed include common.php, inaczej wystąpią problemy!

Pluginy admina są małymi skryptami zintegrowanymi z panelem admina, do których uruchomienia wystarczy wysłanie ich na serwer do katalogu /plugins. Zbadaj przykładowy plugin AMP_Example.php aby dowiedzieć się więcej. Poniżej kilka wskazówek dla twórców pluginów:

- Jeśli chcesz wyświetlić wiadomość korzystając z funkcji message() wcześniej musisz użyć generate_admin_menu($plugin).
- Pluginy są ładowane przez admin_loader.php i nie mogą być zabijane (chodzi np. o wywoływanie funkcji exit()). Po zakończeniu skryptu plugina, skrypt ładowania sam wyświetli stopkę, więc nie trzeba się o to martwić. Dozwolone, a nawet cenione jest użycie funkcji redirect() i podobnych.
- Atrybut akcji wszystkich tagów

oraz target URL dla funkcji redirect() to $_SERVER[’REQUEST_URI’]. Ten adres URL może być rozszerzany o inne opcje (na przykład &foo=bar w przykładowym pluginie).
- Jeżeli Twój plugin jest tylko dla administratorów to prefiksem nazwy pliku musi być “AP_”. Jeżeli zaś jest on zarówno dla administratorów jak i moderatorów, użyj prefiksu “AMP_”. Przykładowy plugin ma prefiks “AMP_” i jest dostępny dla administratorów oraz moderatorów w menu administracyjnym.
- Używaj _ zamiast spacji w nazwach plików pluginów.
- Odkąd pluginy są uruchamiane w admin_loader.php, otrzymujesz dostęp do zmiennych i opcji PunBB (np. $db, $pun_config, $pun_user itd.).
- Aby zachować całkowitą zgodność i prostotę projektuj interfejs zgodnie z resztą panelu admina. Rozsądnie pisz kod, dbając o jego czytelność i bezpieczeństwo.
- Pluginy muszą być wydawane na licencji GNU GPL lub zgodnej z nią. Skopiuj preambułę (w j. ang) do początku Twojego skryptu oraz umieść informacje o autorze plugina (np. Tobie).