Często dostaję pytania o integrację shoutboxa z Waszymi serwisami, w szczególności z systemem autoryzacji. Z racji, iż jest tego stosunkowo dużo, postaram się tu Wam przedstawić integrację shoutboxa z Waszym serwisem (na przykładzie wymyślonego serwisu). Integrację opiszę na najnowszej wersji ShoutBoxa czyli 1.3.1 - podejrzewam, iż na innych wersjach (tych przyszłych i tych wcześniejszych) wyglądać to będzie podobnie.

Autoryzacja

Zacznijmy od wymyślenia systemu autoryzacji w naszym zmyślonym serwisie, z którym będziemy integrować shoutbox. Pójdę na łatwiznę, nie będę wymyślał żadnych obiektów użytkownika itp. Cała autoryzacja będzie zapisana w sesji:

• $_SESSION['id'] - id zalogowane użytkownika
  Brak ustawionej tej wartości oznaczać będzie, iż użytkownik nie jest zalogowany
• $_SESSION['login'] - login zalogowane użytkownika
• $_SESSION['role'] - rola zalogowanego użytkownika
  Załóżmy, że użytkownicy mogą posiadać role, dające im różne uprawnienia. Niech to będą np.:
  • 1 - zwykły użytkownik
  • 2 - moderator
  • 3 - admin

Wszystkie te wartości ustawiane są w momencie logowania do serwisu, a czyszczone w momencie wylogowania.

Baza danych

Ok, teraz zajmiemy się przygotowanie bazy danych. Zakładam, że chcemy skorzystać ze wszystkich możliwości shoutboxa. W paczce shoutboxa znajduje się kod sql, do stworzenia tabel shoutboxa. Z racji, iż Wy już w swoim serwisie posiadacie tabelę użytkowników, nie musicie tworzyć mojej tabeli użytkowników (ShoutBoxUser). Tabela ta jednak zawiera kolor użytkownika. Aby więc tej informacji nie stracić, musicie pole COLOR dodać do swojej tabeli użytkowników poniższym kodem sql (zakładam, iż Wasza tabela użytkowników nazywa się np. user)

alter table user add column `COLOR` varchar(6) default NULL

No i jeszcze musicie utworzyc tabelę ShoutBox - jej kod sql znajduje się w pliku ShoutBox.sql

Konfiguracja

Załóżmy, że pliki shoutboxa z paczki wgracie do katalogu shoutbox do głównego katalogu swojej aplikacji (pliki: sblogin.php, sblogout.php, ShoutBoxDisplay.php - możecie wywalić - nie będą potrzebne.) W pliku cfg.inc.php znajduje się konfiguracja shoutboxa. Możecie tam określić poziomy kompresji, kto może czytać, pisać, dane do bazy danych itp. Przejrzyjcie ten plik, przeczytajcie uważnie komentarze i ustawcie co trzeba.

Html / javascript

Podpinamy teraz kod html, css i javascript, by wstawić na Waszą stronę shoutbox. Na początek wstawmy css i kod js. W sekcji HEAD kodu html wstawcie:

<link rel="stylesheet" href="shoutbox/css/ShoutBox.css" type="text/css" />
<!--[if IE]>
<link rel="stylesheet" type="text/css" href="shoutbox/css/ShoutBox_ie6.css" />
<![endif]-->
	
<script type="text/javascript" src="shoutbox/scripts/ShoutBox.js"></script>
<script type="text/javascript" src="shoutbox/scripts/jquery.js"></script>

Jak zapewne zauważyliście do paczki dołączyłem wersję jQuery. Jeśli macie u siebie jakąś nowszą to bez problemu możecie ją podłączyć zamiast tej z paczki.

Następnie dodamy kod html shoutboxa. Kod ten będzie warunkowany w kodzie php i będzie zależny od naszej konfiguracji z pliku cfg.inc.php oraz faktu, czy jesteśmy zalogowani czy nie. Aby skorzystać z konfiguracji trzeba dołączyć plik cfg.inc.php

<?php
require_once('shoutbox/cfg.inc.php');
?>

No i teraz html shoutboxa. Będziemy go warunkować faktem, czy użytkownik jest zalogowany czy nie oraz ustawieniami z pliku konfiguracyjnego. Kod ten wstawcie tam na stronie, gdzie chcecie wyświetlić shoutbox.

