Preface

Welcome to SuperBoards version 1.2.2. SuperBoards strives to be small, fast, and clean-looking. This readme will help you install the application and show you some basic stuff you need to use the forum.

 

Table of Contents
  1. About this release
  2. Installation instructions
  3. Using SuperBoards
    1. End user
    2. Administration and maintenace
  4. Developing for SuperBoards
Section 1: About this release

This file is part of SuperBoards.

SuperBoards is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

SuperBoards is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with SuperBoards. If not, see <http://www.gnu.org/licenses/>.

Just a quick disclaimer, SuperBoards is released under GPL, so you can use, modify, and distribute this software. SuperBoards is provided as-is and there is no guarantee for reliability or security. This was originally a fun project for me to work on in my spare time and have decided to share my work. If you have any suggestions, improvements, or bugs send them to wt@wesleytabaka.com.

This version of SuperBoards incorporates many improvements over the last public release of SuperBoards, version 0.9.1. The most significant of these changes are the PHP/MySQL interface. PHP has deprecated using the original mysql module. As such, SuperBoards has followed suit and now fully implements MySQLi (MySQL improved). Also, SuperBoards is now HTML 5 compliant as of May 19, 2014. HTML 5 is still experimental, but it is anticipated that no major changes will happen to the HTML 5 standard as it stands now. SuperBoards is also CSS 3 compliant.

SuperBoards 1.2.2 was developed in the following server environment:

  • Apache/2.4.7 (Win32)
  • PHP/5.5.8
    • gdlib for PHP is a necessary module
  • MySQL/5.6.15-log - MySQL Community Server (GPL)

Designed, developed, and programmed by Wesley Tabaka <wt@wesleytabaka.com> for Nanashi Foundation.

Country flag icons by Mark James, www.famfamfam.com

Section 2: Installation instructions
  1.  Unpack the archive file using the appropriate extraction tool.
  2.  Upload the entire directory "SuperBoards-1.2.2" to your web server. Once uploaded, you can change the name of this directory to anything you'd like.
  3.  Point your web browser to the "install" directory within the SuperBoards directory. This will bring you to the installation page.
  4.  Follow the directions on each of the setup pages. First, you should make sure the file "dbauth.php" is writable. On a *nix server, CHMOD "dbauth.php" to 666. On a windows server, make sure the file is writable. The installation page will not let you continue until this step is done. Press "Proceed to Step 2".
  5.  Set up your database on your server or with your web host.
    You'll need the database server's hostname and port number, database name, a username, and a password. Enter all of this information on the installation page.
    You will also set up the administrator's account on this page. Enter a username, a password, confirm the password, and enter the administrator's birthday and email address.
    Press "Proceed to Step 3". The installation will now begin. Please be patient and do not stop your web browser. This may take several seconds.
  6.  If the installation is a success, you can press "Proceed to Step 4". If you encountered an error, the installer will digest the problem for you and identify issues and solutions.
  7.  Make the file "dbauth.php" read-only. CHMOD the file to 644 or make it read-only. This prevents other users from tampering with your database.
    Delete the entire contents of the "install" directory. This prevents other users from overriding your installation with a blank one.
  8.  Click the "Show me my forum!" button. You can now use your forum system. If the installation completed successfully, you'll see a post in one of the forums saying the installation was a success. Feel free to delete this post. Enjoy your new forum system!
Section 3: Using SuperBoards

This section is broken down into two subsections. The first discusses how to use the forum if you are an end-user. The second discusses how to use it if you are the administrator.

  1. End user
  2. Administration and maintenance
Section 3.1: End user
Registration

Registering for a SuperBoards forum is easy and gives you many more benefits. Click "Register" on the top menu or on the login bar. Choose a username. You will be prompted if your username is already in use or contains invalid characters. Enter a password and confirm it. Enter an email address. Enter your birthdate. You will also need to enter a captcha to prevent spam. If you get a captcha that is illegible, click "New Captcha" and enter the new code. You can choose some of your preferences at this point. You can choose whether you want the shoutbox to appear. The shoutbox is like a chat room for members of the forum. Choose whether or not to display your email address publicly. Choose who you want to receive private messages from. Enter your location (a country is required). Enter other contact information and interests. Upload an avatar, enter a signature. Read and agree to the terms of service.

