	Badwords2 Text Filtering/Flushing Component
	Add-on PHP API Component for Joomla 1.x and Mambo Open Source 4.5.x dynamic portal server and content management engine
	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)
 
	Special thanks to Jan De Graaf and Two Shoes Mambo Factory for Project Assistance and Support.
 
	Based on the original 'Badword Filter' component developed by Pravin Hegde, the Extended version of 'Badword Filter' by Wim Albers and suggestions by 												Robert Anthony Pitera.

     	Badwords2 Text Filtering/Flushing Component is Free Software
	Released under GNU/GPL License : http://www.gnu.org/copyleft/gpl.html
     	Version 1.0 beta

     

What is it?

The Badwords2 Text Filtering/Flushing Component is an add-on API component for Joomla 1.x and Mambo Open Source 4.5.x, GNU GPL portal CMS.  It is designed as custom component and fully integrated in Mambo. 

In addition, special consideration has been made for integrating it into the SimpleBoard Forums Component by Two Shoes Mambo Factory, though instructions are included for integration in other components and modules.  Badwords2 integration will be included in future SimpleBoard releases as part of the base package, but integration files are included with this release.

Badwords2 supports Joomla 1.x and Mambo Open Source 4.5.x and higher, however a Badword Extended version developed by Wim Albers available for older versions of Mambo.



What does it do?

Basic Features
 - Replaces words listed in the admin configurable badwords list with asterisks, (i.e. "badword1" becomes "********" in views
 - Case insensitive and finds badwords within strings for thorough filtering/flushing
 - Supports the use of a 'wild card' character (*) in the badwords entries for alternative word form detection
 - Completely NON DESTRUCTIVE; original text remains unchanged in the database
 - Complete administration through Mambo Admin Panel
 - One line of API call to perform badword filtering/flushing for any of your Mambo components
 - Ability to turn Badwords2 filtering/flushing on/off at will
 - Configuration of the language independent badwords list through the admin panel
 - Options to configure regular expressions for advanced filtering/flushing through the admin panel
 - Options to allow special access to users by username through the admin panel


SimpleBoard integration features (SB 1.1.0 Stable *only*)
 - Flushes badwords in ALL views, including RSS and PDF and emails
 - Automatically detects admins and moderators and shows UNFILTERED views
 - Moderator emails show both filtered and unfiltered views
 - Option to filter searches and either show filtered results or deny searching for badwords. Allows for configurable end user denied search message or simply shows 0 result.
 - Includes custom "Last 5 Posts" module with filtering/flushing

AkoComment integration features (AkoComment 2.0 *only*)
 - Flushes badwords in Commentary entries 
 - Automatically detects editors, publishers, etc. and shows UNFILTERED views
 - Configurable message support
 - BW2 Integration Tab on AkoComment config to turn filtering on or off

AkoBook integration features (AkoBook 3.4.2 *only*)
 - Flushes badwords in GuestBook entries
 - Automatically detects editors, publishers, etc. and shows UNFILTERED views
 - Responder emails show filtered views
 - Configurable message support
 - BW2 Integration Tab on AkoBook config to turn filtering on or off

CommunityBuilder integration features (CommunityBuilder 1.0 RC1 *only*)
 - Flushes badwords in SimpleBoard forum view tab for subject and username 
 - Automatically detects admins and moderators and shows UNFILTERED views

 Mambot bot_badwords2
 - Flushes badwords in Mambo content title and text before display.
 - Automatically detects editors, publishers, managers, etc. and users defined in Badwords2 and shows UNFILTERED views

How do I install it?
To get the basic features of Badwords2 operating, follow the standard component install procedure; and upload the zip package through the Mambo Component installation section in the admin portal.

1) Browse to the location of the zip package through Mambo component installer.
2) Choose upload and install

To get the Third Party integrations working, follow the instructions in the README.TXT file in the appropriate integration zip file.  IMPORTANT:  Read each integration instruction file VERY CAREFULLY!  In each case, you will be replacing an original distribution file with a Badwords2 version - if you have made any special modifications, you may wish to do the integration MANUALLY by comparing the differences.  In all cases, our modified code is commented so just search for the word "badword" to find the modifications.



How do I use it?
Actually, 'using' it is quite transparent; Badwords2 works in the background when it is enabled without any admin intervention but there are a few things to setup in the configuration to customize it for your specific needs.

1) Badwords list: Two sample words ("badword1" and "badword2") are already in the list for testing purposes.  It is advised that you attempt to make a post using these words to determine if Badwords2 is functional before adding words to the list.  To add a word, simply choose 'New' from the options and enter the word in the blank provided.  You can edit an existing word by clicking directly on it or checking the box next to the word and choosing "Edit".  To delete a word from the list, check the box next to the word or words you wish to delete and choose the "Delete" option above.

Give some thought to your word choices and forms here; Badwords2 can find words no matter the case or within a string, but it is easier (and more accurate) to use multiple forms of a offending word.  Also some 'creative' users may substitute a letter with one that looks similar in an effort to bypass censoring, replacing a "U" with a "V" for example, so you may want to consider this when making your list up.

The badword entry is just a string to Badwords2 so you can use it with any language.  In addition, the interface supports English and Dutch language options; If you are interested in doing a translation into your native language, please contact us!  We'd love to include your language and we'll credit you appropriately!  