<?php
//jesli jestesmy zalogowani lub jestemy gosciem i goscie moga czytac
if (!empty($_SESSION['id']) || $cfg_shoutbox['guest_read']){
echo '
<div id="sb_main">
	<div class="sb_online"><div class="sb_online_title">Użytkownicy on-line:</div><div class="sb_online_users"><ul id="sb_online_users"></ul></div></div>
	<div class="sb_tools"><div id="sb_history" class="sb_history" title="Pobierz wcześniejsze" onclick="sb.getHistory();"></div><div class="sb_unlocked" title="Zablokuj scroll" onclick="ShoutBox.switchScroll(this);"></div></div>
	<div id="sb_body"></div>
';
if (!empty($_SESSION['id']) || $cfg_shoutbox['guest_write']){ //jesli jestesmy zalogowani lub goscie mogą pisac
	echo '<form onsubmit="sb.sendMessage();return false;">';
	if (empty($_SESSION['id'])){
		echo '<input type="text" id="sb_nick" maxlength="64" value="nick" onfocus="if (this.value==\'nick\')this.value=\'\';"/>
		<input type="text" id="sb_message" class="short" maxlength="255" value="wiadomość" onfocus="if (this.value==\'wiadomość\')this.value=\'\';"/>';
	}
	else
		echo '<input type="text" id="sb_message" maxlength="255" />';
	echo '<input type="submit" id="sb_submit" value="Wyślij" />
	</form>';
}	
echo '
</div>
<div id="sb_footer"><div id="sb_wait"></div><a href="http://nospor.pl/shoutbox.html">ShoutBox 1.3.1</a> © Robert (nospor) Nodzewski</div>
<script type="text/javascript">
';
	echo "var sb = new ShoutBox('sb', $cfg_shoutbox[refresh_time],'$cfg_shoutbox[link]','$cfg_shoutbox[type]');";
echo '
	sb.getMessages();
</script>';
}
?>

Po wstawieniu tego kodu shoutbox powinien już ajax'em wysyłać żądania do serwera w celu pobierania danych. Możecie to łatwo zaobserwować przy pomocy FireBuga - dodatku do FireFoxa.

PHP

Teraz zajmiemy się dostosowaniem kodu php. ShoutBox, gdy wyświetla wiadomości i dodaje nowe, odwołuje się do pliku ShoutBox.php. Pierwsze zmiany zróbmy więc tam - poniższy kod:

<?php
if (empty($_SESSION['nick']) && !$cfg_shoutbox['guest_read']) //jeśli to gość i ustawimy w konfigu że nie może czytać, to go wywalamy
	exit;

if (!empty($_SESSION['nick'])){
	$nick = $_SESSION['nick'];
	$id = $_SESSION['id'];
} else {
	$nick = empty($_POST['nick']) ? null : htmlspecialchars($_POST['nick'], ENT_QUOTES);
	$id = null;
}
?>

zamieńmy na:

<?php
if (empty($_SESSION['id']) && !$cfg_shoutbox['guest_read']) //jeśli to gość i ustawimy w konfigu że nie może czytać, to go wywalamy
	exit;

if (!empty($_SESSION['id'])){
	$nick = $_SESSION['login'];
	$id = $_SESSION['id'];
} else {
	$nick = empty($_POST['nick']) ? null : htmlspecialchars($_POST['nick'], ENT_QUOTES);
	$id = null;
}
?>

Z racji, iż mamy własną tabelę użytkowników, musimy zmienić tabelę z użytkownikami, którą dołączamy. Zamieniamy więc kod:

<?php
$dbd->SetExtraUser('ShoutBoxUser', 'ID', array('COLOR'=>'COLOR'));
?>

na (przypominam, iż założyliśmy, że nasz tabela z użytkownikami nazywa się user):

<?php
$dbd->SetExtraUser('user', 'ID', array('COLOR'=>'COLOR'));
?>

Przyjąłem również, że id użytkownika to pole ID. Jeśli u Was nazywa się inaczej to zmieńcie ID na to Wasze.

Jeśli chcecie wyświetlać użytkowników online (a zapewne chcecie) i nie macie w tabeli użytkowników pola z ostatnią aktywnością użytkownika, to dodajcie je do siebie przy pomocy zapytania:

alter table user 
add column `LAST_ACTIVE_TIME` timestamp NOT NULL default CURRENT_TIMESTAMP on update CURRENT_TIMESTAMP

a następnie zamieńcie kod:

<?php
$sql = 'update ShoutBoxUser set LAST_ACTIVE_TIME=now() where ID='.$_SESSION['id'];
?>

na:

<?php
$sql = 'update user set LAST_ACTIVE_TIME=now() where ID='.$_SESSION['id'];
?>

