	Badwords2 Text Filtering/Flushing Component
	Dodatek PHP API - Komponent dla systemów zarządzania treścią 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 podziękowania dla Jan De Graaf i Two Shoes Mambo Factory za Project Assistance and Support.
 
	Oparty na oryginalnym komponencie 'Badword Filter', który napisał Pravin Hegde, rozszerzonej wersji 'Badword Filter', któej autorem jest Wim Albers oraz sugestiach, jakie sformułował 												Robert Anthony Pitera.

   Komponent	Badwords2 Text Filtering/Flushing jest bezpłatnym 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 wyższych. W gruncie rzeczy, bo jak dodatek [mambot] działa w warstwie API, a więc wykonuje na zawartości jakąś operację, zanim zostanie ona  pokazana na stronie.


Dodatkowe, specjalne rozwiązanie przygotowano dla integracji z komponentem SimpleBoard Forum wydanym przez Two Shoes Mambo Factory, ale instrukcje integrujące mogą być włączone do innych komponentów i modułów. Integracja Badwords2 z SimpleBoard będzie dokonana w przyszłym wydaniu forum, jako część dystrybucji, ale pliki integrujące umieszczone są również w tym wydaniu Badwords2.

Badwords2 wspiera Joomla 1.x i Mambo Open Source 4.5.x oraz wyższe, ale wersja Badword Extended autorstwa Wima Albersa dostępna jest również dla wcześniejszych wersji Mambo.



Jak działa?

