phpforumPlus: Rapid discussion forums creation

*************************************************
	           README FILE
*************************************************
Class: phpforumPlus
Author: Tsiavos Chris <jaames@freemail.gr>
*************************************************
Table of Contents
0. Preface
1. Preparations
    1.1 Creating the database tables
2. Tuning the class variables
    2.1 Database Options
    2.2 Icon Options
    2.3 CSS StyleSheet Options
    2.4 Other Options
3. Final Steps
    3.1 Creating the forum scripts
    3.2 Testing your configuration 
*************************************************

0. PREFACE

What you must already have

You must already have a database server configured properly with a high preference
in MySQL & PostgreSQL as being the database platforms this class has been tested on.
Also you must have the DB.php installed in your computer."DB.php" is the PEAR
class for database access.If you don't have this package installed point your browser at
http://pear.php.net/package/DB/ for download instructions & usage.

What this class is

This class provides the basic functionality needed to create a forum board. Basic
functionality encompasses features such as displaying threads for different forum topics,allowing
users to post new threads or reply to existing ones,searching threads by headline or member,allowing
limited number of html tags in threads' bodies and customizing the tables' layout by choosing from a
variety of predefined CSS Stylesheets.It will be a time saver for anyone interested in creating
community boards in a simple and efficient manner.

What this class isn't

This class isn't a forum system with database and user management options,advanced layout customization
and internationalization support.It's impossible to include all these features in a single class.Besides
there are already mature projects in this area with a large user base.

*********************************************************************************************************

1. PREPARATIONS
   1.1 Creating the database tables

Suppose that we want to create a forum in MySQL about general php discussion. The first step is to create
the database and the database tables.
This class expects two tables for each forum topic we create. One table is used for posts and the other one for replies
to selected posts. For the purpose of this tutorial we will create a database named forums and two tables, phpposts and
phpreplies.Therefore we have:

CREATE DATABASE forums;USE forums;

CREATE TABLE phpposts (id INTEGER UNSIGNED AUTO_INCREMENT,member VARCHAR(20),headline VARCHAR(15),body TEXT,
date_posted DAYTIME,views INTEGER, PRIMARY KEY(id))Type=MyISAM;

CREATE TABLE phpreplies(id INTEGER,member VARCHAR(20),headline VARCHAR(15),body TEXT,date_posted DAYTIME)Type=MyISAM;

Let's explain the columns & their meaning:

id: holds the thread's id
member:defines the registered member who posted the thread to the forum
headline:defines the headline of the selected thread
body:the body of the current thread
date_posted:info about posting date & time
views: how many people have read this thread

*********************************************************************************************************

2. TUNING THE CLASS VARIABLES
   2.1 DATABASE OPTIONS

