Screenshots of bttlxeForum in use

Introduction
Installation
Usage
- End User Walkthrough
- Administrator Walkthrough
Development
- Organisation
- Where To Look
Known Issues
License
Credits
History

Introduction

bttlxeForum 2.0 is free software for providing extensive online forums to web users. The software can be easily configured to suit uses ranging from product support web sites to bustling web communities, and has been designed in such a way to allow its functionality to be used even with heavy customisation.

The latest version of bttlxeForum can be seen in action at http://forums.bttlxe.com/.

Overview

This article attempts to show not only how to get bttlxeForum running for you but also to explain how the software works and can be developed for. It is hoped that readers will feel confident enough after reading to dig into the source code and start working with the software rather than simply using it.

The software is written using Active Server Pages and JScript and so targets the Microsoft Windows server platform. It may be possible to use it successfully on another platform with the aid of an ASP emulator but such usage is not supported. bttlxeForum makes extensive use of CSS1 and modular page components to make it simple and logical for an experienced web developer to fully customise the appearance of the forums.

Considerations

No assumptions of familiarity with bttlxeForum are made, but the reader should be confident with the way Internet software and web sites work, and general web development terms and techniques. An understanding of online forum software would be advantageous but is not critical.

It is not recommended that you upgrade previous versions of bttlxeForum to 2.0. Future upgrades will be handled by the software.

Features

bttlxeForum 2.0 has many unique features and lots of enhancements over previous versions:

General

Software-based installer that can download the latest version and configures the scripts for uploading to your web server.
Support for installation in multiple languages
Templates/Themes can be applied with one click to totally define the visual appearance of the forums. Custom templates are easy to create to slot the forums into your existing web site design.
Confirmed to work flawlessly in the latest versions of Internet Explorer, Mozilla, the Mozilla Firebird project and Opera (dynamic views behave as normal views in all but Internet Explorer 4.0 or later)
Can currently use SQL Server 2000 or Microsoft Access to store its data
Unlimited number of members, forums, groups and messages
Full classic ASP/Jscript source code provided

Forums

Active User list listing who's currently in the forums
User definable forum views, ranging from the more traditional threaded views to the tree based views as used here on CodeProject
Polls can be inserted with new threads
Can be made private (only visible/accessible to members of a certain group)
Collapsible forum categories
Authors can choose to be notified by e-mail when they receive replies
Forum Code (similar to safety-restricted HTML mark-up) can be used to enhance messages
Toolbars for emoticons and common Forum Codes are shown when posting a message using a supported Internet browser
Can be searched for keywords by forums, by user or by category
Allows moderation rights to authorised members
Protection against message flooding
Entire threads or individual messages can be deleted or locked by moderators
Bad word censor

Groups

Group moderators can add and remove members from a group
Can be given permissions ranging from forum moderation to restricted forum access (which can be used to hide forums from non-members)
Can be either public or private (private group members are not viewable)
Private Messages can easily be sent to all group members

Users

Can be of either Member, Moderator or Administrator user account types (which are granted forum-wide permissions respectively)
Private Messages can be sent between users
Can include Instant Messaging details in their public profiles
Can include a photo, biography and web site link in their public profiles
Can define a display name to be their public name instead of their account name
Can define a custom signature to be used in their messages
Can choose not to have their e-mail address shared with other members (the default)
Must activate their accounts before they can use them to validate e-mail addresses

Administration

If it exists it can be configured
Users can be viewed, updated and deleted
Forums can be created, updated and deleted; categories can be defined
Groups can be created, updated and deleted; group moderators can be assigned
Members can be added to groups and groups can be granted permissions in forums
Forum-wide settings such as the installation name, settings, mail server, default forum view, etc, can be set
Old member accounts can be purged from the database, either if they have not been used in the last year or if they were created but not activated within the last week
Automatic forum updating - one click will check if an update is available and let you download it immediately

Misc. changes over previous versions

Modified all date stamps to use a generic date/time format that will work in all locales
Validation protection against common SQL Injection attacks

