milesjohnson

Below you can find a detailed list containing most of the features within the plugin. To better understand each feature, you should download and install the plugin!

Forums

• Parent and children forums
• Activity and latest post tracking
• Auto-Lock old topics
• Enable/Disable post count increments
• Individual settings for reading, posting, replying, etc
• Access/Private specific forums
• Create topics or polls
• Reply to topics, or quote previous posts

Moderation

• Moderators, Super Moderators and Admin levels
• Restrict moderators to specific forums
• Inline moderation and management
• Mass processing (Move, Delete, Close, etc)
• Ability to edit and manage users content

Administration

• Full admin panel using CakePHP admin routes
• Requires the administration access level
• Can add, edit, order, delete forums and categories
• Manage all reported content
• Promote, demote, create access levels, staff and moderators
• Edit forum settings through the panel
• Manage all aspects and content

Security

• Utilizes CakePHPs Auth and Security Components
• Advanced flood protection (Posts and Topics)
• Hourly post limitations
• Registration security wall
• Form protection against bots and hackers

Miscellaneous

• BBCode support using Decoda
• Utilizes remember me features using AutoLogin
• Mark topics as read (Session)
• Log created topics and posts (Session)
• Access level verification
• Report system for topics, posts and users
• Search through topics (Title and Post)
• RSS feeds for each forum

The forum plugin was designed to interact with an external users system and does not provide one. This allows you to drop the forum into an already existent application with ease. However, there are a few things you will need to do.

If you already have a users table, please verify the configuration for $userMap and $statusMap in forum/config/config.php. If you do not have a users table, please create one with these minimum fields: id, username, email, password and status (active, pending, banned, etc). You may name the columns as you please as long as you configure it correctly in the $userMap and $statusMap.

Setting up the model
You will need to manually apply the following forum model associations within your User model.

class User extends AppModel {
 
	public $hasOne = array('Forum.Profile');
 
	public $hasMany = array('Forum.Access', 'Forum.Moderator');
 
}

Setting up your controller
The forum does not come packaged with a login, logout or signup system. This should be done within your applications UsersController outside of the forum. However, there are a few things you will need to add to these actions.

The login and logout actions need to delete the forum session, as to properly assign the correct values when the user visits the forum. Furthermore, the login action must execute Profile::login($user_id).

The signup method can optional execute Profile::getUserProfile($user_id) after a successful user creation, to create the forum user profile. If this code is left out, the forum will automatically create a profile the first time a user visits the forum.

Heres a quick example of this implemented with some helpful comments.

class UsersController extends AppController {
 
	public $uses = array('User');
 
	public $components = array('Auth', 'Session');
 
	/**
	 * Will need to check the status and not login banned or pending users.
	 */
	public function login() {
		if (!empty($this->data)) {
			$this->User->set($this->data);
 
			if ($this->User->validates()) {
				if ($user = $this->Auth->user()) {
					$this->User->Profile->login($user['User']['id']);
					$this->Session->delete('Forum');
 
					$this->redirect($this->referer());
				}
			}
		}
	}
 
	/**
	 * When logging out, delete the Forum session.
	 */
	public function logout() {
		$this->Session->delete('Forum');
		$this->redirect($this->Auth->logout());
	}
 
	/**
	 * After signup is successful, trigger Profile::getUserProfile() to create a forum user profile.
	 */
	public function signup() {
		$this->User->Profile->getUserProfile($user_id);
	}
 
	/**
	 * Disable Auth::$autoRedirect so that you can trigger forum logic.
	 */
	public function beforeFilter() {
		parent::beforeFilter();
 
		$this->Auth->autoRedirect = false;
	}
 
}

Admin routing must be enabled in app/config/core.php.

Configure::write('Routing.prefixes', array('admin'));

As well as RSS parsing in app/config/routes.php.

Router::parseExtensions('rss');

And finally applying these routes.

Router::connect('/forum/help/*', array('plugin' => 'forum', 'controller' => 'forum', 'action' => 'help'));
Router::connect('/forum/rules/*', array('plugin' => 'forum', 'controller' => 'forum', 'action' => 'rules'));
Router::connect('/admin/forum/settings/*', array('plugin' => 'forum', 'controller' => 'forum', 'action' => 'settings', 'admin' => true));

It is also a good idea to create a "forum" folder within your app/tmp folder, and chmod it to 777.

For your convenience, there is an automated installation script that you can run through the command line. If you do not have access to a command line, please jump down to the manual installation section. Simply run the following command in your command line and follow the on screen instructions.

cake -app /path/to/app install

The manual process is a bit tedious, so bare with. To begin, you need to create all the database tables. You can do this by opening up each SQL file in the forum/config/schema folder. Once opened, you need to find and replace each instance of {prefix} with a prefix for your tables, I highly suggest using a prefix to not conflict with existing tables. I recommend using "forum_" (without the quotes). Once you have done this, simply execute each of these MySQL queries in PhpMyAdmin or your MySQL command line.

Up next is creating your admin users. All you need to do is get the ID of the user you want to grant admin privileges for (from your users table). If you do not have a user, simply create a new one and use that ID. Once you have an ID, execute the following query. Be sure to replace the {prefix} and {user_id} values.

