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()

  <?php
  public function SetShoutBoxObject(&$sbObj){
  	$this->_sbObj = $sbObj;
  }
  ?>

  Metoda ta ustawia obiekt shoutboxa, dzięki czemu będzie można później z niego skorzystać.
• TimeFormat()

  <?php
  public function TimeFormat($timestamp){
  	$d = date('Y-m-d', $timestamp); 
  	return '['.($d == $this->_today ? '' : ($d.' ')).date('H:i', $timestamp).']';
  }
  ?>

  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ę.
• NickFormat()

  <?php
  public function NickFormat($nick){
  	return $nick.':';
  }
  ?>

  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.
• AddingMessageFormat()

  <?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;
  }
  ?>

  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.
• ReformatMessage()

  <?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;
  }
  ?>

  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 "" na kod html właściwego obrazka, to ta metoda musi kod html obrazka zamienić nam spowrotem na "".
• GettingMessageFormat()

  <?php
  public function GettingMessageFormat($message){
  	return $message;
  }
  ?>

  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ą
• GetParameters()

  <?php
  public function GetParameters($row){
  	if (!empty($row['COLOR']))
  		return array('stylenick'=>'color:#'.$row['COLOR'].';');
  	else
  		return null;	
  }
  ?>

  Metoda ta zwraca tablicę dodatkowych parametrów (lub null), które zmienią nam wygląd wiadomości, czasu, nicka. Te parametry to:
  • 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
  Jak zapewne zauważyliście, w przykładzie tym ustalam kolor nicka na podstawie otrzymanej tablicy $row. Tablica ta zawiera rekord wiadomości.
• GetUsersOnLine()

  <?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
  }
  ?>

  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:
  • 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()

  <?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
  }
  ?>

  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.

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()

  <?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';
  	}
  ?>

  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ć).
• CanDelete()

  <?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';
  }
  ?>

  Metoda sprawdza prawo do usuwania wiadomości. Sposób działania podobny do CanEdit.
• CanAdd()

  <?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;
  }
  ?>

  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.
• CanRead()

  <?php
  public function CanRead() {
  	if (empty($this->_nick)) //goście nie mogą czytać
  		return false;
  	return true;
  }
  ?>

  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.
• CanReadHistory()

  <?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;
  }
  ?>

  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.

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.