TFC Documentation.

BEV Home Page,/|Contact,mailto:steve.teale@britseyeview.com|Comment,,#TFC-toggler|Adia's Place,/ap/|Software,/software/


What is TFC.

Please note that the implementation described here has been superseded by a version using a jQuery plugin. The new version does the same things, with some improvements. Please get in touch if you are interested.

The Tiny Feedback Component is a simple system that will allow readers of your web page to get back to you with their ten cents worth. It is less than a bulletin board, or a newsgroup, but may be adequate for many purposes.

It supports categories and topics. That is, if you add it to a web page specifying 'category1', then users will only see topics and comments that originate from pages marked with that category. Topics are as close as TFC gets to threads - they allow grouping of comments, though you can also display comments in chronological order.

Installation Requirements.

Your web server or hosting environment will need to provide PHP4 or better, and the MySQL database, in which you, or your hosting provider has created a database for use by your site. This is quite a common combination. You will also have to add a little Javascript to your web page.
How TFC Works.

If you just wnt to use the system, you don't have to read this.

TFC keeps user comments in a single database table with columns as follows:
  • uid INT(11) NOT NULL AUTO_INCREMENT,
  • dt VARCHAR(100) NOT NULL,
  • moniker VARCHAR(20) NOT NULL,
  • topic VARCHAR(20) DEFAULT '',
  • blurb VARCHAR(2000),
  • city VARCHAR(50) DEFAULT 'N/A',
  • region VARCHAR(50) DEFAULT 'N/A',
  • country VARCHAR(50) DEFAULT 'N/A',
  • bevmonth INT(11) NOT NULL,
  • category VARCHAR(30) DEFAULT '',
  • UNIQUE uid (uid)
You will have to create this table using the PHP file createcomtab.php See 'Installation' below). It is assumed in what follows that you have a directory structure in your web site like:
  • / (something like public_html - where the home page lives)
  • /php
  • /script
All communication with the database is via PHP scripts, namely:
  • createcomtab.php
  • dbcommon.inc
  • browser.inc
  • geodata.php
  • gettopics.php
  • listcomments.php
  • purgecoms.php
  • savecomment.php
  • selall.php
It is assumed that you don't want the feedback UI stuck in your users face unless she chooses to request it. If that's not what you want you can instruct the component to be always visible. Because of this assumption, TFC does things in a lazy fashion. It won't go to the database to get existing comments or topics until the UI is revealed. This stuff is handled by the Javascript file BEV-tfc2.js.

The UI lives in a block <DIV> tag that is initially not visible. The contents of the DIV are provided for you by the TFC Javascript code. When the visibility is first toggled on, an IFRAME is populated from source http://yourdomain/php/listcomments.php. At the same time, an AJAX call is made to the database via gettopics.php to get the existing topics to populate into the topics SELECT drop-list.

the listcomments.php URL includes some query fields like:
http://yourdomain/php/listcomments.php?category=BEV&month=200911&sort=time
The sort field can be time or topic. This request searches the database for rows that belong to the specified month or the month before, in the specified category, and composes some HTML in the appropriate format. The gettopics.php script is called by some AJAX code with a similar query string (except no sort), and that returns a Javascript expression that is eval'd and used to populate a drop-list.

Whe the user submits a comment, its components are first checked to see that everything is there - a user moniker, a topic, and some comment, then that information is dispatched along with the category and month via another AJAX call to savecomment.php.

An ancillary PHP component - geodata.php, can go to www.geoplugin.net, and get information about the geographical location of your user.

That's really all there is to it. The script selall.php, invoked as:
http://yourdomain/php/selall.php?table=comments
Will give you a rough listing of what's in the database table if you need to know, and purgecoms.php will remove all comments. You can use that to clean up when you've finished testing your installation.
Installation.

First download tfc.zip, and unzip it into some convenient directory.

