Wiele osób, które jeszcze nie znają php i sql zadają pytania jak to ustrojstwo zainstalować. Postaram się tutaj to trochę przybliżyć. Instalacja będzie omawiana na wersji 1.1, która to oferuje różne sterowniki zapisu danych (baza MySql, pliki, inne). Jednak instalacja wcześniejszych wersji przebiegać będzie podobnie, z tą tylko różnicą, że do wyboru będziemy mieli tylko bazę MySql.

Przygotowanie struktury danych.

Jeśli będziemy korzystać ze sterownika MySql, musimy utworzyć tabelę na dane ShoutBoxa. W pliku shoutbox.sql mamy niezbędne do tego celu zapytania. Zapytania można wykonać np. w PhpMyAdmin. Na początek wykonajmy to zapytanie:

CREATE TABLE `ShoutBox` (
  `ID` int(11) unsigned NOT NULL auto_increment,
  `FK_USER` int(11) unsigned default NULL,
  `NICK` varchar(64) NOT NULL default '',
  `MESSAGE` text NOT NULL,
  `TIME` timestamp NOT NULL default '0000-00-00 00:00:00',
  PRIMARY KEY  (`ID`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8

Tworzy ono tabelę, która przechowuje wszystkie wiadomości. Jeśli zaś korzystamy ze sterownika operującego na plikach, krok ten możemy pominąć. Niezbędne pliki same się utworzą.

Jeśli nie posiadamy własnej tabeli MySql z użytkownikami naszego serwisu, a chcemy używać ShoutBoxa w takiej wersji w jakiej go dostarczam, należy jeszcze utworzyć tabelę użytkowników:

CREATE TABLE `ShoutBoxUser` (
  `ID` int(11) unsigned NOT NULL auto_increment,
  `NICK` varchar(64) NOT NULL default '',
  `PASS` varchar(40) NOT NULL default '',
  `COLOR` varchar(6) default NULL,
  `LAST_ACTIVE_TIME` timestamp NOT NULL default CURRENT_TIMESTAMP on update CURRENT_TIMESTAMP,
  PRIMARY KEY  (`ID`),
  UNIQUE KEY `NICK` (`NICK`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8;

Obsługa żądań ShoutBoxa

Mając przygotowaną już strukturę danych, przygotujmy obsługę żądań ShoutBoxa. Zawarta jest ona w pliku ShoutBox.php. Plik ten zawiera trochę kodu. Narazie opiszę podstawową formę:

<?php
$sb = new ShoutBox(new ShoutBoxDefaultFormatter(),$dbd,'./', $_SESSION['nick'], $_SESSION['id']);
$sb->RunAction();
$sb->GenerateWholeXML();

Pierwsza linia inicjalizuje obiekt ShoutBoxa. Przekazujemy do niej:

• obiekt formatera (patrz niżej)
• obiekt sterownika baz danych (patrz niżej)
• katalog ('./' - bieżący katalog), w którym ShoutBox będzie przechowywał swoje pliki
• nick piszącego wiadomość
• oraz ewentualnie ID piszącego wiadomość

Druga linia uruchamia obsługę żądania, a trzecia wysyła do przeglądarki odpowiedź z danymi. I to tyle. Proste, nieprawdaż?

Wzbogadźmy jednak naszego ShoutBoxa o pare dodatkowych funkcji:

• Komendy
  Komendy to takie coś, które wywoływane jest po wpisaniu do Shouta tekstu /komenda, gdzie zamiast słowa komenda należy wpisać naszą komendę, np. help, która wypisze na ekran ShoutBoxa krótką pomoc. A więc określmy nasze komendy:

  <?php
  $sb->commands = array('help','nick', 'me','color');
  ?>

  Obsługę komend należy jeszcze zdefiniować w formaterze, ale o tym później.
• Komunikaty floodowania

  <?php
  if ($sb->userMode & ShoutBox::F_LOCKED)
  $sb->AddAdminMessage('Zostałeś zablokowany za floodowanie.');
  elseif ($sb->userMode & ShoutBox::F_WARNED)
  $sb->AddAdminMessage('Nie floodować mi tu!!!');
  ?>

  Pierwszy if sprawdza, czy delikwent został zablokowany za floodowanie. Jeśli tak to informuje go o tym. Jeśli drugi if zwróci true, to użytkownik zostanie upomniany, by nie floodować, ale jeszcze go nie zablokuje.
• Użytkownicy on-line
  Jeśli udostępniamy jeszcze informację, kto jest on-line, to należy zapodać poniższy kod, który co 30 sekund zapisuje aktywność użytkownika:

  <?php
  if (empty($_SESSION['last_active_time']) || $_SESSION['last_active_time'] < $now - 30) {
  //co 30 sekund zapisujmy aktywnosc usera	
  $sql = 'update ShoutBoxUser set LAST_ACTIVE_TIME=now() where ID='.$_SESSION['id'];
  ShoutBoxDBMysql::MysqlConnect();
  $res = mysql_query($sql);
  if ($res !== false)
  $_SESSION['last_active_time'] = $now;
  }
  ?>

• Informacja o zalogowaniu
  Po zalogowaniu się użytkownika, zapisuję w sesji informację o tym. Poniższy kod odbiera tę informację i informuje o tym wszystkich użytkowników

  <?php
  if (!empty($_SESSION['justlogged'])){ 
  $_SESSION['justlogged'] = false;
  $sb->AddAdminMessage('<u>'.$_SESSION['nick'].'</u> dołączył', true);		
  }
  ?>

Implementacja interfejsów

ShoutBox udostępnia trzy interfejsy, dzięki którym każdy może dostosować go do własnych potrzeb. Jeśli jednak nie chcecie narazie się bawic w dostosowanie ShoutBoxa do siebie, wystarczy ż użyjecie przykładowych, które zdefiniowałem. Interfejsy, o których mowa to:

• 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
  Ostatni z interfejsów 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.

Każdy z interfejsów postaram się opisać w późniejszych artykułach (artykuł 1).

Publiczne właściwości

Klasa ShoutBox zawiera parę publicznych właściwości, które możecie ustawić by zmienić sposób działania. Są to:

• adminNick - nick admina, który będzie wyświetlany przy wiadomościach od admina. Domyślnie jest to ADMIN.
• floodTime - liczba sekund, w czasie których można napisać tylko jedną wiadomość. Domyślnie jest to sekunda.
• floodCount - określa ile razy dany użytkownik zostanie upomniany by nie floodował, zanim ostatecznie zostanie zablokowany. Domyślnie jest 3.
• floodLockTime - na ile sekund zablokować użytkownika za floodowanie. Domyślnie jest to 30 sekund.
• allowStringUserId - czy ID użytkownika podawane będzie jako tekst. Domyślnie ustawione na "nietekst", czyli liczbę.
• commands - tablica dozwolonych komend. Domyślnie nie ma żadnych komend.

Po stronie przeglądarki

To co napisałem do tej pory należało robić w php. Teraz czas na klienta. Wszystko znajduje się w pliku ShoutBoxDisplay.php. W pliku tym jest również logowanie, ale to już pominę. Zajmę się tylko samym wyglądem i inicjalizacją ShoutBoxa. Na początek należy wstawić kod html:

<div id="sb_main">
	<div id="sb_online"><div id="sb_online_title">Użytkownicy on-line:</div><div id="sb_online_users"></div></div>
	<div id="sb_tools"><div id="sb_history" class="sb_history" title="Pobierz wcześniejsze" onclick="sb.getHistory();"></div><div id="sb_scroll_locking" class="sb_unlocked" title="Zablokuj scroll" onclick="ShoutBox.switchScroll();"></div></div>
	<div id="sb_body"></div>
	<form onsubmit="sb.sendMessage();return false;">
	<input type="text" id="sb_message" maxlength="255" />
	<input type="submit" id="sb_submit" value="Wyślij" />
	</form>
</div>

Odpowiada on za rozmieszczenie naszego ShoutBoxa, które posiłkowane jest dołączonym css. Jest to przykładowy kod, Wy możecie te divy układać tak jak wam wygodnie. Możecie również dołożyć do tego inputa o id sb_nick. ShoutBox wyłapie go i będzie przesyłał jego wartość razem z wiadomością. Input ten oczywiście będzie wykorzystywany do pisania przez gości.Input taki pojawia się tu na stronie, gdy nie jesteśmy zalogowani.
Mając kod html, dodajmy kod js:

<script language="javascript">
	var sb = new ShoutBox('sb');
	sb.getMessages();
</script>

Pierwszym parametrem konstruktora jest id. Ważne jest, by zmienną obiektu ShoutBox nazwać tak samo jako id. Również pamiętajcie, by nadać id dla diva _body zaczynające się tym samym przedrostkiem co id ShoutBox. W tym przypadku chodzi o sb. Do konstruktora można jeszcze przekazać czas odświerzania w sekundach oraz adres skryptu odbierającego żądania. Ważne jest, by adres skryptu kończył się na ? lub &, gdyż będą dopisywane do niego inne parametru (planuje jednak zmienić ten wymóg i sam to ustawiać). Przykład pełnego wywołania:

<script language="javascript">
	var sb = new ShoutBox('sb',20, 'ShoutBox.php?');
	sb.getMessages();
</script>

ShoutBox z tego przykładu będzie odświerzać się co 20 sekund i kierować żądania do ShoutBox.php. Skrypt zawiera również komunikaty. Są to:

ShoutBox.txtScrollLock = 'Zablokuj scroll';
ShoutBox.txtScrollUnlock = 'Odblokuj scroll';
ShoutBox.txtFloodingLock = 'Blokada pisania jeszcze przez sekund: ';
ShoutBox.txtRemoveConfirm = 'Czy na pewno chcesz usunąć tę wiadomość?';
ShoutBox.txtRemoveError = 'Nie udało się usunść wiadomości';
ShoutBox.txtGettingError = 'Nie udało się pobrać danych';
ShoutBox.txtEditError = 'Nie udało się zmienić wiadomości';
ShoutBox.txtEditClick = 'Kliknij by edytować';

Możemy nadpisać te teksty na własne. Należy pamiętać by zrobić to przed inicjalizacją ShoutBox, np.:

<script language="javascript">
ShoutBox.txtRemoveConfirm = 'Nasz własny tekst potwierdzenia';
//inne podobnie
	var sb = new ShoutBox('sb');
	sb.getMessages();
</script>

No i niezapomnijmy oczywiście dołączyć niezbędnych skryptów js oraz css:

<head>
... tutaj jakies wasze rzeczy z head, a poniżej SHoutBox:
<link rel="stylesheet" href="css/ShoutBox.css" type="text/css" />
<!--[if IE]>
<link rel="stylesheet" type="text/css" href="css/ShoutBox_ie6.css" />
<![endif]-->
	
<script type="text/javascript" src="scripts/advajax.js"></script>
<script type="text/javascript" src="scripts/ShoutBox.js"></script>
</head>

Podsumowanie

To narazie tyle. Starałem się tu opisać uniwersalne podstawy instalacji, niezależnie na jakim systemie ta instalacja przebiegać będzie. ShoutBoxa można bez problemu podłączyć pod każdy serwis jaki macie, korzystając przy tym z mechanizmów tego serwisu.