	Badwords2 Text Filtering/Flushing Component
	Dodatek PHP API - Komponent dla systemw zarzdzania treci i dynamicznych portali: Joomla 1.x i Mambo Open Source 4.5.x
	By the Badwords2 Development Team
	Senior Developer - Wim Albers (walb)
	Developer/SimpleBoard Integration Assistance - Niels Vandekeybus (progster)
	Project Management/QA & Testing - Robert Anthony Pitera (rpitera)
 
	Specjalne podzikowania dla Jan De Graaf i Two Shoes Mambo Factory za Project Assistance and Support.
 
	Oparty na oryginalnym komponencie 'Badword Filter', ktry napisa Pravin Hegde, rozszerzonej wersji 'Badword Filter', ktej autorem jest Wim Albers oraz sugestiach, jakie sformuowa 												Robert Anthony Pitera.

   Komponent	Badwords2 Text Filtering/Flushing jest bezpatnym programem
	upowszechnianym na warunkach licencji GNU/GPL : http://www.gnu.org/copyleft/gpl.html
   Wersja 1.0 beta

   Polska adaptacja
   Stefan Wajda - Koordynator Polskiego Centrum Joomla!
	http://www.joomla.pl
	http://www.joomlademo.pl   

Co to jest?


Komponent Badwords2 Text Filtering/Flushing jest w gruncie rzeczy dodatkiem Joomla 1.x i Mambo Open Source 4.5.x i wyszych. W gruncie rzeczy, bo jak dodatek [mambot] dziaa w warstwie API, a wic wykonuje na zawartoci jak operacj, zanim zostanie ona  pokazana na stronie.


Dodatkowe, specjalne rozwizanie przygotowano dla integracji z komponentem SimpleBoard Forum wydanym przez Two Shoes Mambo Factory, ale instrukcje integrujce mog by wczone do innych komponentw i moduw. Integracja Badwords2 z SimpleBoard bdzie dokonana w przyszym wydaniu forum, jako cz dystrybucji, ale pliki integrujce umieszczone s rwnie w tym wydaniu Badwords2.

Badwords2 wspiera Joomla 1.x i Mambo Open Source 4.5.x oraz wysze, ale wersja Badword Extended autorstwa Wima Albersa dostpna jest rwnie dla wczeniejszych wersji Mambo.



Jak dziaa?