Prawa

Z ważnych rzeczy pozostały jeszcze prawa. Zalogowany użytkownik może więcej niż niezalogowany, moderator może więcej niż zwykły użytkownik. Zarządzanie prawami odbywa się w pliku libs/ShoutBoxDefaultRights.class.php. Należy zmienić w nim kod:

<?php
$this->Logged = !empty($_SESSION['nick']);
?>

na:

<?php
$this->Logged = !empty($_SESSION['id']);
?>

i już. Prawa załatwione. To czy ktoś jest moderatorem czy nie określa wpis w pliku konfiguracyjnym (pamiętacie jak kazałem Wam się z tym plikiem zaznajomić). Jednak jeśli chcecie w pełni skorzystać z systemu uprawnień Waszego serwisu (na początku tego artykułu napisałem, że zakładamy podział na zwykłego użytkownika, moderatora i admina) to zmodyfikujcie kod:

<?php
public function IsModerator(){
	return $this->Logged && in_array($this->Nick,$this->ModNick);
}
?>

Dodajcie do tego systemowe uprawnienia:

<?php
public function IsModerator(){
	return $this->Logged && ($_SESSION['role'] == 2 || $_SESSION['role'] == 3);
}
?>

Teraz można powiedzieć, że shoutbox został zintegrowany z systemem autoryzacji i uprawnień.

Wyświetlanie

Co bardziej wybredni z Was zapewne będą chcieli zmodyfikować sposób wyświetlania. Za wyświetlanie odpowiada plik libs/ShoutBoxDefaultFormatter.class.php. Załóżmy, że w tabeli user znajduje się pole RANGA, które zawiera np. wartości: masta, laik, wymiatacz. Chcecie te pole wyświetlać obok nicka użytkownika. W tym celu należy powiedzieć, że chcemy pobrać dodatkowe pole z tabeli użytkownika (robimy to w pliku ShoutBox.php):

<?php
$dbd->SetExtraUser('user', 'ID', array('COLOR'=>'COLOR','RANGA'=>'RANGA'));
?>

a następnie w pliku libs/ShoutBoxDefaultFormatter.class.php zamieniamy:

<?php
public function HtmlMessage($message){
	$owner=!empty($message['ADMIN']) ? '_a' : ((empty($message['ID_USER']) && empty($message['NICK'])) ? '_s' : (!empty($message['ID_USER']) && $message['ID_USER'] == $this->_sbObj->GetIdUser() ? '_o' : ''));
	$this->GettingMessageFormat($message);
	$id = $this->_sbObj->GetId();
	return '<div id="'.$id.'_m'.$message['ID'].'" class="sb_m'.$owner.'">'.
				($message['CAN_DELETE'] ? '<div class="sb_d" onclick="'.$id.'.dm('.$message['ID'].');"/>' : '').
				'<span class="sb_t">'.$message['TIME'].'</span>'.
				'<span class="sb_n"'.(!empty($message['COLOR']) ? ' style="color:#'.$message['COLOR'].'"' : '').'>'.$message['NICK'].'</span>'.
				'<div class="sb_tt'.($message['CAN_EDIT'] ? ' sb_e' : '').'"'.($message['CAN_EDIT'] ? ' title="Kliknij, by edytować" onclick="'.$id.'.tti('.$message['ID'].');"' : '').'>'.
					'<span> '.$message['MESSAGE'].' </span>'.
				'</div>'.
			'</div>';
}
?>

na (w zasadzie dopisujemy tylko $message['RANGA'].' '.):

<?php
public function HtmlMessage($message){
	$owner=!empty($message['ADMIN']) ? '_a' : ((empty($message['ID_USER']) && empty($message['NICK'])) ? '_s' : (!empty($message['ID_USER']) && $message['ID_USER'] == $this->_sbObj->GetIdUser() ? '_o' : ''));
	$this->GettingMessageFormat($message);
	$id = $this->_sbObj->GetId();
	return '<div id="'.$id.'_m'.$message['ID'].'" class="sb_m'.$owner.'">'.
				($message['CAN_DELETE'] ? '<div class="sb_d" onclick="'.$id.'.dm('.$message['ID'].');"/>' : '').
				'<span class="sb_t">'.$message['TIME'].'</span>'.
				'<span class="sb_n"'.(!empty($message['COLOR']) ? ' style="color:#'.$message['COLOR'].'"' : '').'>'.$message['RANGA'].' '.$message['NICK'].'</span>'.
				'<div class="sb_tt'.($message['CAN_EDIT'] ? ' sb_e' : '').'"'.($message['CAN_EDIT'] ? ' title="Kliknij, by edytować" onclick="'.$id.'.tti('.$message['ID'].');"' : '').'>'.
					'<span> '.$message['MESSAGE'].' </span>'.
				'</div>'.
			'</div>';
}
?>