INSERT INTO `{prefix}access` (id, user_id, access_level_id, created, modified) VALUES (null, {user_id}, 4, NOW(), NOW());

After the tables are created, open up the plugins ForumAppModel and change the values for $tablePrefix to the prefix you have chosen and $useDbConfig to the database configuration you created the tables in (usually default).

In a fresh setup, the forum should work if you installed it correctly. However, there are times where you need to inject your own code, or to edit the theme, or to edit the settings. The following should help you in your endeavor.

Integrating with a users table
If you integrated the forum on top of an existent users table, you may run into issues where certain field names do not match what the plugin needs. To correct this, you can edit the $userMap and $statusMap within /forum/config/config.php. The $userMap contains a mapping of specific fields that the plugin uses, while the $statusMap are mappings of a users state. Below is an example of some custom mappings.

$config['Forum']['userMap'] = array(
	'username'	=> 'displayName',
	'password'	=> 'passwd',
	'status'	=> 'state'
);
 
$config['Forum']['statusMap'] = array(
	'pending'	=> 'pending',
	'active'	=> 'active',
	'banned'	=> 'banned'
);

Using a custom view layout
If you want to integrate the forum into your own application's layout, and not use the default forum layout, you would have to delete or rename the layout file. The layout file is located at /forum/views/layouts/default.ctp. If you do not use the forum layout, you will need to add the appropriate styles and scripts.

However, your best bet is to keep the forum layout.ctp file, but replace the HTML with the original layout. By doing it this way, you want lose the RSS feed links, nor will you have to re-link the CSS and Javascript.

Customizing the forum theme
The administration panel does not come pre-built with a theme editor. You would need to edit the CSS stylesheet located at /forum/webroot/css/ or create your own from scratch. Additionally, you may edit the views to inject or remove HTML as you please.

Editing the forum title, limits, settings, etc
The forum comes pre-bundled with a list of settings that include flood intervals, page limits, site title, site email, security questions and many more. You will not need to edit these manually because the administration panel has a section devoted primarily to changing settings. Jump to the next chapter to learn more.

The plugin comes pre-built with a full blown administration panel that can edit nearly all aspects of the forum. It can add, edit, delete all the forums, users, topics, posts, reports, moderators, staff, so on and so forth. If for some reason you need to edit something that isn't in the panel, you will most likely need to do it manually in the database.

After you login with an administrator, you will see an admin tab within the menu.

Changing the settings
Within the panel you will notice a "Settings" tab. From here you may change all settings related to the forum. Most of the settings -- besides the site related settings -- have been optimized to work best at those numbers, but you may change them if you please.

Managing forums
All forums are parents or children of each other. The top most-level forums will only act as containers and can not be posted to. Furthermore, you may not have unlimited nested children, for performance sake.

Managing users
The plugin does not have its own users table, so therefor it relies on a profile system. For every external user, the plugin creates a profile. This profile contains all meta data related to the user, like login times and signature. The admin panel will only edit profiles and not users.

Promoting and demoting staff
By default the forum comes with 5 access levels: Guest (being the lowest), Member, Moderator, Super Moderator and Administrator (Being highest of course). Moderators are able to edit specific forums, where as super moderators may edit all forums. Administrators will have full access to everything including the panel. You may create your own access levels -- for example Community Manager, or Staff writer.

Dealing with reported content
Users have the ability to report topics, posts and users if they find the content inappropriate, offensive, etc. Once reported, you can take the required or necessary action to delete, close, move, etc respectively. You also have the ability to discard the report but not edit the source content directly.

If you would like to translate the forum into a new language, or fix a previous language, fork the repo and follow the instructions below. You will need to download PoEdit: http://poedit.net/

Open the program and go to File > New catalog from POT file. Fill in the settings box with the following information

Project: Forum Plugin
Team: <Your Name>
Team Email: <Your Email>
Language: <Pick the language>
Country: <Pick the country>
Charset: UTF-8
Source code: UTF-8
Plural: <Leave blank>

Save the file as forum.po and place it anywhere. Once saved, the program should populate with the text on the left. Translate the sentences on the left by typing in the translation box in the bottom. When you come across text with the %s and %d symbols, that means those symbols will be replaced with dynamic data

%d = Integer/Number
%s = Text/String

"The forum %s has been deleted, and all its forum categories have been moved!"
"The forum General Discussion has been deleted, and all its forum categories have been moved!"

Those are required to work correctly, just place those symbols where they would be within the translated string. You may find some others like %count% and %total%; leave those as they are as well.

When you are done, simply save the file. You should now have 2 files, a .po and .mo. The .po file should contain all your translated strings.

#: /controllers/stations_controller.php:101
msgid "A total of %d topic(s) have been permanently deleted"
msgstr "<YOUR TRANSLATED VERSION HERE>"

Lastly, create a folder for your language within the locale folder, based on the 3 character locale. Within the language folder, create the LC_MESSAGES folder and place the files within. Commit and push! Once done, I will review and merge with your changes.