Podstawowe waciwoci:
 - Zastpowanie gwiazdkami liter w sowach niepodanych, definiowanych za pomoc
   panelu administracyjnego komponentu (tzn. BrzydkiWyraz wywietlany jest  jako ***********
 - Wyszukiwanie i filtrowanie sw niepodanych bez wzgldu na wielko liter.
 - Zastosowanie we wzorcach sw  niepodanych znaku specjalnego (*) do wykrywania 
   alternatywnyh form wyrazu  (m.in.gramatycznych)
 - Zachowywanie w bazie danych oryginalnego tekstu - NIEDESTRUKCYJNY charakter, nie niszczy autentycznych wpisw.
 - Pene zarzdzanie za pomoc panelu administracyjnego Joomla!/Mambo
 - Jedna linia w API przeprowadza filtrowanie/oczyszczanie kadego komponentu Joomla/Mambo.
 - Moliwo wczania i wyczania funkcjonalnoci Badwords2 filtering/flushing.
 - Tworzenie w panelu administracyjnym sownika sw niepodanych niezalenych od stosowanego w witrynie jzyka.
 - Moliwo (opcja) zaawansowanego filtrowania w wyniku zastosowania wyrae regularnych, 
   konfigurowanych w panelu administracyjnym.
 - Opcja zezwalania uytkownikom ze specjalnymi prawami na uywanie niestosownych sw.


SimpleBoard - Waciwoci integracji  (*tylko* SB 1.1.0 Stable)
 - Filtrowanie niepodanych sw we WSZYSTKICH widokach, take z RSS, PDF i poczcie elektroniczej.
 - Automatyczne rozpoznawanie administratorw oraz moderatorw i wywietlanie w NIEPRZEFILTROWANYCH tekstw.
 - Przesyanie do moderatora poczt elektroniczn powiadomie z tekstem przefiltrowanym i nieprzefiltrowanym
 - Filtrowanie wynikw wyszukiwania, wywietlanie przefiltrowanych wynikw wyszukiwania.
 - Uniemoliwienie uytkownikom kocowym wyszukania tekst ze sowami niecenzuralnymi, 
   wpisanymi do sownika - rezultat wyszukiwania = 0.
 - Doczony modu  Last 5 Posts (Ostatnie 5 postw)z funkcj filtrowania/zastpowania

AkoComment - waciwoci integracji (*tylko* AkoComment 2.0)
 - Filtrowanie niepodanych sw w komentarzach 
 - Automatyczne rozpoznawanie edytorw, publikatorw oraz administratorw i wywietlanie NIEPRZEFILTROWANYCH tekstw
 - Przesyanie do administratora poczt elektroniczn powiadomie z tekstem przefiltrowanym i nieprzefiltrowanym
 - Wsparcie dla konfiguracji wiadomoci
 - Zakadka Integracja z Bw2 w Ustawieniach komponentu, umoliwiajaca wczenie bd wyczenie filtrowania.

AkoBook - waciwoci integracji (*tylko* AkoBook 3.4.2)
 - Filtrowanie niepodanych sw we wpisach do Ksigi Goci
 - Automatyczne rozpoznawanie edytorw, publikatorw oraz administratorw i wywietlanie NIEPRZEFILTROWANYCH tekstw
 - Przesyanie do administratora poczt elektroniczn powiadomie z tekstem przefiltrowanym i nieprzefiltrowanym
 - Wsparcie dla konfiguracji wiadomoci
 - Zakadka Integracja z Bw2 w Ustawieniach komponentu, umoliwiajaca wczenie bd wyczenie filtrowania.

CommunityBuilder - waciwoci integracji (*tylko* CommunityBuilder 1.0 RC1)
 - Filtrowanie niestosownych sw w zakadce forum Simpleboard - w temtach postw i nazwach uytkownikw.
 - Automatyczne rozpoznawanie administratorw oraz moderatorw i wywietlanie w NIEPRZEFILTROWANYCH tekstw.

 Mambot bot_badwords2
 - Zastpowanie liter niecenzuralnych sw w tytuach i tekstach artykuw.
 - AUTOMATYCZNE rozpoznawanie uytkownikw ze specjalnymi uprawnieniami (z grupy Special) - wywietlanie w ich widoku nieprzeksztaconych, oryginalnych tekstw. 
 
 
Jak zainstalowa Badwords2?

Aby korzysta z waciwoci komponentu Badwords2, zainstaluj komponent jedn ze standardowych procedur instalacyjnych dla Joomla!/Mambo  (z pakietu albo z katalogu na serwerze). Wykonaj nastpujce czynnoci:

1. Wybierz w panelu administratora opcj Instalatory => Komponenty.
2. Znajd i wska na Twoim dysku lokalnym spakowany pakiet instalacyjny albo wska katalog na serwerze,
   do ktrego przesae rozpakowane pliki pakietu instalacyjnego.
3. Nacinij przycisk Wczytaj i zainstaluj 
						 

Korzystajc z integratorw Badwords2 z dodatkowymi skadnikami dla Joomla/Mambo opracowywanmi przez rnych programistw, a zaczonymi do pakietu dystrybucyjnego Badwords2, zapoznaj si z objanieniami w plikach README.TXT, wczonych do spakowanych pakietw. 
WANE : przeczytaj kad instrukcj integracji BARDZO UWANIE. W kadym przypadku bdziesz zastpowa plik nalecy do oryginalnej dystrybucji plikiem z wersji Badwords2. Jeli wprowadzae jakiekolwiek specjalne modyfikacje w oryginalnych skryptach, prawdopodobnie zechcesz je zachowa. Std moesz wykona integracj z Badwords 2 "rcznie" przez porwnanie oryginalnego skryptu ze skryptem integrujcym z Badwords2. We wszystkich przypadkach nasz zmodyfikowany kod jest skomentowany. Wyszukaj w skrypcie sowo "badword", aby znale modyfikacje.



Jak stosowa?
Badwords2 jest dodatkiem do API, pracuje w tle, nie wymaga jakiejkolwiek interwencji administratorw. Dysponujesz jednak kilkoma moliwociami dostosowania Badwords 2 do Twoich specyficznych potrzeb.

1. Sownik wyrazw niecenzuralnych: W sowniku znajdziesz dwa przykadowe nieprzyzwoite sowa ("zeslowo1" 
   i "zleslowo2" ), z ktrych moesz skorzysta do przetestowania komponentu. 
   Moesz je, oczywicie, zmieni na dowolne inne.
   Aby doda nowy wyraz do sownika, kliknij ikon lub odsyacz  'Nowy' w pasku narzdzi, nastpnie wpisz w polu formularza nowe sowo  i kliknij odsyacz lub ikon 'Zapisz'.
   Aby zmodyfikowa wyraz umieszczony w sowniku, zaznacz w wykazie pole wyboru obok tego wyrazu,
   a nastpnie kliknij ikon lub odsyacz 'Edytuj' w pasku narzdzi. Moesz rwnie po prostu klikn na sowo. Przejdziesz do formularza edycji. Zmie wpisany tekst, a nastpnie  kliknij odsyacz lub ikon 'Zapisz'.
   Aby usun wyraz ze sownika, zaznacz pole wyboru obok tego sowa w wykazie, a nastpnie kliknij ikon lub odsyacz 'Usu' w pasku narzdzi.


Badwords2 moe filtrowa sowa w ich dosownym brzmieniu. Ale atwo i skutecznie moesz rwnie zapobiec prbom omijania przez uytkownikw regu filtowania sztuczkami typu zastpienie jednego  znaku przez inny, np. 'U' z 'V'. Posu si odpowiednim wzorcem sowa w sowniku, pamitajc o moliwoci takich prb.

Wpisane w wykazie sowa s cigami  (strumieniami znakw), moesz uywa Badwords2 z dowolnym jzykiem. 
Dodatkowo interfejs Badwords2 zawiera wsparcie dla jzyka angielskiego, holenderskiego i polskiego. Jeli jeste zainteresowany przygotowaniem tumaczenia dla Twojego rodzimego jzyka, prosimy o kontakt!  Chtnie wczymy Twj jzyk do dystrybucji komponentu i wyrazimy Ci stosowne podzikowania!

Badwords2 wspiera uywanie w sowach wzorcowych znakw specjalnych, umoliwiajcych wyszukiwanie niecenzuralnych wyrazw zastosowanych w rnych formach alternatywnych. Najlepiej pozna sposb zastosowania znaku specjalnego  na przykadach zamieszczonych poniej,  pokazujcych skutki zastosowania uniwersalnego znaku (*)  na pocztku lub kocu sowa 'pieprz'.

UWAGA:  JAKO ZNAK SPECJALNY MOESZ ZASTOSOWA TYLKO GWIAZDK! Jeli potrzebujesz wikszej elastycznoci, rozwa wykorzystanie wyrae regularnych. 

Jeli zdefiniowane sowo = "pieprz" (dokadnie, cig "pieprz" jest jednym caym sowem), to rezultat filtrowania bdzie nastpujcy:

pieprz 	  		= ******
Pieprz	  		= Pieprz
Popieprzony		= Popieprzony
popieprz	  		= popieprz
Pieprzony  		= Pieprzony
pieprz go		= ****** go 

Jeli zdefiniowane sowo = *pieprz (dokadnie, cig "*pieprz" jest jednym caym sowem  I/LUB jest poprzedzony jakimikolwiek innymi znakami, to rezultat filtrowania bdzie nastpujcy:

pieprz 			= ******
Pieprz 			= Pieprz
Popieprzony 		= Popieprzony
popieprz 		= po******
Pieprzony 		= Pieprzony
pieprz go 		= ****** go 



Jeli wpisane sowo = "pieprz*"  (dokadnie, cig znakw "pieprz" jest caym sowem I/LUB zawiera jakie znaki po tym cigu), wtedy rezultat filtrowania bdzie nastpujcy:

pieprz 			= ******
Pieprz 			= ******
Popieprzony 		= Popieprzony
popieprz 		= popieprz
Pieprzony 		= ******ony
pieprz go 		= ****** go  

Jeli wpisane sowo = "*pieprz*"  (dokadnie, cig znakw "pieprz" jest caym sowem I/LUB zawiera jakie znaki przed tym cigiem i po tym cigu), wtedy rezultat filtrowania bdzie nastpujcy:

pieprz 			= ******
Pieprz 			= ******
Popieprzony 		= Po******ony
popieprz 		= po******
Pieprzony 		= ******ony
pieprz go 		= ****** go 


2) Wyraenie regularne (w skrcie: regex albo regexp) s sposobem porwnywania cigw ze znakami specjalnymi,  ktre zastpuj wiksze porcje cigu docelowego. Prawdopodobnie znasz ju takie znaki specjalne, jak * [gwiazdka], ktra w wyraeniu *.txt oznacza, e naley wyszuka w katalogu wszystkie pliki,  z rozszerzeniem .txt. Gwiazdka zastpuje tutaj wszystkie znaki nazwy. Ekwiwalentne wyraenie regularne miaoby nastpujcy ksztat: .*\.txt

Zastosowanie wyrae regularnych nie jest wymagane, by Badwords2 wykrywa i filtrowa niecenzuralne fragmenty tekstu. Jeli nie jeste dobrze zaznajomiony ze stosowaniem wyrae regularnych, ich skadni, proponujemy Ci pozostawi przykad tak, jak zosta umieszczony. Jeli chcesz zapozna si bliej z t problematyk,  skorzystaj z poradnika zamieszczonego TUTAJ - http://weblogtoolscollection.com/regex/regex.php, objaniajcego podstawy, przykady stosowania,  funkcje PHP korzystajce z wyrae regularnych.


Uproszczone zasady wyrae regularnych w stylu POSIX, z ktego korzysta Badwords2, s nastpujce:

 - Znaki, ktre nie s znakami specjalnymi, s porwnywane dosownie. 
   Przykadowo - litera we wzorcu jest porwnywana z liter w cigu.
 - Znak specjalny ^ oznacza tylko pocztek cigu, a znak $ oznacza tylko koniec cigu.
 - Znak specjalny . [kropka] oznacza dowolny znak.
 - Znak specjalny * [gwiazdka] oznacza zero (0) lub wicej miejsc wystpienia poprzedniego wyraenia regularnego.
 - Znak specjalny + [plus] oznacza jedno lub wicej miejsc wystpienia poprzedniego wyraenia.
 - Zestaw znakw otoczony nawiasami kwadratowymi zastpuje dowolny z tych znakw, np. [ab] zastpuje zarwno a,
   jak i b. Mona rwnie poda zakres znakw w nawiasach, uywajc kreski: [a-c] zastpuje a, b lub c.
 - Znaki specjalne poprzedzone znakiem ukonika \ trac specjalne znaczenie i s porwnywane dosownie.

Aby doda nowe wyraenie regularne, wybierz t opcj z menu administratora, a nastpne kliknij w pasku narzdzi ikon lub odsyacz 'Nowy' i wpisz je w polu tekstowym. Moesz redagowa lub usuwa wyraenia regularne, uywajc instrukcji omwionych powyej w punkcie Sownik nieprzyzwoitych wyrae

3) Uytkownicy ze specjalnymi prawami:  Badwords2 pozwala Ci w atwy sposb "upowani" uytkownikw ze specjalnymi uprawnieniami do stosowania w swoich tekstach sw wykluczonych, umieszczonych w sowniku nieprzyzwoitych wyrae. Aby doda uytkownika ze specjalnymi uprawnieniami, wybierz odpowiedni opcj z menu komponentu, a nastpnie kliknij w ikon lub odsyacz 'Nowy' i wpisz w polu formularza nazw uytkownika Joomla!/Mambo. Podobnie jak poprzednio - moesz modyfikowa lub usuwa uytkownikw z uprawnieniami specjalnymi, uywajc instrukcji omwionych powyej w punkcie Sownik nieprzyzwoitych wyrae. 
Uwaga: Nadajc to uprawnienie, musisz uy cile takiej nazwy uytkownika, jaka znajduje si w rejestrze uytkownikw witryny w polu Nazwa uytkownika. Upewnij si, e wprowadzie poprawn nazw.