Podstawowe właściwości:
 - Zastępowanie gwiazdkami liter w słowach niepożądanych, definiowanych za pomocą
   panelu administracyjnego komponentu (tzn. BrzydkiWyraz wyświetlany jest  jako ***********
 - Wyszukiwanie i filtrowanie słów niepożądanych bez względu na wielkość liter.
 - Zastosowanie we wzorcach słów  niepożądanych znaku specjalnego (*) do wykrywania 
   alternatywnyh form wyrazu  (m.in.gramatycznych)
 - Zachowywanie w bazie danych oryginalnego tekstu - NIEDESTRUKCYJNY charakter, nie niszczy autentycznych wpisów.
 - Pełne zarządzanie za pomocą panelu administracyjnego Joomla!/Mambo
 - Jedna linia w API przeprowadza filtrowanie/oczyszczanie każdego komponentu Joomla/Mambo.
 - Możliwość włączania i wyłączania funkcjonalności Badwords2 filtering/flushing.
 - Tworzenie w panelu administracyjnym słownika słów niepożądanych niezależnych od stosowanego w witrynie języka.
 - Możliwość (opcja) zaawansowanego filtrowania w wyniku zastosowania wyrażeń regularnych, 
   konfigurowanych w panelu administracyjnym.
 - Opcja zezwalania użytkownikom ze specjalnymi prawami na używanie niestosownych słów.


SimpleBoard - Właściwości integracji  (*tylko* SB 1.1.0 Stable)
 - Filtrowanie niepożądanych słów we WSZYSTKICH widokach, także z RSS, PDF i poczcie elektroniczej.
 - Automatyczne rozpoznawanie administratorów oraz moderatorów i wyświetlanie w NIEPRZEFILTROWANYCH tekstów.
 - Przesyłanie do moderatora pocztą elektroniczną powiadomień z tekstem przefiltrowanym i nieprzefiltrowanym
 - Filtrowanie wyników wyszukiwania, wyświetlanie przefiltrowanych wyników wyszukiwania.
 - Uniemożliwienie użytkownikom końcowym wyszukania tekstó ze słowami niecenzuralnymi, 
   wpisanymi do słownika - rezultat wyszukiwania = 0.
 - Dołączony moduł  Last 5 Posts (Ostatnie 5 postów)z funkcją filtrowania/zastępowania

AkoComment - właściwości integracji (*tylko* AkoComment 2.0)
 - Filtrowanie niepożądanych słów w komentarzach 
 - Automatyczne rozpoznawanie edytorów, publikatorów oraz administratorów i wyświetlanie NIEPRZEFILTROWANYCH tekstów
 - Przesyłanie do administratora pocztą elektroniczną powiadomień z tekstem przefiltrowanym i nieprzefiltrowanym
 - Wsparcie dla konfiguracji wiadomości
 - Zakładka Integracja z Bw2 w Ustawieniach komponentu, umożliwiajaca włączenie bądź wyłączenie filtrowania.

AkoBook - właściwości integracji (*tylko* AkoBook 3.4.2)
 - Filtrowanie niepożądanych słów we wpisach do Księgi Gości
 - Automatyczne rozpoznawanie edytorów, publikatorów oraz administratorów i wyświetlanie NIEPRZEFILTROWANYCH tekstów
 - Przesyłanie do administratora pocztą elektroniczną powiadomień z tekstem przefiltrowanym i nieprzefiltrowanym
 - Wsparcie dla konfiguracji wiadomości
 - Zakładka Integracja z Bw2 w Ustawieniach komponentu, umożliwiajaca włączenie bądź wyłączenie filtrowania.

CommunityBuilder - właściwości integracji (*tylko* CommunityBuilder 1.0 RC1)
 - Filtrowanie niestosownych słów w zakładce forum Simpleboard - w temtach postów i nazwach użytkowników.
 - Automatyczne rozpoznawanie administratorów oraz moderatorów i wyświetlanie w NIEPRZEFILTROWANYCH tekstów.

 Mambot bot_badwords2
 - Zastępowanie liter niecenzuralnych słów w tytułach i tekstach artykułów.
 - AUTOMATYCZNE rozpoznawanie użytkowników ze specjalnymi uprawnieniami (z grupy Special) - wyświetlanie w ich widoku nieprzekształconych, oryginalnych tekstów. 
 
 
Jak zainstalować Badwords2?

Aby korzystać z właściwości komponentu Badwords2, zainstaluj komponent jedną ze standardowych procedur instalacyjnych dla Joomla!/Mambo  (z pakietu albo z katalogu na serwerze). Wykonaj następujące czynności:

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 którego przesłałeś rozpakowane pliki pakietu instalacyjnego.
3. Naciśnij przycisk Wczytaj i zainstaluj 
						 

Korzystając z integratorów Badwords2 z dodatkowymi składnikami dla Joomla/Mambo opracowywanmi przez różnych programistów, a załączonymi do pakietu dystrybucyjnego Badwords2, zapoznaj się z objaśnieniami w plikach README.TXT, włączonych do spakowanych pakietów. 
WAŻNE : przeczytaj każdą instrukcję integracji BARDZO UWAŻNIE. W każdym przypadku będziesz zastępować plik należący do oryginalnej dystrybucji plikiem z wersji Badwords2. Jeśli wprowadzałeś jakiekolwiek specjalne modyfikacje w oryginalnych skryptach, prawdopodobnie zechcesz je zachować. Stąd możesz wykonać integrację z Badwords 2 "ręcznie" przez porównanie oryginalnego skryptu ze skryptem integrującym z Badwords2. We wszystkich przypadkach nasz zmodyfikowany kod jest skomentowany. Wyszukaj w skrypcie słowo "badword", aby znaleć modyfikacje.



Jak stosować?
Badwords2 jest dodatkiem do API, pracuje w tle, nie wymaga jakiejkolwiek interwencji administratorów. Dysponujesz jednak kilkoma możliwościami dostosowania Badwords 2 do Twoich specyficznych potrzeb.

1. Słownik wyrazów niecenzuralnych: W słowniku znajdziesz dwa przykładowe nieprzyzwoite słowa ("złeslowo1" 
   i "zleslowo2" ), z których możesz skorzystać do przetestowania komponentu. 
   Możesz je, oczywiście, zmienić na dowolne inne.
   Aby dodać nowy wyraz do słownika, kliknij ikonę lub odsyłacz  'Nowy' w pasku narzędzi, następnie wpisz w polu formularza nowe słowo  i kliknij odsyłacz lub ikonę 'Zapisz'.
   Aby zmodyfikować wyraz umieszczony w słowniku, zaznacz w wykazie pole wyboru obok tego wyrazu,
   a następnie kliknij ikonę lub odsyłacz 'Edytuj' w pasku narzędzi. Możesz również po prostu kliknąć na słowo. Przejdziesz do formularza edycji. Zmień wpisany tekst, a następnie  kliknij odsyłacz lub ikonę 'Zapisz'.
   Aby usunąć wyraz ze słownika, zaznacz pole wyboru obok tego słowa w wykazie, a następnie kliknij ikonę lub odsyłacz 'Usuń' w pasku narzędzi.


Badwords2 może filtrować słowa w ich dosłownym brzmieniu. Ale łatwo i skutecznie możesz również zapobiec próbom omijania przez użytkowników reguł filtowania sztuczkami typu zastąpienie jednego  znaku przez inny, np. 'U' z 'V'. Posłuż się odpowiednim wzorcem słowa w słowniku, pamiętając o możliwości takich prób.

Wpisane w wykazie słowa są ciągami  (strumieniami znaków), możesz używać Badwords2 z dowolnym językiem. 
Dodatkowo interfejs Badwords2 zawiera wsparcie dla języka angielskiego, holenderskiego i polskiego. Jeśli jesteś zainteresowany przygotowaniem tłumaczenia dla Twojego rodzimego języka, prosimy o kontakt!  Chętnie włączymy Twój język do dystrybucji komponentu i wyrazimy Ci stosowne podziękowania!

Badwords2 wspiera używanie w słowach wzorcowych znaków specjalnych, umożliwiających wyszukiwanie niecenzuralnych wyrazów zastosowanych w różnych formach alternatywnych. Najlepiej poznać sposób zastosowania znaku specjalnego  na przykładach zamieszczonych poniżej,  pokazujących skutki zastosowania uniwersalnego znaku (*)  na początku lub końcu słowa 'pieprz'.

UWAGA:  JAKO ZNAK SPECJALNY MOŻESZ ZASTOSOWAĆ TYLKO GWIAZDKĘ! Jeśli potrzebujesz większej elastyczności, rozważ wykorzystanie wyrażeń regularnych. 

Jeśli zdefiniowane słowo = "pieprz" (dokładnie, ciąg "pieprz" jest jednym całym słowem), to rezultat filtrowania będzie następujący:

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

Jeśli zdefiniowane słowo = *pieprz (dokładnie, ciąg "*pieprz" jest jednym całym słowem  I/LUB jest poprzedzony jakimikolwiek innymi znakami, to rezultat filtrowania będzie następujący:

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



Jeśli wpisane słowo = "pieprz*"  (dokładnie, ciąg znaków "pieprz" jest całym słowem I/LUB zawiera jakieś znaki po tym ciągu), wtedy rezultat filtrowania będzie następujący:

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

Jeśli wpisane słowo = "*pieprz*"  (dokładnie, ciąg znaków "pieprz" jest całym słowem I/LUB zawiera jakieś znaki przed tym ciągiem i po tym ciągu), wtedy rezultat filtrowania będzie następujący:

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


2) Wyrażenie regularne (w skrócie: regex albo regexp) są sposobem porównywania ciągów ze znakami specjalnymi,  które zastępują większe porcje ciągu docelowego. Prawdopodobnie znasz już takie znaki specjalne, jak * [gwiazdka], która w wyrażeniu *.txt oznacza, że należy wyszukać w katalogu wszystkie pliki,  z rozszerzeniem .txt. Gwiazdka zastępuje tutaj wszystkie znaki nazwy. Ekwiwalentne wyrażenie regularne miałoby następujący kształt: .*\.txt

Zastosowanie wyrażeń regularnych nie jest wymagane, by Badwords2 wykrywał i filtrował niecenzuralne fragmenty tekstu. Jeśli nie jesteś dobrze zaznajomiony ze stosowaniem wyrażeń regularnych, ich składnią, proponujemy Ci pozostawić przykład tak, jak został umieszczony. Jeśli chcesz zapoznać się bliżej z tą problematyką,  skorzystaj z poradnika zamieszczonego TUTAJ - http://weblogtoolscollection.com/regex/regex.php, objaśniającego podstawy, przykłady stosowania,  funkcje PHP korzystające z wyrażeń regularnych.


Uproszczone zasady wyrażeń regularnych w stylu POSIX, z któego korzysta Badwords2, są następujące:

 - Znaki, które nie są znakami specjalnymi, są porównywane dosłownie. 
   Przykładowo - litera we wzorcu jest porównywana z literą w ciągu.
 - Znak specjalny ^ oznacza tylko początek ciągu, a znak $ oznacza tylko koniec ciągu.
 - Znak specjalny . [kropka] oznacza dowolny znak.
 - Znak specjalny * [gwiazdka] oznacza zero (0) lub więcej miejsc wystąpienia poprzedniego wyrażenia regularnego.
 - Znak specjalny + [plus] oznacza jedno lub więcej miejsc wystąpienia poprzedniego wyrażenia.
 - Zestaw znaków otoczony nawiasami kwadratowymi zastępuje dowolny z tych znaków, np. [ab] zastępuje zarówno a,
   jak i b. Można również podać zakres znaków w nawiasach, używając kreski: [a-c] zastępuje a, b lub c.
 - Znaki specjalne poprzedzone znakiem ukośnika \ tracą specjalne znaczenie i są porównywane dosłownie.

Aby dodać nowe wyrażenie regularne, wybierz tę opcję z menu administratora, a następne kliknij w pasku narzędzi ikonę lub odsyłacz 'Nowy' i wpisz je w polu tekstowym. Możesz redagować lub usuwać wyrażenia regularne, używając instrukcji omówionych powyżej w punkcie Słownik nieprzyzwoitych wyrażeń

3) Użytkownicy ze specjalnymi prawami:  Badwords2 pozwala Ci w łatwy sposób "upoważnić" użytkowników ze specjalnymi uprawnieniami do stosowania w swoich tekstach słów wykluczonych, umieszczonych w słowniku nieprzyzwoitych wyrażeń. Aby dodać użytkownika ze specjalnymi uprawnieniami, wybierz odpowiednią opcję z menu komponentu, a następnie kliknij w ikonę lub odsyłacz 'Nowy' i wpisz w polu formularza nazwę użytkownika Joomla!/Mambo. Podobnie jak poprzednio - możesz modyfikować lub usuwać użytkowników z uprawnieniami specjalnymi, używając instrukcji omówionych powyżej w punkcie Słownik nieprzyzwoitych wyrażeń. 
Uwaga: Nadając to uprawnienie, musisz użyć ściśle takiej nazwy użytkownika, jaka znajduje się w rejestrze użytkowników witryny w polu Nazwa użytkownika. Upewnij się, że wprowadziłeś poprawną nazwę.