Logging in

If you are not logged in, the login bar will appear on every page. Enter your username and password and click "Log in". Or, on the menu bar, click "Log in". You can log in from this page as well. There is also an option to "Remember Me". You won't have to manually log in for 1 year if you check this box and log in successfully.

Browsing the forum

Forums are broken up into heirarchies to organize similar discussions. The forum breaks down into Categories (most broad similarity), Forums, and Topics (most specific). From the home page one or more categories will appear and categories will contain one or more forums. Choose a forum you are interested in. From a forum page, you can browse topics. You can sort topics by their subject name alphabetically or sort them by the original date or the most recent post date. Pressing the arrow on the right of a topic takes you to the most recent post in that topic. There may be many topics in a forum. As such, you may have to switch between pages of topics. On the top right and bottom right there is a drop-down box that will allow you to skip between pages of topics. The same applies to viewing a topic. Many posts may exist within a topic. It will be necessary to switch between pages. The drop down box appears in the same location.

Rather than browsing many topics and forums, it is possible to search for topics, users, and private messages. You can search the forum by any of these criteria by clicking "Search" on the menu bar.

Posting to the forum

Depending on the preferences of the administrator, it may or may not be possible to post to the forum if you are not registered. That is, guests may also post to the forum if allowed by the administrator. You will be prompted if this is not allowed. In this case, you should register if you wish to post. If posting is allowed for guests, the guest will have to enter a captcha at each post to prevent spam. In addition, a guest's posts cannot be edited or deleted by the same guest. It is difficult to coordinate whose post belongs to whom if the user is not registered. If this functionality is desired, the user should register.

To post to a particular topic, enter the topic page and click on the top left or bottom left "Post Reply". You can enter a subject line and a message which can be formatted with SBCode. Clicking on the format buttons will insert the necessary SBCode tag. You should insert your text to be formatted inside the square bracket tags. For instance if you wanted to make your text bold, click the bold text button. "[b][/b]" will be inserted in the message field. You should enter your formatted text like this: "[b]Bold text[/b]". To post your message, click "Post". Upon success, you will be presented with a link to your new post.

If a topic you're interested in does not exist, go to the appropriate forum and click on the top left or bottom left "New Topic". You can now start your own topic.

If you are a registered member, you can edit and delete your post. To do this, go to the appropriate post. On the bottom right of your post will appear several icons. The leftmost icon (aI) allows you to edit your post. The next icon over (X) lets you delete your post. These icons will not appear for you for posts made by other users. All members can report abuse or a questionable post by clicking the exclamation point icon (!) on any post. See the section "Reporting abuse" for more information.

Private messages and contacts

It is possible to send messages to individual members of the forum in private (i.e., not in the public forum). When you have an unread private message in your inbox, the "My Messages" link on the menu bar will show a number. This is the number of unread messages in your inbox. The "My Messages" link will bring you to your inbox. From here you can compose a new message by clicking "Compose", manage your contacts list by clicking "My Contacts", search your messages by clicking "Search Inbox", or view messages you have sent by choosing "Sent" in the drop down box. These options are located at the top right.

You can select multiple messages using the checkboxes on the left of your inbox and perform operations on them using the drop-down box on the bottom left. These include deleting and marking read or unread. If you have many messages, they will appear on several pages. Switch between pages using the drop down box at the bottom right. You can sort messages by sender, date, and subject line by clicking the fields at the top of the page.

You can subscribe to your inbox by RSS by clicking the RSS icon at the bottom right of the page. If your web browser supports RSS feed detection, this option should be made available to you.

Composing a message
Click "Compose" from your inbox. You can enter the recipient's username. To send to multiple recipients, separate their usernames with a semicolon (;). You can also add users from your contacts list by clicking the button to the right of the Recipients field. Check the users you wish to send to and press "Done". The recipients field will now be populated. Enter a subject line. Enter and format the message as you wish. Press "Send" to send the message to the recipient(s). You will recieve a notice that your messages were sent successfully or notify you of any errors that occur. The most common error is that some users may opt to recieve private messages only from those users in their contact list. You will be notified if this is the case.