Przejrzyjcie sobie ten plik dokładnie i dostosujcie wyświetlanie do własnych potrzeb.

Użytkownicy online

Również w pliku libs/ShoutBoxDefaultFormatter.class.php znajduje się metoda do pobierania użytkowników online. Z racji, iż mamy inną tabelę z użytkownikami, musimy zmodyfikować w niej kod:

<?php
$sql = 'select NICK, COLOR from ShoutBoxUser where DATE_SUB(NOW(),INTERVAL 40 SECOND) <= LAST_ACTIVE_TIME order by NICK';
?>

Przyjmuję, iż w Waszej tabeli user login użytkownika znajduje się w polu LOGIN - jeśli macie inne pole, to zmieńcie tylko nazwe. Kod po zmianach wyglądać więc będzie tak (zostawiam as NICK by nie musieć robić innych zmian):

<?php
$sql = 'select LOGIN as NICK, COLOR from user where DATE_SUB(NOW(),INTERVAL 40 SECOND) <= LAST_ACTIVE_TIME order by LOGIN';
?>

Komendy

Klasy z komendami znajdują się w katalogu libs/commands. Tam również trzeba zmienić to i owo.

ShoutBoxCommandColor.class.php
Zmieniamy kod:

<?php
$sql = "update ShoutBoxUser set COLOR='$_color' where ID=".$_SESSION['id'];
?>

na

<?php
$sql = "update user set COLOR='$_color' where ID=".$_SESSION['id'];
?>

ShoutBoxCommandMe.class.php
Zmieniamy kod $_SESSION['nick'] na $_SESSION['login'].

ShoutBoxCommandNick.class.php
Zmieniamy kod:

<?php
$sql = "update ShoutBoxUser set NICK='$_nick' where ID=".$_SESSION['id'];
?>

na

<?php
$sql = "update user set LOGIN='$_nick' where ID=".$_SESSION['id'];
?>

Jeśli nie chcecie pozwalać na zmianę nicka poprzez ShoutBox to na początku funkcji Run dajcie kod:

<?php
public function Run($arg, ShoutBox $sbObject, ShoutBoxDB $dbObject, ShoutBoxFormatter $formatterObject, ShoutBoxRights $rightsObject){
$sbObject->AddAdminMessage('Komenda zmiany nicku została wyłączona');
return true;
//...dalsza część kodu funkcji Run
?>

Rozwiązywanie problemów

Jeszcze mała wstawka odnośnie rozwiązywania problemów, na które możecie natrafić. W pierwszej kolejności zainstalujcie sobie dodatek FireBug do FireFoxa. Bardzo pomoże w analizie żądań ajaxowych jakie generuje shoutbox. Analizując odpowiedzi, jakie zwracać będzie ajax, będzie mogli szybko określić błąd, albo chociaż mi podać szczegóły.

Kolejną ważną sprawą jest sprawdzenie pliku temp/ShoutBox.log - zapisywane tam są błędy skryptu. Bardzo ważną rzeczą jest nadanie odpowiednich uprawnień na katalog temp, by skrypt mógł do niego pisać.

Podsumowanie

Mam nadzieję, iż podany tu opis jest w miarę czytelny i Wam pomoże. W razie pytań piszcie śmiało. Postaram się Wam w miarę możliwości pomóc i ewentualnie poprawię tego arta, jeśli okaże się, że coś zawile opisałem.

I jeszcze na koniec wspomnę o plikach które modyfikujecie: libs/ShoutBoxDefaultFormatter.class.php oraz libs/ShoutBoxDefaultRights.class.php. Są to domyślne sterowniki napisane przeze mnie. Jeśli zamierzacie robić w nich jakieś zmiany dobrze by było, byście nie modyfikowali tych plików bezpośrednio, tylko stworzyli własne, np: libs/ShoutBoxMyFormatter.class.php oraz libs/ShoutBoxMyRights.class.php i tam nanieśli własne poprawki. Pozwoli to uniknąć nadpisania tych plików, gdy wgram kolejną wersję shoutboxa. Jeśli tak zrobicie to pamiętajcie, by w pliku ShoutBox.php zmienić odwołania do tych plików.