4) Ustawienia: Znaczenie opcji konfiguracyjnych wskazuj etykiety ekranowe i dodatkowe objanienia. 

	Wcz filtrowanie [Perform Filtering]  - wcza lub wyacza filtrowanie przez Badwords2. ('Tak' - wcz filtrowanie nieprzyzwoitych sw. Ustawienie domylne, UWAGA: 'Nie' - wycza filtrowanie nieprzyzwoitych sw w CAYM Joomla!/Mambo!, we wszystkich komponentach, w ktrych jest zaimplementowane) 

	Zastosuj wyraenia regularne [Apply RegExp] - wcza lub wyacza korzystanie przez Badwords2 z wyrae regularnych. ( 'Nie' - nie korzystaj w filtrowaniu z wyrae regularnych (ustawienie domylne), 
	'Tak'  - zastosuj wyraenia regularne w filtrowaniu.

	Akceptuj odstpstwa uytkownikw z grupy Specjal [Allow Special User Exceptions for Badwords2] - Umoliwia uytkownikom ze specjalnymi uprawnieniami stosowanie wyrazw umieszczonych w sowniku niecenzuralnych ('Tak' - uytkownicy z listy ze specjalnymi uprawnieniami mog uywa dowolnych sw i wyrae (ustawienie domylne),
	'Nie' - ADEN uytkownik nie moe stosowa nieprzyzwoitych sw, wcznie z moderatorami i administratorami.)

5) O Badwords 2:  Pokazuje numer wersji komponentu, podzikowania, informacje kontaktowe, informacje o wsparciu oraz ten plik pomocy.