Reporting abuse

SuperBoards makes it simple to report abuse or spam. If you witness or are a victim of abuse or a post contains inappropriate content, you can report the offending post by clicking the exclamation point icon (!) at the bottom right of any post. You will be asked for a brief comment. Click "Send Report". Forum moderators and administrators recieve these reports and take further action. They can edit the offending post, delete it, and administrators can take further action with the user by suspending their account or deleting their account. The user's IP address may also be suspended.

If you are unsure if something is inappropriate or are contemplating filing a report or not, you should send one anyway. It is the job of the moderators to monitor the forum and protect its users from the smallest of problems to the biggest of issues.

If the abuse or inappropriate content was not present on the forums themselves but through a private message, for example, you should send an email to the moderator or administrator with what was sent by the offending user and a brief comment from yourself. You can retrieve a list of forum staff for you to contact in this instance by clicking the "Forum Staff" link that appears at the bottom of every page of the forum system.

Section 3.2: Administration and maintenance
Section 3.2.1: Logging in to administration tools

Point your web browser to your forum's address and add "/admin" to the end of the URL to log into administration tools. Enter your username and password.

Alternatively, you can sign in as you normally would using the front end. If you are not already logged in, the login bar appears on all pages. Enter your username and password. Once logged in, click "Administration" on the menu bar. You will be asked for your password once more.

Section 3.2.2: Setting up your forum

It is important to organize and tailor your forum to suit the needs of your users. When your forum is brand new, the administrator must set up the separate categories and forums that will appear.

There are four main heirarchial levels to organizing a forum. There are categories, the broadest level of organization. Inside each category may be several forums. Inside each forum may be many topics. Inside each topic may be many posts. Posts are the "leaves" of the forum "tree".

Let's say you are starting a forum for a specific model of car. You might make two categories: one strictly for discussion of the particular car; the other for off-topic discussion. Inside the category dedicated to this car, you might make several forums for each of the marks of the model of car.

To start organizing your forum, log into the administrator interface and click "Forum Management" on the left menu. There will be links to create new categories and forums. These names and descriptions can be modified at a later time if necessary.

You can also change the order in which categories and forums appear on the main page by changing the number next to each of these and clicking "Save Orders".

Now that you have organized your forum to your satisfaction, users will know where to post similar discussions. If you want to continue to modify your forum setup, topics and forums can all be renamed at a later time.

Section 3.2.3: General configuration

From the "General Configuration" link on the left menu, you can modify your forum in many ways. You may temporarily disable the forum to end users, change the title and description of your forum, add a custom header and footer or a news ticker, change censorship settings, change settings for the calendar, and write a custom terms of service.

Section 3.2.4: Miscellaneous settings

From the "Miscellaneous" link on the left menu you can change even more settings. You may set up using a custom banner, change membership requirements, change date formatting, write a custom message welcoming new users, change avatar settings, and more.

Section 3.2.5: Style settings and themes

From the "Style Settings" link on the left menu themes can be installed and new ones can be selected.

Section 3.2.6: Managing users and ranks

It is important to be able to have control over a forum's users. Using the administrator interface, an administrator may edit a member's profile, suspend their account or IP address, delegate greater permissions to users, or delete a user entirely.

You may browse through all of the forum's members by clicking "User Editor" on the left menu. You may also search for a member by their username or their most recently used IP address. Once a user has been selected, you may edit their profile. You may also change their rank, delete the user, or suspend the user using the links at the bottom.

You can see a list of all the users and IP addresses that have been suspended from the forum by clicking "Ban List" on the left menu. You may unban any of the users on this list by clicking "Unban" next to the user's name or IP. You may also suspend a list of IP addresses using the utility on this page.

A user's rank is important in defining the rights of the user. Click the "Ranks" link on the left menu to apply a rank to a user, create a new rank, or edit the permissions of an existing rank.

