ShoutBox - interfejsy
Jak już pisałem w artykule o instalacji, ShoutBox posiada kilka interfejsów, które dają duże pole do popisu wszystkim tym, którzy chcą urozmaicić tudzież dostosować ShoutBox do swoich potrzeb. Postaram się tu i teraz przybliżyć Wam małe co nieco jak używać tych cudaków.
Interfejsy
- ShoutBoxFormatter
Służy głównie do zarządzania wyglądem wiadomości, w tym również np. kolorowaniem nicków itp. Aczkolwiek zamieściłem tutaj również obsługę użytkowników on-line oraz komend. - ShoutBoxRights
Służy do zarządzania prawami. Możecie tu określić czy dany użytkownik może przeglądać wiadomości, edytować, kasować itp. - ShoutBoxDB
Służy do zarządzania danymi. Określa sposób ich przechowywania. Na chwilę obecną napisałem dwa sterowniki. Jeden do bazy MySql, drugi do systemu plików.
ShoutBoxFormatter
Chcąc wykorzystać ten interfejs, trzeba napisać klasę, która go zaimplementuje:
<?php
class ShoutBoxDefaultFormatter implements ShoutBoxFormatter {
private $_today;
private $_sbObj = null;
function __construct(){
$this->_today = date('Y-m-d');
}
}
?>
Klasa zawiera dwie właściwości prywatne, które w dalszym kodzie zostaną wykorzystane. W konstruktorze klasy ustawiam jedną z nich na aktualny dzień.
Przystąpmy teraz do implementacji metod interfejsu:
- SetShoutBoxObject()
Metoda ta ustawia obiekt shoutboxa, dzięki czemu będzie można później z niego skorzystać.<?php public function SetShoutBoxObject(&$sbObj){ $this->_sbObj = $sbObj; } ?>
- TimeFormat()
Metoda ta służy do formatowania czasu utworzenia wiadomości. Jako parametr wywołania dostaje czas w postaci timestampa. Zwraca czas gotowy do wyświetlenia. W tym przykładzie wyświetlam czas w postaci pełnej daty i godziny, chyba że wiadomość została napisana dzisiaj, wówczas wyświetlam tylko godzinę.<?php public function TimeFormat($timestamp){ $d = date('Y-m-d', $timestamp); return '['.($d == $this->_today ? '' : ($d.' ')).date('H:i', $timestamp).']'; } ?>
- NickFormat()
Metoda formatuje nick osoby piszącej wiadomość. Jako parametr wywołania dostaje nick, a zwraca przetworzony nick. W tym przykładzie do nicka dodaję tylko dwukropek. Kolor nicka ustawiany jest w innym miejscu.<?php public function NickFormat($nick){ return $nick.':'; } ?>
- AddingMessageFormat()
Zadaniem tej metody jest sformatowanie wiadomości przed jej zapisaniem w bazie. Możemy tutaj pozamieniać uśmieszki na obrazki, bbcode na odpowiednie znaczniki html itp. Dzięki temu nie trzeba będzie tych operacji powtarzać przed każdym wyświetleniem wiadomości.<?php public function AddingMessageFormat($message){ //cały kod formatujący wiadomość pomijam, gdyż jest za długi //możecie go podejrzeć w ściągnietej paczce return $message; } ?>
- ReformatMessage()
Metoda ta zwraca tekst gotowy do edycji. Wiadomość do reformatowania pobierana jest z bazy. Jeśli więc AddingMessageFormat() zamieniło mi ciąg znaków "<?php public function ReformatMessage($message){ //cały kod formatujący wiadomość pomijam, gdyż jest za długi //możecie go podejrzeć w ściągnietej paczce return $message; } ?>
" na kod html właściwego obrazka, to ta metoda musi kod html obrazka zamienić nam spowrotem na "
".
- GettingMessageFormat()
Formatuje wiadomość pobraną z bazy tak, by można ją było wyświetlić. Ponieważ w tym przykładzie AddingMessageFormat() zapisuje do bazy wiadomość tak jak ma już wyglądać, GettingMessageFormat() nie robi już nic z wiadomością<?php public function GettingMessageFormat($message){ return $message; } ?>
- GetParameters()
Metoda ta zwraca tablicę dodatkowych parametrów (lub null), które zmienią nam wygląd wiadomości, czasu, nicka. Te parametry to:<?php public function GetParameters($row){ if (!empty($row['COLOR'])) return array('stylenick'=>'color:#'.$row['COLOR'].';'); else return null; } ?>
- classmessage - nazwa klasy css dla całego diva wiadomości
- classtime - nazwa klasy css dla czasu
- classnick - nazwa klasy css dla nicka
- classtext - nazwa klasy css dla wiadomości
- stylemessage - styl css dla całego diva wiadomości
- styletime - styl css dla czasu
- stylenick - styl css dla nicka
- styletext - styl css dla wiadomości
- GetUsersOnLine()
Metoda ta być może nie pasuje do reszty tu omawianych, ale tak wyszło. Jej zadaniem jest zwrócić użytkowników on-line. Jeśli parametr $refresh jest ustawiony na true, metoda ma zwrócić aktualną listę użytkowników. Gdy nie, to użytkownicy mogą być pobierani z cache, jeśli takowy stworzycie (w przykładzie jest). Parametr $reset mówi nam, czy wyczyścić/odświerzyć ewentualny cache. Funkcja powinna zwracać następujące wartości:<?php public function GetUsersOnLine($refresh, $reset = false){ //cały kod formatujący wiadomość pomijam, gdyż jest za długi //możecie go podejrzeć w ściągnietej paczce } ?>
- array (tablica) - lista użytkowników zostanie zaktualizowana. Gdy tablica będzie pusta, oznaczać to będzie, ze nie ma aktualnie użytkowników on-line. Tablica ta może być jednowymiarowa lub dwuwymiarowa. Gdy będzie to tablica jednowymiarowa, jej elementami będą nazwy użytkowników. W przypadku tablicy dwuwymiarowej indexami tablicy są nazwy użytkowników, zaś wartościami tablica o indexach style (styl css dla nicka danego użytkownika) oraz class (nazwa klasy dla nicka danego użytkownika)
- każdy inny typ (najlepiej false lub null) - lista użytkowników nie zostanie odświerzona
- RunCommand()
Metoda odpowiada za wykonywanie komend. Podanie komendy polega na wpisaniu jako wiadomości czegoś takiego: /komenda argument, gdzie komenda to określona przez Was komenda, np. "help" a argument to argument komendy (dowolny tekst, który dopełnia komendę). Jeśli do ShoutBox zostanie wpisana komenda, zostanie wywołana ta metoda, która w parametrach wywołania dostanie komendę oraz jej argument. Na tej podstawie należy coś zrobić. Przykładowo jeśli wywołamy komendę help, zostanie wyświetlona krótka pomoc.<?php public function RunCommand($command, $arg){ //cały kod formatujący wiadomość pomijam, gdyż jest za długi //możecie go podejrzeć w ściągnietej paczce } ?>
ShoutBoxRights
Chcąc wykorzystać ten interfejs, trzeba napisać klasę, która go zaimplementuje:
<?php
class ShoutBoxDefaultRights implements ShoutBoxRights {
private $_nick;
private $_id;
function __construct($id, $nick){
$this->_id = $id;
$this->_nick = $nick;
}
}
?>
W pokazanym przykładzie klasa zawiera dwie właściwości prywatne: _nick oraz _id. Prawa w tym przykładzie będą ustalane właśnie na podstawie id oraz nicka. Przykładowo, jeśli ktoś ma nick nospor to automatycznie jest moderatorem całego shoutboxa. Wam proponuję zrobić to już bardziej profesjonalnie.
Przystąpmy teraz do implementacji metod interfejsu (należy pamiętać o tym, iż metody te mogą zwracać true lub false, w zależności czy ktoś ma do czegoś prawo czy nie; zwracany może być również tekst w przypadku gdy ktoś nie ma prawa do czegoś; tekst ten będzie wyświetlany użytkownikowi):
- CanEdit()
Metoda ta sprawdza, czy dany użytkownik może edytować wiadomość. Argument $message to rekord wiadomości. Jeśli zostanie przekazany do metody, to interesuje nas, czy dany użytkownik ma prawo edycji dla tej konkretnej wiadomości. Jeśli $message będzie nullem, wówczas interesuje nas ogólne prawo edycji, niezależnie od wiadomości. Jak już mówiłem, użytkownik nospor jest moderatorem, każdy inny uzytkownik, by móc edytować wiadomość, musi być jej właścicielem (musiał ją napisać).<?php public function CanEdit($message = null){ if ($this->_nick == 'nospor') return true; if ($message && !empty($this->_id) && $message['ID_USER']==$this->_id) return true; return 'Nie masz praw do edytowania tej wiadomości'; } ?>
- CanDelete()
Metoda sprawdza prawo do usuwania wiadomości. Sposób działania podobny do CanEdit.<?php public function CanDelete($message = null) { if ($this->_nick == 'nospor') return true; if ($message && !empty($this->_id) && $message['ID_USER']==$this->_id) return true; return 'Nie masz praw do usunięcia tej wiadomości'; } ?>
- CanAdd()
Metoda sprawdza prawo do dodawania wiadomości. Nie posiada żadnych argumentów wywołania. W pokazanym przykładzie goście oraz użytkwonik o nicku blocked nie mogą dodawać wiadomości.<?php public function CanAdd() { if (empty($this->_nick)) //goście nie mogą pisać return false; elseif ($this->_nick == 'blocked') //w tym przykładzie koleś o nicku "blocked" nie może nic pisać return 'Nie możesz dodawać wiadomości'; return true; } ?>
- CanRead()
Metoda sprawdza prawo do czytania wiadomości. Nie posiada żadnych argumentów wywołania. W pokazanym przykładzie goście nie mogą czytać wiadomości.<?php public function CanRead() { if (empty($this->_nick)) //goście nie mogą czytać return false; return true; } ?>
- CanReadHistory()
Metoda sprawdza prawo do przeglądania historii. Nie posiada żadnych argumentów wywołania. W pokazanym przykładzie goście nie mogą przeglądać historii, nospor może przeglądać całą historię, a pozostali użytkwonicy mogą tylko podejrzeć dwa poprzednie zakresy wiadomości.<?php public function CanReadHistory() { if (empty($this->_nick)) //goście nie mogą czytać return false; if ($this->_nick == 'nospor') //nospor może przeglądać historię do bólu
return true; //pozostali użytkwonicy tylko 2 razy mogą się cofnąć if ($_SESSION['history'] >= 2) return "Tylko nospor może przeglądać całą historię
"; $_SESSION['history']++; return true; } ?>
ShoutBoxDB
Jest to dość specyficzny interfejs i raczej większość z Was nie będzie pisać własnych klas do jego obsługi. Zapewne wystarczą Wam te dwie które sam napisałem. Jednak w następnym artykule postaram się opisać dokładniej i ten interfejs.