THCNET Version 1.1.0.4 Documentation
THCNET is a customizable PHP-enabled Web application which provides a moderated message system using a backend MySQL database.
You can see the THCNET message system in use at these sites:
and the current development version:
http://devel.thcnet.net/thcnetdev/
Disclaimer
This is software in progress. There may be bugs, but *probably* none that will fdisk your hard drive.
This software is licensed under the CC-GNU GPL
http://creativecommons.org/licenses/GPL/2.0/
Installing
download and install MySQL. download and install apache with mod_rewrite and PHP4 or PHP5 compiled with the pspell libraries. Note: older aspell libraries cause problems, but it has been tested to work with aspell >= 0.60.
note: I use MySQL 5.0 and PHP 5.1 in development of THCNET, but it should work with earlier versions.
As of release 1.0.0.5 THCNET has an auto-installer/revision control feature that makes the initial setup much easier.
Setup THCNET by performing the following steps:
- Copy all the files into your htdocs directory on your web server. THCNET can run in a sub directory or at the document root.
- Open index.php in your browser. It will prompt you for values it needs to perform the installation. Click on setup and it will create the database for you and populate it.
- Now that you have the initial setup complete, the first task will be to apply as a new user. The first user to apply will be given admin rights.
- Once you have setup the admin user, you can customize features by clicking on the Admin link to the left.
- Modify the *.template *.css files in the standard template set located in themes/standard to customize the look of THCNET.
Upgrading
Database upgrades happen automatically, however there may be some new features that may need modification to the template files or some other change to take advantage of. See the UPGRADING Upgrading text file for details.
Customizing
THCNET uses a template / macro based system for the formatting of it's output. By editing the template files you can change the look and feel of THCNET however you like without the need for modification of the PHP source code.
As of version 1.0.0.9 I've implemented a new macro processing system that standardizes the names of the macros, allows any macros to be used in any template, provides context based output so the macro %%user%% displays the current user name, the name of the person who wrote the article being viewed, or the name of the user record being viewed, all defendant on where it's used. This simplifies things greatly as well as reduces the amount of code needed to be written to handle template processing. New with 1.0.0.10 are the ability to include external PHP scripts, or even include THCNET in a script.
See the file macro.txt MacroSystem for a list of all the macros and their uses, as well as optional switches to limit display of macros based on users access level, etc..
Plugin external scripts. With macros you can call external scripts and have their output incorporated within your page. To convert a script for use with THCNET, simply modify it so that output is buffered into the variable $output instead of using print or echo statements.
Template Definition
The standard template is defined for you in the Template Definition section of the system config. You are not allowed to delete or rename the default template, as THCNET must always have a known working template as a safeguard. Note, that "known working" just means that a template set is defined. If the template files themselves are bad, it can't help you. Be sure to backup your template files when making any changes, so you always have a way to reverse any mistakes.
It's suggested that you put your template sets in their own directory, though you are not forced to do this. The path defined is relative to the current working directory where THCNET is installed.
Policies
One of the unique features of THCNET is the ability to define and set policies. A policy is a way of evaluating a complex set of conditions, and set variables accordingly.
An example of a policy is to set a template if a certain browser type is detected. You can go a step further and only set the template if a user is trying to use a particular template, and a browser was detected, such as if they were trying to use a template that was known not to display correctly in Internet Explorer, you could set the template to an IE friendly version.
Of course you are not limited to browser detection. In fact you can check and set any number of variables, in sets of rules with multiple match and set statements. Because of this, policies can be quite powerful, but if used incorrectly, can be rather dangerous. Policies don't limit you from doing something like setting everyone's access level to 255 or 0.
You have the ability to set the system_policy_map configuration variable which is applied just before the template determination takes place. Because all other policies you apply take place after this step, if you want to define a policy to change the template set to be displayed, you need to define that here. Also since setting the system_policy_map can potentially be system disabling, in the event of a poorly written policy, you can override this if you have sysop level access. Just append ?policy=disable or &policy=disable to the URL.
See the policies.txt file for a detailed explanation of how to define and use policies.
URL Masking
As of version 1.0.0.21, you now have the ability to mask thread URLs in a number of fashions with apache mod_rewrite, and some new configuration within THCNET.
Assuming your web server is configured to support mod_rewrite, you can take full advantage of this feature.
First you need to create your rewrite rules under the virtual host entry for your web site. A simple configuration would look like the following in the httpd.conf/ssl.conf files:
RewriteEngine On
RewriteRule ^/thcnet/article/([0-9a-zA-Z\-\._,]+)$ http://yourwebsite.com/thcnet/index.php?section=article,$1
This would assume you installed THCNET into the /thcnet directory off your site's http root.
When working with URL masking like this it is important that any images or other files you might reference give the full URL from your site's http root folder. By default THCNET references directories relatively, or from the current folder. Since with the rewrite rule you make it look like the page is in a sub-folder, your files won't be where the web browser expects when it makes subsequent requests. You could add a rewrite rule for the images folder, or modify your template and css files to point to the correct path.
Once you have updated your rewrite rules, restart Apache for them to take effect.
Next step, you have to configure some options within THCNET.
There is a new configuration block labeled Access, which is where all the options you'll need to adjust for this are located.
base_url
By default THCNET is able to determine what it's URL is based on the PHP Server Self parameter. However, when you modify the URL with mod_rewrite this variable will be set to, using the above configuration as an example, "/thcnet/article/", which won't work since there is no actual folder called article.
You can configure base_url to be the fully qualified URL, or just include the directory and PHP file information, such as /thcnet/index.php which gives you the advantage of serving up the page on multiple domain names, ports, or encryption settings.
text_thread_links
The option will display the text title in URL links to threads instead of the article ID number of the first message in the thread. You can actually use this feature even if you don't choose to implement mod_rewrite, and it is enabled by default. Setting this to 1 uses the thread title for the URL, and 0 uses the article ID number.
thread_url
Currently thread URLs, i.e the URLs beginning with "?section=article," are the only URLs which are maskable. Here you would enter what mod_rewrite is going to translate. Again using the above example enter in:
/thcnet/article/
Save your configuration, and you should notice that the thread URLs will now look like:
http://yourwebsite.com/thcnet/article/article_tile_about_something
Notes
By default, THCNET is a moderated message system. for messages to appear on the main page you are required to validate any unmoderated posts. Once moderated users can read and reply to the post. Replies to messages are not moderated. You can change security access levels to allow users to have the ability to post without moderation, just certain users, etc.. It's designed to be flexible.
Security is done with an access level system. Each user is assigned an security level from 0 to 255. The default user is set at 0, and the system admin is set to 255.
Under the security section on the Admin page you can set the values for System Administrator, Administrator, and Moderator.
Additionally you can tailor security levels on individual message boards. These values are read, post, moderated (auto validation of posts when starting a new thread) and moderator. The system comes with the defaults of Main, Calendar, and Private.
Calendar is reserved for a future modification to allow you to edit the events listing on the side. As of this release the events is just a calendar.html include file.
Default levels for main allow all users to read. All users can post, but their message will be marked as unmoderated, until a user with the level of moderator validates the message. Users posts with a security level of 150 or above are auto-moderated.
Default levels for private only allow users with a security level of 150 or higher to read and posts messages, and moderation is effectively turned off since it's at the same level as the read and post access.
Last words
If you use THCNET somewhere, like what I've done, or have any suggestions, updates or bug reports, send me an email.
krux@…