Requirements

Microsoft Windows 2000/ Windows XP Professional/Windows Server 2003 (Windows XP Home is not supported).
Microsoft IIS v5.0 or newer
Microsoft SQL Server v2000 (or MSDE 2000) database or Microsoft Access 95 or later database (additional database types are planned and can be supported)
Approximately 3mb hard drive space for web files (source code and image files)

Installation

The release of bttlxeForum 2.0 is provided with this article in a convenient zip archive. Once downloaded extract the contents of the zip archive to a temporary directory. The software now needs to be installed to set it up correctly for your target environment by running the bttlxeForum.exe setup program. Follow the remainder of the installation steps as guided by the setup program.

Screenshot of the Installer - Welcome

Screenshot of the Installer - License Agreement

Screenshot of the Installer - SQL Server 2000 Configuration

(For the following sections "offline" means installed on your local development machine or internal network and "online" means installation on a live web server.)

Offline

During the installation you will have specified your local development machine or server name and the location the scripts would be installed to on that machine. You should locate your now-configured installation of bttlxeForum and copy it in the correct location on the target machine.

If you have not previously done so, for example if the forums are not being added to an existing web site, create a web site or virtual directory with Internet Information Services on the target machine that exposes the installation.

Access the target directory through a web browser and run the onetimesetup.asp script to complete the installation. The script is automatically deleted after execution if your access permissions allow it, but if not you must delete it manually.

If you completed the process correctly the software should be able to detect it is being accessed offline and ensure that all relevant links and database connections are correct for the installation.

Online

Again during the installation you will have specified your live web server name and the location the scripts would be installed to on that machine. You should locate your now-configured installation of bttlxeForum and copy or upload it in the correct location on the target machine.

(Note if uploading via FTP: ensure that any image files and/or database files are uploaded as binary files. If your installation choices require it there may be a ReadMe.txt file accompanying your installation that will explain any directories that need special access permissions or locations.)

If you completed the process correctly the software should be able to detect it is being accessed online and ensure that all relevant links and database connections are correct for the installation.

Advanced Note

If you wish to use the same database for both offline and online installations, or wish to make changes to your configuration before you run the onetimesetup.asp script, you can edit the database connection string and associated details in the createdatabase.asp file in the target directory. Note that changes to the connection string will need to be copied to the appropriately named files in the /include/config directory.

Usage

This section will provide basic walkthroughs of a typical end user and administrator.

End User Walkthrough

The main page of the forum software shows a list of the available forums that are visible to the current user (logged in anonymously or with a member account) organised according to their category. The user chooses a forum to view it's messages.

Screenshot of the forum home page

When viewing a forum the messages, format and actions that are shown to the user will be determined by their current "view" settings that can be seen and changed at any time from the top of the message list. The user can search that forum for keywords by entering search terms into the search box, or can search the forums with more advanced criteria using the separate "Search" page.

If allowed new messages and replies can be created, and formatting options shown to the user to aid them in formatting their message.

Screenshot of the reply to message page

Users can send private messages to other members that will be sent to their virtual mailbox within the software.

Screenshot of the private messaging homepage

A users public profile contains the personal information that they explicitly choose to expose to other users, such as their name and e-mail address.

Administrator Walkthrough

The Forum Administration pages are made available when logging on using an Administrator account and provide easy access to all the important areas of the software:

bttlxeForum configuration

View and modify the global bttlxeForum settings such as the site name, e-mail server, default user settings and whether the site is live or disabled for maintenance.

Screenshot of the admin configuration page

Template Configuration

Change the template/theme being used. Installed templates will be shown as a list that you can choose from.

Members

View either summary or detailed views of your registered forum members including links to update their information.

Screenshot of a member account being edited

Forums

Add, remove or modify forums and their categories, and manage group access and permissions to specific forums.

Screenshot of a forum being edited

Groups

Add, remove or modify groups and manage group members.

Clean Member Accounts