Jak mog doda Badwords2 Flushing/filtering do "Applikacji XYZ"?

Komponent zadziaa, jeli dokonasz odpowiednich modyfikacji w skryptach posyajcych do bazy danych  
zawarto, ktra bdzie wywietlana w serwisie.
Moesz skorzysta z dwch dostpnych opcji:
   1. Badword Extended Filter
   2. Badwords2 Text Filtering/Flushing
   
Badword Extended Filter: cenzor nieprzyzwoitych tekstw jest komponentem, dziaajcycm w warstwie programowej. Filtruje teksty zawierajace nieprzyzwoite sowa i wyraenia. Zamiast zawierajcego je tekstu, wywietla komunikat informujcy, i tekst zosta ocenzurowany (tre komunikatu naley zadeklarowa w pliku komunikatw jzykowych komponentu Joomla/Mambo i uy zmiennej lub wpisa bezporednio do skryptu). 


Wcz plik components/com_badwords2/class.badwords2.filter.php do pliku .php komponentu instrukcj:
  require_once( 'components/com_badwords2/class.badwords2.filter.php' );
Wywoaj: 
  Badword::Filter(text, user)
aby w rezultacie API zwrcio nastpujcy wynik:
  1 - "true" - jeli tekst zawiera nieprzyzwoite sowo, czyli dokona zastpienia tekstu komunikatem
  0 - "false"- jeli tekst nie zawiera nieprzyzwoitych sw, czyli wywietli wprowadzony tekst


