Setting up the forum
--------------------

By Nick Gammon <nick@gammon.com.au>

Home page: http://www.gammon.com.au/

Date: 10th January 2003

This document is best viewed in a monospaced font (eg. Courier, FixedSys).


Introduction
------------

This is the preliminary documentation for my "discussion forum" code written on PHP (v4) to be used in conjunction with mySQL database.


Installation
------------

See the document INSTALL.


Copyright
---------

The forum software is released under the GNU General Public License. 

You can see a copy of that at: http://www.fsf.org/copyleft/gpl.html 

It is also supplied in the file: docs/gpl.txt

In essence, this means you can copy the software without paying for it. There are some restrictions imposed by the licence, you should read it for more details. 


Table editor
------------

When reference is made to the "table editor" or changing fields "manually" this refers to using the "edittable.php" web page that lets you make arbitrary changes to any table in a mySQL database.

Such changes are intended for "low volume" changes, such as:

* Creating new sections
* Tweaking fields like date posted
* Moving posts from one topic to another or similar activities

Structure
---------

The forum is organised into sections, topics, subjects and posts. These are represented by the SQL tables bbsection, bbtopic, bbsubject and bbpost respectively.

This is intended for a layout like this:

Major section (eg. product A)
  |
  |
  -- Topic (eg. Sales, Support, FAQ)
     |
     |
     -- Subject (eg. How do I turn on the power?)
        |
        |
        -- Post (eg. one message about the subject)

Sections are entered manually, using the table editor, as normally the rate of change there will be small.

Users can start their own subjects, or reply to existing ones. Administrators can create new topics.


Users
-----

Anyone can read any post, however to make posts (or replies) you must register. When registering a password is emailed to you, which confirms that you have supplied a valid email address, that you have access to.

If you change email addresses, this process is repeated.

User names and email addresses may not be duplicated (ie. no two John Smiths)


Control
-------

There is a 'control' table which lets the administrator customise things like the standard page header and footer, signature at the bottom of the generated email addresses, and return address.

You can also turn on or off the ability to make posts, delete posts etc., as an emergency measure in case someone is spamming the forum.

Administrator
-------------

Anyone can have their administrator flag turned on, which allows them to:

* post to any topic, including closed, or "administrator only" ones
* edit any post
* delete any post
* edit any user's profile (eg. to remove profanity from bio or signature)

This is intended so that administrators can edit or delete offensive messages.

Note - the administrator flag should only be used for trusted people. Anyone with the administrator flag set can set or remove the administrator flag for other users, and generally cause trouble.


Moderators
----------

The administrator can set a "moderator topic" or "moderator section" for a user, which means they are the moderator for that topic, or section. When posting to that topic/section they have administrator privileges, but not to other topics/sections. 

At present a user can only moderate one topic at a time (plus one section).

Moderators do not have administrator privileges over users (ie. they cannot edit other users' profiles).


Users
-----

Users can self-register. A password is emailed to them. They can choose whether or not to disclose their email address, or other personal details.

Users can post or reply to any forum that is:

* not closed
* not an administrator-only topic

Users can edit or delete messages they have themselves posted.
  
Users can send mail, via the forum, to each other without necessarily disclosing their email addresses.


Forum code
----------

To allow some formatting, users can use "forum codes" (eg. [b] for bold) to format their messages.


Nuisance posters
----------------

By adding an entry to the "bbbanned" table you can ban either an email address, or a whole domain, from registering as a user. You could then set the "blocked" field for that user so they can't log on.

eg.  twink@somedomain.com  <-- bans this particular email address
     hotmail.com	<-- bans anyone from hotmail.com

Note - you should not *delete* users who have made a posting, because then you create a "dangling" post that has no associated user. Once all related posts are deleted, then it is safe to delete the user. In some ways it is simpler to leave them on file as "blocked" because then they:

a) can't log on
b) can't re-register because the name and email address is already taken


Countries
---------

To simplify country name entry, and stop people inventing stupid countries, all country names are in the "country" table, which you can add to or edit as required.


Notification
------------

Administrators can set any user to have notification for:

* any new message
* any amended message
* any deleted message
* any new user
* any amended user

This is so that an administrator can check for offensive posts (or user names) shortly after they are made.

You can choose any combination of the above (eg. new message but not amended message)


User notification
-----------------

Any user can choose to be notified by email of any new posting to either:

* a particular subject (these are stored in table bbnotify_subject)
* a particular topic   (these are stored in table bbnotify_topic)

Users can view their current subscriptions by looking at their own profiles.