This lets you remove users who never activated their accounts or those who have not used their accounts in the last year from the database.

Help and Tips

View helpful information and tips for administering the bttlxeForum software. Currently this page links to this article and the online support forums.

Update Scripts

bttlxeForum 2.0 includes a new method for updating the software by automatically upgrading the software and your databases when a new version is published. These pages will tell you more and guide you through any update if available.

Development

This section outlines the structure of the forum software and where various actions are performed.

Organisation

The scripts are split into six sections according to their task that are reflected in the directory structure:

Admin - All administration tasks are in this section; from managing forums to setting up group permissions and checking for updates to the software.
Forum - The front-end viewing and forms for adding messages to forums. The code to perform tasks such as getting and displaying messages are in the Utils section.
Include - Files included in the other sections, such as the database configuration and path information.
MyAccount - All scripts relating to the user accounts and user tasks are in this section, such as profiles, private messages and account maintenance.
Templates - Contains subdirectories for each installed theme the software can use. The Templates directory contains further instructions for working with themes and templates.
Utils - This section, split into further sub directories, contains most of the actual code for the software.

Where To Look

Using the organisation information above it should be easy to find the section in which specific functionality is implemented or should be added. The scripts in each section are named so as to be self-descriptive to their purpose, for example a script that inserts new forum messages would be called new.asp and be located in the Forums section.

Consider the following examples:

If you want to add a new field that users can include in their public profiles you would look for the profile scripts in the MyAccount section.
If you want to modify the Frequently Asked Questions for the forum you would look for the FAQ script in the Forum section.
If you want to install a new template, or modify an existing one, you would look in the Templates section.
If you want to define a new "view" for displaying messages in a forum you would look in the "views" directory in the Utils section.

Known Issues

The advanced search results are sorted by thread and forum first and then by date.
Some installations will require tweaking to work, typically if you use a non-standard web server configuration or a remote database.

License

bttlxeForum 2.0 is licensed software. You must agree to the full license when you install the software but for quick reference the summarised version is shown here:

You are permitted to use or hold the software free of charge for any purpose, including learning and modification, but not to pass it on at cost to another party or claim ownership.

If you make changes to the software and wish to release them in source code form to another party then you must obtain permission to do. There are some other conditions to and restrictions on using the software that are outlined in the opening sections of the full license.

Credits

I would like to thank:

The bttlxeForum beta testers, for helping to find, squash and prevent bugs from creeping into this release as well as numerous feature suggestions, and for the patience in seeing the beta test through.
Jason Jystad, for the script behind much of the dynamic entry controls for inputting messages.
Chris Maunder and Uwe Keim for some of the underlying code and idea.
James Shaw, for one of the best ASP resources I've found on the net, www.coveryourasp.com, and for the code behind some of the features of the software.
Everybody who has been waiting over a year for this release!

Finally I would like to thank the owners of CodeProject.com for continuing to provide such a wonderful resource for developers at no cost to its members.

History

12 June 2004 - Third release of this article to accompany version 2.0 of the software being released. A complete rewrite - too many changes to list!

18 September 2002 - Second release. Numerous enhancements to the scripts have been made, including:

Bug fixes - all of the reported bugs to-date have been resolved in this release, bar those mentioned above. I think...
Administration scripts - you can now administrate the member system and the forums through the web.
User interface enhancements - the user interface has been rewritten to be more intuitive.
Anonymous users - you can choose to allow anonymous posts in any forum.
Forum access rights - you can limit the creation of new threads or replies in any forum.
Thread control - you (the administrator) can delete threads or a specific post entirely - or lock them to prevent further replies.
New message tracking - messages posted since your last visit will be marked as new.
Security enhancements - you can no longer enter HTML, script, SQL, etc into various fields for possible client side or SQL injection attacks.
Keyword Searching - you can filter any of the forums by specifying a keyword (can include wildcards) and only the matching messages will be shown (and keywords highlighted!)

14 February 2002 - Initial release.

Contents

bttlxeForum - Advanced ASP Forum Software