Badwords2 Text Filtering/Flushing: cenzor nieprzyzwoitych sw jest komponentem, dziaajcycm w warstwie programowej. Filtruje nieprzyzwoite sowa i wyraenia w tekstach generowanych przez skadniki (komponenty) Joomla/Mambo. W odnalezionych sowach zastpuje niecenzuralne fragmenty gwiazdkami. 

Wcz plik components/com_badwords2/class.badwords2.filter.php do pliku .php komponentu instrukcj:
   require_once( 'components/com_badwords2/class.badwords2.filter.php' );
Wywoaj: 
   Badword::Flush(text, user)
aby w rezultacie API: zastpio znakiem * 
kady znak w sowie lub wyraeniu zawierajacym niecenzuralny tekst (w kadym znalezionym przypadku).



Przykady zastosowania
----------------
Dodaj nastpujce linie w stosownych miejscach skryptu php komponentu

// Filtrowanie niecenzuralnych tekstw
require_once( 'components/com_badwords2/class.badwords2.php' );

// $msg  jest tekstem do filtrowania
// $my jest uytkownikiem joomla/Mambo - zmienna globalna 
$expletivesExist = Badword::filter($msg, $my); 

if ($expletivesExist == 0)
 {
	// wykonaj polecenie: ( instrukcje - wpisz je tutaj)
 } 