The next step is to make the class aware of the database tables & columns we' ve just created. In
"myphpforum.php" script there is a section named "Database Options".Seven variables need to be configured

       var $database_type: Defines the type of the database currently used.In our case the database is mysql.

       var $database_type="mysql";

       var $db_host: The name of the database server hosting the forums.If the database server is located
       on the same machine as your php scripts enter the name of the machine.

       var $db_user: Defines the user of the database. A special user such as "webuser" with limited privilleges
       is a good idea.

       var $db_passwd: Defines the password of the database user.

       var $forum_database: Defines the name of the database holding our forum topics. In our case we' ve created
       the database "forums".

       var $forum_database="forums";

       var $topic_tables:This variable contains the topic name, a short description for the topic and the
       database tables related to this topic. In our case the topic is "General PHP" and the database tables
       related to PHP are phpposts & phpreplies. Therefore we define:

       var $topic_tables=array ("PHP"=>array("phpposts","phpreplies","This is a general php forum.Your one-stop
       resource for all things php"));

       var $table_struct: This variable defines the columns' names of our database tables, phpposts & phpreplies.
       Therefore we have:

       var $table_struct=array ("table_posts"=>array("id","member","headline","body","date_posted","views"),
                                "table_replies"=>array("id","member","headline","body","date_posted"));

       var $threads_limit_per_page: Used to specify the number of threads per page.Below we set the
       value to be 42,meaning 42 threads per page.

       var $threads_limit_per_page=42;

       var $thread_length_limit:Used to limit the length(in characters) of forum threads.Default 2000 characters.

       var $thread_length_limit=2000;

       var $headline_length_limit:Same as above but for the headline of the thread.Default 20 characters.

       var $headline_length_limit=20;

********************************************************************************************************
2. TUNING THE CLASS VARIABLES
   2.2 ICON OPTIONS

This section is used to specify icons utilized in different parts of the forum.

       var $forum_icon:This variable is used to specify an icon for the selected forum. For instance if
       we have a PHP & a Perl forum and want to specify a diverse icon for each we enter the following data.

       var $forum_icon=array ("PHP"=>"./phpicon.gif", "Perl"=>"./perlicon.gif");

       var $thread_icon: This variable defines the thread's icon such as an envelop etc.

       NOTE: The icon path must be related to the location of your "displayforum.php" & "forums.php"
       scripts(see below)

       var $thread_icon="./envelop.gif";

       var $hot_thread_icon: Used to specify the icon for a thread which is marked as hot(with many replies).

       var $hot_thread_icon="./hot.gif";

       var $hot_thread_limit: Defines the replies limit after which a thread is market as hot. For instance if
       we want threads with over 20 replies to have a different icon (var $hot_thread_icon) we type:

       var $hot_thread_limit=20;

********************************************************************************************************
2. TUNING THE CLASS VARIABLES
   2.2 CSS STYLESHEET OPTIONS

This section is used to specify the CSS stylesheet name affecting the page layout.

      var $style_type: Defines the name of the applied CSS Stylesheet.For more information regarding methods for 
      custom stylesheets application & changing HTML elements' attributes read the style.php script.
      In the below example the stylesheet named ocean is utilized.

      var $style_type="ocean";

********************************************************************************************************
2. TUNING THE CLASS VARIABLES
   2.2 OTHER OPTIONS

This section briefly describes enviroment,page and site options

Site Options

     var $welcome_msg: Used to specify a welcome message for the forums. Default value "Welcome to our community"

     var $welcome_msg="Welcome to our community";

     var $site_administrator:Defines the email address of the site administrator displayed in error messages.

 
Page Options

     var $display_forum: Defines the name of the page which will be used to display the forum threads. Default
     value displayforum.php

     var $display_forum="displayforum.php";

     var $view_thread_page: The name of the page used to display the selected thread and the relevant
     replies.Default value showmessage.php.

     var $view_thread_page="showmessage.php";

     var $reply_page: The name of the page for posting replies to selected threads. Default value reply.php

     var $reply_page="reply.php";

     var $post_new_thread_page: The name of the page for posting new threads. Default value post.php

     var $post_new_thread_page="post.php";

     var $search_page: The name of the page used to search the forum threads by headline and member name
	
     var $search_page="search.php"; 

 
Environment Options

     var $member: Usually in forum sites only registered members can post or reply to threads.This variable
     defines the name of the registered member. You will often use this variable along with something like this:

     session_register("mymember","chris");
     $this->member=$_SESSION["mymember"];

********************************************************************************************************
3. FINAL STEPS
   3.1 CREATING THE FORUM SCRIPTS

The next step in the configuration process is to create the php scripts that will utilize the class.
Six scripts need to be created.

CREATING THE forums.php SCRIPT

The first script named forums.php is used to show the available forum topics with a short description for each.Therefore we have:

***********forums.php**************
<?php
include("./myphpforum.php");
$myforum=new myphpforum( );
$myforum->display_forums( );
?>
***********end-forums.php*********

CREATING THE displayforum.php SCRIPT

The second script we are going to create is used to show the threads for the selected forum. You can give
any name you want to the script but do note that this name must then be declared in the var $display_forum
variable of the myphpforum.php script.For demostration purposes the "displayforum.php" name is given to the
script.

********displayforum.php**********
<?php
include("./myphpforum.php");
$myforum=new myphpforum();
$myforum->display();
?>
********end displayforum.php*****

And in myphpforum.php script we configure the $display_forum class variable with the name of the above script.

var $display_forum="displayforum.php";

CREATING THE sowmessage.php SCRIPT

The third script is used to display the selected thread and all replies related to this thread. The name of the script
can be again based on your personal preferences and therefore can be set to anything you want. For the purpose of
this tutorial the "showmessage.php" name is selected.

*******showmessage.php********
<?php
include("./myphpforum.php");
$myforum=new myphpforum();
$myforum->display_thread();
?>
****end showmessage.php******

And in myphpforum.php script we configure the $display_forum class variable with the name of the above script.

var $view_thread_page="showmessage.php"

CREATING THE post.php SCRIPT

The forth script is used to provide the functionality needed for posting new threads to a selected forum topic.Therefore we have:

*************post.php************
<?php
include("./myphpforum.php");
$myforum=new myphpforum();
$myforum->post_new_thread();
?>
**********end post.php**********

And in myphpforum.php script the appropriate declaration

var $post_new_thread_page="post.php";

CREATING THE reply.php SCRIPT

The last script provides the functionality needed for replying to selected threads.

*************reply.php************
<?php
include("./myphpforum.php");
$myforum=new myphpforum();
$myforum->reply_to_thread();
?>
**********end reply.php**********

And the appropriate declaration in "myphpforum.php"

var $reply_page="reply.php";

CREATING THE reply.php SCRIPT

The last script provides the functionality needed for searching threads based on headline and member values.

*************search.php************
<?php
include("./myphpforum.php");
$myforum=new myphpforum();
$myforum->search();
?>
**********end search.php**********

And the appropriate declaration in "myphpforum.php"

var $search_page="search.php";

********************************************************************************************************
3. FINAL STEPS
   3.2 TESTING YOUR CONFIGURATION

Point your browser at http://yourhost.yourdomain/forums.php. Your forum should be up & running. Don't forget
that if you want to add a new forum or change any of the configuration options you should refer to myphpforum.php
script and change the configuration variables as described in this tutorial.

Note: If the first time you point your browser at forums.php script you receive an error such as "DB:Error Connect failed"
it means that either your database server is not running or you have the database server provided with
the wrong credentials.
********************************************************************************************************