Using your favourite FTP client (try FileZilla if you don't have one), create directories /php and /script under your web root. Copy all the .php files and .inc files to the /php directory, and BEV_tfc3.js to the /script directory.

Now edit the file dbcommon.inc to reflect your host, database name, user, and password. It comes looking like this:
<?php
$dbhost = 'yourdomain.com';
$dbuser = 'user';
$dbpwd = 'password';
$dbdefault = 'db_name';

$MYSQL_ERRNO = '';
$MYSQL_ERROR = '';

function dbConnect()
{
	global $dbhost, $dbuser, $dbpwd, $dbdefault;
	global $MYSQL_ERRNO, $MYSQL_ERROR;

	$handle = mysql_connect($dbhost, $dbuser, $dbpwd);
	if (!$handle)
	{
		$MYSQL_ERRNO = 0;
		$MYSQL_ERROR = "Connection failed to host $dbhost";
		return 0;
	}
	else if (!mysql_select_db($dbdefault))
	{
		$MYSQL_ERRNO = mysql_errno();
		$MYSQL_ERROR = mysql_error();
		return 0;
	}
	else return $handle;
}

function sql_error()
{
	global $MYSQL_ERRNO, $MYSQL_ERROR;
	if (empty($MYSQL_ERROR))
	{
		$MYSQL_ERRNO = mysql_errno();
		$MYSQL_ERROR = mysql_error();
	}
	return "$MYSQL_ERRNO: $MYSQL_ERROR";
}
?>
Change the $db... lines at the top of the file to reflect what you've set up on the server or what was provided by your hosting company. Then upload the modified file to the /php directory.

When you've done this you should be in a position to create the comments table in the database. In your browser, enter:
http://www.yourdomain.com/php/createcomtab.php
You should get a message to the effect that the table has been created.

Now you'll need to do a little work on your web page. First, right after the closing </body> tag, include the following line
<script src="http://www.yourdomain.com/script/BEV_tfc3.js"></script>
Since you will probably want to know where the comments are coming from, you can also add a line just above that or somewhere in the <HEAD> section of your page:
<script src="http://www.yourdomain.com/php/geodata.php"></script>
That's all there is to do with script.

However, you will have to make some small additions to the actual HTML of your page. First copy the following, and paste it into your page right after the <BODY> tag:
<input type="hidden" id="britseyeview.com/TFC/V0.3:params"
   value='site: "http://www.yourdomain.com", category: "test", title: "Please feel free to comment",
   surl: "/php/savecomment.php", rurl: "/php/listcomments.php", turl: "/php/gettopics.php",
   useLocInfo: true, noToggle: false'>
Edit this setup information to reflect your domain name, the category name you want to use,, and the title. If your PHP files are somewhere other than I have sugested, edit the paths as well. Next you need to define a DIV that locates the TFC component.
<div id="britseyeview.com/TFC/V0.3:outerdiv">
</div>
The DIV goes where you want the TFC component to appear.

Finally, since TFC assumes that your reader will invoke the feedback component if she wants to use it, so you also need some link, button, or menu item in your code that will make it visible, for example:
<a href="javascript:document['britseyeview.com/TFC/V0.3'].toggleCommentDiv()">
               Show the BEV Tiny Feedback Component - TFC</a>
Where you put that is purely a matter of page design. Then update your page on the server, and click the latter item. If all has gone well, you should see the TFC, and be able to enter the first comment. The strange name - G__BEV_tfc - is the name of the Javascript object that implements TFC.

If you want TFC to be visible all the time, omit that last step, and edit the setup information so you have 'noToggle: true'.

Here's the source for a simple page that shows TFC all the time:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
 <HEAD>
  <TITLE>TFC Test</TITLE>
  <script src="http://www.yourdomain.com/php/geodata.php"></script>
 </HEAD>

 <BODY>
 <input type="hidden" id="britseyeview.com/TFC/V0.3:params"
    value= 'site: "http://www.britseyeview.com", category: "test", title: "Please feel free to comment",
	surl: "/php/savecomment.php", rurl: "/php/listcomments.php", turl: "/php/gettopics.php",
	useLocInfo: true, noToggle: true'>
 <div id="britseyeview.com/TFC/V0.3:outerdiv"></div>
  
 </BODY>
<script src="http://www.yourdomain.com/script/BEV_tfc3.js"></script>
</HTML>
What is BEV?

Brits Eye View is an Englishman's six-year personal blog about life in Arusha, Tanzania, and previously in Bangalore, Manhattan, and the Bronx. It deals with life in general, building a house, food and drink, computer programming, opinion on current affairs, 20th century history, and so on. It may give you some insight into what life is like in 'the third world', or encourage you to visit Tanzania.