Badwords2 supports the use of wildcards in the badwords field entry for alternative word form detection; this can be a very powerful way of flushing various forms of a word with a single entry.  The easiest way to see this in action is with the examples below, which show the effects of using a badword and the wild card character "*" in either the beginning or end of our badword "funk" and the results of flushing compared to the original.  

NOTE: ONLY THE ASTERISK WILDCARD IS SUPPORTED!!! If you need more specific flexibility, then consider using the regular expressions feature.


If the badword entry = "funk" (Literally, the string "funk" all by itself), then the flushing results would be as folllows;
funk			=	****
Funky		=	Funky
Motherfunker	=	Motherfunker
motherfunk	=	motherfunk
funkster		=	funkster
funk you 		=	**** you 



If the badword entry = "*funk" (Literally, the string "funk" all by itself AND/OR with characters PRECEDING it), then the flushing results would be as folllows;
funk			=	****
Funky		=	Funky
Motherfunker	=	Motherfunker
motherfunk	=	mother****
funkster		=	funkster
funk you 		=	**** you 



If the badword entry = "funk*" (Literally, the string "funk" all by itself AND/OR with characters AFTER it), then the flushing results would be as folllows;
funk			=	****
Funky		=	****y
Motherfunker	=	Motherfunker
motherfunk	=	motherfunk
funkster		=	****ster
funk you 		=	**** you 



If the badword entry = "*funk*" (Literally, the string "funk" all by itself AND/OR with characters PRECEDING AND/OR AFTER it), then the flushing results would be as folllows;
funk			=	****
Funky		=	****y
Motherfunker	=	Mother****er
motherfunk	=	mother****
funkster		=	****ster
funk you 		=	**** you


2) Regular expressions:  A regular expression (regex or regexp for short) is a special text string for describing a search pattern. You can think of regular expressions as wildcards on steroids. You are probably familiar with wildcard notations such as *.txt to find all text files in a file manager. The regex equivalent would be .*\.txt

While not required for operation, regular expressions can be used to fine tune Badwords2 detection.  If you are not familiar with the use of regular expression and their syntax, we'd advise you to leave the sample entry as it is.  You can find a great Regular Expressions reference at http://weblogtoolscollection.com/regex/regex.php and it explains the basics and includes additonal help and references.

To add a new regular expression, simply choose "New" from the options and put the expression in the blank provided.  You can edit or delete a regular expression using the same instructions as the badwords listing.

3) Special User Access:  Badwords2 provides a facility to allow specific users to post and see words in the badwords list.  Note that you will need to use the *EXACT* username as it appears in the Mambo registered user list and it is advisable to test to make sure that the username matches. Add a new user by choosing "New" from the options above the list and put the MAMBO USER NAME in the blank provided.  Again, You can edit or delete a special user using the same instructions as the badwords listing.

4) Settings:  Settings are pretty self explanatory, but let's go over them anyway...

	Perform Filtering  - Turn on Badwords2 filtering. ("Yes" turned on by default, NOTE: "No" turns off ALL filtering throughout Mambo!!) 

	Apply RegExp - Turn on Badwords2 filtering using regular expressions. ("No" turned on by default,  Yes - Turn on Badwords2 filtering using regular expressions) 

	Allow Special User Exceptions for Badwords2 - Allows specified users in the Special Users List to use listed badwords ("Yes" turned on by default,  
	No - Do not allow any listed badwords by ANY user)  

5) About Badwords 2:  Shows the version number, credits/contact/support info and this README.TXT file



How can I add Badwords2 Flushing/filtering to "Application XYZ"?

The Badword Extended Filter is an API component which provides an API for badword filtering that can be invoked through any of your Mambo components

1) Include the components/com_badword/class.badword.filter.php in your php files
2) Invoke the Badword::Filter(text, user) API which returns 
 1 - if the text includes a bad word
 0 - if the text passes the badword test
 
The Badwords2 Text Filtering/Flushing Component is an API component which provides an API for badword filtering that can be invoked through any of your Mambo components

1) Include the components/com_badwords2/class.badwords2.filter.php in your php files
2) Invoke the Badword::Flush(text, user) API which returns
A moderated string with a string of "*" replacing the badwords (case insensitive) found.

Sample usage
----------------
Include the following lines at appropriate places in your php file

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

// $msg is the text to be filtered
// $my is Mambo user variable available as a global
$expletivesExist = Badword::filter($msg, $my); 

if ($expletivesExist == 0)
 {
	// do something
 } 
else 
 {
	// throw error 
 }

An example of content flushing.

// Search for bad words and replace by ****
require_once( 'components/com_badwords2/class.badwords2.php' );

// e.g. $msg is the text to be flushed
// $my is Mambo user variable available as a global
$msg = Badword::flush($msg, $my);
// if $msg contained bad words it will be flushed

An example of content filtering and flushing combined to add some notification.

// Search for bad words and replace by ****
require_once( 'components/com_badwords2/class.badwords2.php' );

// e.g. $msg is the text to be filtered/flushed
// $my is Mambo user variable available as a global
$expletivesExist = Badword::filter($msg, $my);
if ( $expletivesExist ) {
   $msg = Badword::flush($msg, $my);
   $msg .=  "<br /><strong>This message contains badwords</strong><br />";
}