4) Ustawienia: Znaczenie opcji konfiguracyjnych wskazują etykiety ekranowe i dodatkowe objaśnienia. 

	Włącz filtrowanie [Perform Filtering]  - włącza lub wyłacza filtrowanie przez Badwords2. ('Tak' - włącz filtrowanie nieprzyzwoitych słów. Ustawienie domyślne, UWAGA: 'Nie' - wyłącza filtrowanie nieprzyzwoitych słów w CAŁYM Joomla!/Mambo!, we wszystkich komponentach, w których jest zaimplementowane) 

	Zastosuj wyrażenia regularne [Apply RegExp] - włącza lub wyłacza korzystanie przez Badwords2 z wyrażeń regularnych. ( 'Nie' - nie korzystaj w filtrowaniu z wyrażeń regularnych (ustawienie domyślne), 
	'Tak'  - zastosuj wyrażenia regularne w filtrowaniu.

	Akceptuj odstępstwa użytkowników z grupy Specjal [Allow Special User Exceptions for Badwords2] - Umożliwia użytkownikom ze specjalnymi uprawnieniami stosowanie wyrazów umieszczonych w słowniku niecenzuralnych ('Tak' - użytkownicy z listy ze specjalnymi uprawnieniami mogą używać dowolnych słów i wyrażeń (ustawienie domyślne),
	'Nie' - ŻADEN użytkownik nie może stosować nieprzyzwoitych słów, włącznie z moderatorami i administratorami.)

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



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

Komponent zadziała, jeśli dokonasz odpowiednich modyfikacji w skryptach posyłających do bazy danych  
zawartość, która będzie wyświetlana w serwisie.
Możesz skorzystać z dwóch dostępnych opcji:
   1. Badword Extended Filter
   2. Badwords2 Text Filtering/Flushing
   
Badword Extended Filter: cenzor nieprzyzwoitych tekstów jest komponentem, działającycm w warstwie programowej. Filtruje teksty zawierajace nieprzyzwoite słowa i wyrażenia. Zamiast zawierającego je tekstu, wyświetla komunikat informujący, iż tekst został ocenzurowany (treść komunikatu należy zadeklarować w pliku komunikatów językowych komponentu Joomla/Mambo i użyć zmiennej lub wpisać bezpośrednio do skryptu). 


Włącz plik components/com_badwords2/class.badwords2.filter.php do pliku .php komponentu instrukcją:
  require_once( 'components/com_badwords2/class.badwords2.filter.php' );
Wywołaj: 
  Badword::Filter(text, user)
aby w rezultacie API zwróciło następujący wynik:
  1 - "true" - jeśli tekst zawiera nieprzyzwoite słowo, czyli dokona zastąpienia tekstu komunikatem
  0 - "false"- jeśli tekst nie zawiera nieprzyzwoitych słów, czyli wyświetli wprowadzony tekst


Badwords2 Text Filtering/Flushing: cenzor nieprzyzwoitych słów jest komponentem, działającycm w warstwie programowej. Filtruje nieprzyzwoite słowa i wyrażenia w tekstach generowanych przez składniki (komponenty) Joomla/Mambo. W odnalezionych słowach zastępuje niecenzuralne fragmenty gwiazdkami. 

Włącz plik components/com_badwords2/class.badwords2.filter.php do pliku .php komponentu instrukcją:
   require_once( 'components/com_badwords2/class.badwords2.filter.php' );
Wywołaj: 
   Badword::Flush(text, user)
aby w rezultacie API: zastąpiło znakiem * 
każdy znak w słowie lub wyrażeniu zawierajacym niecenzuralny tekst (w każdym znalezionym przypadku).



Przykłady zastosowania
----------------
Dodaj następujące linie w stosownych miejscach skryptu php komponentu

// Filtrowanie niecenzuralnych tekstów
require_once( 'components/com_badwords2/class.badwords2.php' );

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

if ($expletivesExist == 0)
 {
	// wykonaj polecenie: ( instrukcje - wpisz je tutaj)
 } 
else 
 {
	// filtruj wiadomość i wyświetl komunikat błędu: (instrukcja wyświetlająca komunikat błędu ) 
 }

 
Przykład zastosowania kmponentu do filtrowania zawartości artykułów [contents]. W skrypcie strony frontowej components/com_content.php przed wysłaniem zawartości 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 użytkownikiem 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 ciągiem ****

 require_once( $GLOBALS['mosConfig_absolute_path'] . '/components/com_badwords2/class.badwords2.php' );
// np. $row-&gt;title jest tekstem do przefiltrowania
// $my jest użytkownikiem 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 będzie przefiltrowana treść.
	 
 
 
Inny przykład zastępowania zawartości.

// Znajdź niedozwolone wyrażenie i zamień je na ****
require_once( 'components/com_badwords2/class.badwords2.php' );

// np. $msg jest tekstem do filtrowania
// $my jest użytkownikiem Joomla/Mambo - zmienna globalna 
$msg = Badword::flush($msg, $my);
// jeżeli $msg zawiera niedozwolone wyrażenia, zostanie wyczyszczony 
 
 
Przykład filtrowania połaczony z wyświetleniem komunikatu błędu.

 
// Znajdź niedozwolone wyrażenie i zamień je na ****
require_once( 'components/com_badwords2/class.badwords2.php' );

//  np. $msg jest tekstem do filtrowania/zastąpienia
// $my jest użytkownikiem Joomla/Mambo - zmienna globalna
$expletivesExist = Badword::filter($msg, $my);
if ( $expletivesExist ) {
   $msg = Badword::flush($msg, $my);
   $msg .=  "<br /><strong>Autor użył niedopuszczalnych zwrotów. Tekst został ocenzurowany..</strong><br />";
}