else 
 {
	// filtruj wiadomo i wywietl komunikat bdu: (instrukcja wywietlajca komunikat bdu ) 
 }

 
Przykad zastosowania kmponentu do filtrowania zawartoci artykuw [contents]. W skrypcie strony frontowej components/com_content.php przed wysaniem zawartoci do bazy danych - w Mambo 4.5.2.3 odszukaj: function saveContent (linia 1269).

Wstaw przed lub za $isNew =  $row-&gt;id &lt; 1; (line 1278)
// Filtrowanie
// Znajdz niecenzuralne slowa i zamien je ciagiem ****

require_once( 'components/com_badwords2/class.badwords2.php'  );
// n.p.  $row-&gt;title jest tekstem do przefiltrowania

// $my jest uytkownikiem Mambo - zmienna globalna
$row-&gt;title = Badword::flush($row-&gt;title, $my);
 $row-&gt;introtext = Badword::flush($row-&gt;introtext, $my);
 $row-&gt;fulltext = Badword::flush($row-&gt;fulltext, $my);
 
//  End Filtrowanie nieprzyzwoitych slow

W skrypcie zaplecza -  administrator/components/com_content/admin.content.php - w Mambo 4.5.2.3 odszukaj:
 function saveContent (linia 560).
 Wstaw przed lub za sta  $isNew = ( $row-&gt;id &lt; 1 ); (linia 572)
 //  Znajdz niecenzuralne slowa i zamien je cigiem ****

 require_once( $GLOBALS['mosConfig_absolute_path'] . '/components/com_badwords2/class.badwords2.php' );
// np. $row-&gt;title jest tekstem do przefiltrowania
// $my jest uytkownikiem Mambo - zmienna globalna
$row-&gt;title = Badword::flush($row-&gt;title, $my);
$row-&gt;introtext = Badword::flush($row-&gt;introtext, $my);
$row-&gt;fulltext = Badword::flush($row-&gt;fulltext, $my);

//   End Filtrowanie nieprzyzwoitych slow

Wynikiem bdzie przefiltrowana tre.
	 
 
 
Inny przykad zastpowania zawartoci.

// Znajd niedozwolone wyraenie i zamie je na ****
require_once( 'components/com_badwords2/class.badwords2.php' );

// np. $msg jest tekstem do filtrowania
// $my jest uytkownikiem Joomla/Mambo - zmienna globalna 
$msg = Badword::flush($msg, $my);
// jeeli $msg zawiera niedozwolone wyraenia, zostanie wyczyszczony 
 
 
Przykad filtrowania poaczony z wywietleniem komunikatu bdu.

 
// Znajd niedozwolone wyraenie i zamie je na ****
require_once( 'components/com_badwords2/class.badwords2.php' );

//  np. $msg jest tekstem do filtrowania/zastpienia
// $my jest uytkownikiem Joomla/Mambo - zmienna globalna
$expletivesExist = Badword::filter($msg, $my);
if ( $expletivesExist ) {
   $msg = Badword::flush($msg, $my);
   $msg .=  "<br /><strong>Autor uy niedopuszczalnych zwrotw. Tekst zosta ocenzurowany..</strong><br />";
}