Ranks themselves are nothing more than a name and a permission level. They behave like user groups. Every registered user has a rank. If you have given many users permission to behave like forum moderators and would now like to demote all of them, you may just change the permission level associated with the rank by clicking "Edit" next to the appropriate rank.

Section 3.2.7: Security incident reporting

SuperBoards generates incident reports when the forum is behaving in a way that is consitent with hacking or other malicious intent. Some such event reports might be generated if a user attempts to login unsuccessfully too many times. Manipulating form data and URL data will also trigger reports. These reports are not neccessarily malicious incidents. But many reports like these from the same user should be an indication of malicious intent. You can search reports by username and IP address. New reports will cause the left menu to show a red number next to the "Security Events" link and the "Administration" link will flash on the forum's front end. When you want to dismiss the alert that pops up, mark the report "read" by clicking its checkbox and choosing "Mark read" in the drop down box and press "Go". Reports can be deleted in the same way.

Section 3.2.8: Managing flagged posts

Users may report questionable content or abuse to moderators and administrators. If you are an administrator or moderator and there are unread reports, "Administration" or "Moderator Controls" will flash red on the menu bar. When you have signed into the administrator interface, a number will appear in red next to "Reported Posts" on the left menu. Click this link to be taken to this utility.

Reports may be filtered by the complainant's username, the original author's username, the post subject, or the date on which the report was filed. You can also select to view only read reports, unread reports, or both. Unread reports appear in bold. To view a report, click "view". You will be shown the complainant's comments and the post being complained about. From this screen, you can edit the original author's post, delete the post, or mark the report as unread.

You can delete reports in bulk using the "Prune Reports" utility. Enter the date from which reports should be deleted. You can also opt to not delete reports which haven't been read.

Section 3.2.9: Creating backups and restoring your forum

Regular maintenance is important for the administrator of a forum. Creating backups on a regular basis will help protect against unintended damage to your forum and against malicious users trying to compensate the integrity of your forum.

To create a backup of your forum, click "Backup/Restore on the left menu. There are two utilities. To create a backup, click "Create Backup". Wait a few moments and you will be prompted to download a backup of your database, containing all of your forum's content and settings. It is important that you do not stop your web browser while this process is taking place. Doing so may corrupt the backup file.

In the event that you need to restore your forum to a previous state, you may do one of the following:

If your forum is unusable or has been corrupted and you cannot reach the administrator's interface, you may use the backup file you have saved using your web host's database management utilities. Often, the program that is used is called "phpMyAdmin" -- this utility lets you run queries on your database. You will need to drop all the tables in your database. Then, upload the backup file and run the query. This should restore your forum to its previous state.

If your forum is still usable and would just like to revert back to an old state, go to the "Backup/Restore" page. Select the backup file from your machine to upload. Click "Restore". You will prompted if you wish to proceed. You will receive a warning if the file you uploaded is not recognized as a SuperBoards backup file or if the backup is from another version of SuperBoards. If you are sure you want to continue, click "Proceed with Restore". DO NOT STOP YOUR WEB BROWSER. THIS MAY TAKE SEVERAL SECONDS. Stopping your web browser during this process will cause permanent damage to your forum and corrupt its database. You will be notified when the database restoration has completed successfully.

Section 3.2.10: Creating mass messages

Sometimes it is necessary to send a message to all members of the forum. The mass message utility allows you to do this. Click "Mass Message" on the left menu. Compose a message. Before sending it, you may preview the message to see how it will appear. When you are happy with the message you may press "Send". A notice will confirm your messages were sent successfully or if there were any problems.

Section 4: Developing for SuperBoards

At the present time there is no SuperBoards API. However, themes may easily be created. You will find a collection of images for each theme under the themes/<yourtheme>/images directory. A theme should consist of a collection of all of these images with the same naming scheme, but adopted to suit your design. A theme must also consist of a style.php file under the themes/<yourtheme> directory. A theme installer file follows the format below:

The file is essentially an SQL query that inserts the theme into the SuperBoards database. Items in carats (<>) should be changed to suit your theme and your information.