This manual is outdated and needs a major rework - any volunteers?


pnForum v2.0.0 beta

----------------------------------------------------------------------

Table of Contents

1.Introduction
= 1.0.1 License


2.Installation
= 2.1 Requirements
= 2.2 Install preparations
= 2.3 Installation


3.Upgrading
= 3.1 Preparations
= 3.2 phpBB_14 versions 1.7.6 (PostNuke .72x)
= 3.3 phpBB_14 versions 1.7.2.1 - 1.7.2.x (PostNuke .71x)
= 3.4 phpBB_14 versions 1.7.2.1 - 1.7.2.x (PostNuke .70x)


4.Setup
= 4.1 Forums Administration
= 4.2 Using PostNuke Permissions
= 4.3 Setting up the Statistics block
= 4.4 Setting up Search Include


1.0 Introduction

Thank you for choosing pnForum as your PostNuke forum software. pnForum is based on the phpBB-forum originally created by 'The phpBB Group'. We have added an extensive list of features to pnForum that I am sure you will enjoy. pnForum is designed for use as a module with the PostNuke, .75x (http://postnuke.com)

We have spent a lot of time on this product and hope that you find it to be as useful as we intended it to be. Support for pnForum can be found at http://pncommunity.de with a multilingual FAQ area both for Users and Admins and at http://snowbankih.tzo.com (English only).

After you have installed pnForum, we encourage you to list your web site in the 'Demo' forum on http://pncommunity.de Please mention the language of pnForum on your site, so native speakers can visit it :)

1.0.1 License

This product is protected under the GNU General Public License (GPL). For full details on this license and the rights it grants to you, the user of this software, and to us, the developers, please see the file COPYING that is distributed with this software. Also, for more information on the GPL and the Free Software Foundation visit http://www.fsf.org/ or http://www.gnu.org/


2. Installation

2.1 Requirements

pnForum is designed to run as a module under the PostNuke .75x series. It is assumed that you have the appropriate version of PostNuke already running on your web site.

2.2 Install preparations

2.2.1. Please check if this is the latest version available at http://pncommunity.de or http://snowbankih.tzo.com first. These are the primary support sites for the pnForum module with a multilingual FAQ area both for Users and Admins.

2.2.2. Make a backup of your PostNuke database (we recommend using phpMyAdmin) and the entire /html/modules/pnForum directory. Then, remove the following directories and files:
/modules/pnForum
/includes/search/pnForum.php
/includes/blocks/pnForum.php

This will prevent you from creating potential errors if there were any changes in the filenames or an error in the setup.
This is a safe proceedure, since all these files will be restored from the new distribution and all forum settings are kept in the database.

Right now we do do not have a script designed specifically for backing up the pnForum-module related tables in your database. And since backup is a good idea for all Phoenix tables, we suggest the use of phpMyAdmin.

Important Notes:
1. Due to some changes in BBCode and Smilie-Handling within pnForum, it is advised that you install and activate three new modules; pn_bbclick, pn_bbcode and pn_bbsmile. These files are available in the 'Download' areas at http://pncommunity.de and http://snowbankih.tzo.com

 

2.3. Installation


2.3.1. Extract directories from distribution into the appropriate PostNuke Phoenix html directories.
No files from Phoenix or other modules can be damaged by doing this.
Do not rename the pnForum module directory. There are hard coded links to its name within this directory.
You can use any names in your forums when creating links in menublocks.

2.3.2. Go to the PostNuke Administration panel,
enter the Modules section. Press the 'Regenerate' link.
You should see pnForum in the modules list.
Press 'Initialize' on the right side of the page. This will create the module's tables and fill in some constants.
Normally you should get a 'Module initialized' message at the top of the screen.
Press 'Activate' in pnForum line.
This will make pnForum Administration panel visible in PostNuke Administration.
Then, do the same 'Initialize' and 'Activate' procedures with the pn_bbcode, pn_bbclick and pn_bbsmile modules.
Now, while still in the Modules section, the 'Regenerate' or 'List' links. To the far right side of the pnForum module listing, you will see 'Deactivate | Edit'. Click on 'Edit'. Place a check mark in the three boxes to activate pn_bbcode, pn_bbclick and pn_bbsmile. Then save.

2.3.3. Go to PostNuke Administration panel.
Select the pnForum link.
Click on 'Sync forum/topic index'. This will sync the list of users in PostNuke and pnForum.
Click on the 'Forum Wide Options' link .
Click on 'Restore defaults'. This will set parameters for pnForum

2.3.4. Go to Administration/Blocks section.
In the appropriate menu block create a new entry for your forum.
For example 'Forums'.
Link should be:
{pnForum}
Save it.

2.3.5. You're done with the pnForum module installation.
pnForum is now administered using the PostNuke Administration panel.
There you can make general forum settings, define new Categories, Forums, Private Forums, User Rights, User Ranks, Honorary Ranks, re-order categories and forums within them.

2.3.6 If you have $bgcolor3 and $bgcolor4 as different colors in your theme, then you will get a color change with a 'mouse over' while in the forum index and category views.

2.3.7 You can create background images for your tables.
cell1.gif for tableheader and cell2.gif for category (to be placed in /themes/YOUR_THEME/images) Both images must be liimited to 28 pixels in height.

2.3.8 If you use style sheets in your themes, the styles contained in them will be reflected in pnForum. You can also use: pn-phpBB-Title, pn-phpBB-border and pn-phpBB-cat for additional customization of your forums.

2.3.9 If you are using AutoTheme; $bgcolor1, $bgcolor2, $bgcolor3, and $bgcolor4 are defined in /yourtheme/theme.cfg using the names 'color1', 'color2', 'color3' and 'color4'.


3. Upgrading

3.1. Preparations

Do preparations as in 2.2.1, 2.2.2

3.2. Upgrading from phpBB_14 versions 1.7.6 (PostNuke .72x)

Copy new files into place.
Delete the existing file /includes/blocks/pnForum.php
Go to Admin panel/Modules. Use 'regenerate' link.
Find pnForum module link and use 'Upgrade' link nearby.
You will need to 'Activate' the module after the page reloads.
Delete any old phpBB_14 related blocks you had created and make new ones.
Then, 'Initialize' and 'Activate' the three new modules that were installed; pn_bbcode, pn_bbclick and pn_bbsmile modules.
Now, while still in the Modules section, the 'Regenerate' or 'List' links. To the far right side of the pnForum module listing, you will see 'Deactivate | Edit'. Click on 'Edit'. Place a check mark in the three boxes to activate pn_bbcode, pn_bbclick and pn_bbsmile. Then save.
Also see 2.3.5
You're done.

3.3. Upgrading from phpBB_14 versions 1.7.2.1 - 1.7.3.x (PostNuke .71x and up)

Copy new files into place.
Delete the existing file /includes/blocks/phpBB_14.php
Go to PostNuke/Administration/Modules. Use 'regenerate' link.
Find pnForum module link and use 'Upgrade' link nearby.
You will need to 'Activate' the module after the page reloads.
Delete any old phpBB_14 related blocks you had created and make new ones.
Then, 'Initialize' and 'Activate' the three new modules that were installed; pn_bbcode, pn_bbclick and pn_bbsmile modules.
Now, while still in the Modules section, the 'Regenerate' or 'List' links. To the far right side of the pnForum module listing, you will see 'Deactivate | Edit'. Click on 'Edit'. Place a check mark in the three boxes to activate pn_bbcode, pn_bbclick and pn_bbsmile. Then save.
Also see 2.3.5
You're done.

3.4. Upgrading from phpBB_14 versions 1.7.2.1 - 1.7.2.x (PostNuke .70x)

Due to changes in upgrade procedure between Phoenix releases .70x and .71x, there is no easy and fast way of doing this.
- write a note with the exact pnForum version that you had previously installed
- backup your database (see 'Note:' below)
- backup phpBB_14 tables
- drop the database tables and erase following folders:
modules/phpBB_14
includes/search/phpBB_14.php
includes/blocks/phpBB_14.php
- follow 2.3.1. (only this step)
- replace this line in pnversion.php
$modversion['version'] = '1.7.4';
with
$modversion['version'] = '1.7.0.0';
if your previous version were any from 1.7.0.0 to 1.7.0.3

or with:
$modversion['version'] = '1.7.0.4';
if your previous version were any from 1.7.0.4 to 1.7.2.0
- install module as a clean install.
- drop all pnForum tables
- restore your initial phpBB_14 tables from backup copy
- modify pnversion.php with version number you are installing
- follow 3.2.


4. Setup

After the initial installation, you will be able to go to the PostNuke Administration panel and select the pnForum icon to administer your forums.

4.1 Forums Administration

This is where you can administer your pnForum forums.

4.1.1 pnForum:
Forum Wide Options allows you to:
a. Configure who you want the email to come from when someone subscribes to a topic and gets an email showing a new post.
b. Set the Character Set that will be used in the e-mail headers.
c. Set the -Hot Topics- threshold.
d. Set the number of posts per topic that will be displayed per page.
e. Use your own custom images.|
d. Allow the html codes that were set in PN Settings to be shown or not shown below each message.

'Sync': Allows you to synchronize the PN users, forums and topics indexes to fix any discrepancies that might exist.

4.1.3 Add a Category:
Categories are the top level of the individual forums.
'Add': After clicking on 'Add', you will be give a space to type in the name of your new category. Click 'Submit' when done entering your text.
'Edit': This will allow you to 'Edit' or 'Delete' any categories that have been previously made.
'Re-Order': Allows you to re-order the Categories.
'Delete': This will allow you to 'Edit' or 'Delete' any categories that have been previously made.

4.1.4 Add a Forum:
Forums are the various 'sub-categories' that your individual discussion will be kept in.
'Add': After clicking on 'Add', you will be give a space to type in the name and desctription of your new Forum. Highlight who you want to moderate this Forum and which Category you want the forum to be in. Click 'Submit' when done entering your text.
'Edit': This will allow you to 'Edit' or 'Delete' any Forums that have been previously made.
'Re-Order': Allows you to re-order the Forums within individual Categories.
'Delete': This will allow you to 'Edit' or 'Delete' any Forums that have been previously made.

4.1.5 Users Ranks
You have the ability to create various 'Ranks' for users based on the number of posts they generate.
' Add': After clicking on 'Add', you will be give a space to type in the name and desctription of a new User Rank.
'Edit': This will allow you to 'Edit' or 'Delete' any Users Ranks that have been previously made.
'Delete': This will allow you to 'Edit' or 'Delete' any Users Ranks that have been previously made.

4.1.6 Honorary Ranks
You have the ability to create 'Ranks' for special members. This could be 'Webmaster', 'Associate', 'Client', etc.
'Add': After clicking on 'Add', you will be give a space to type in the name and desctription of a new Honorary Rank.
'Edit': This will allow you to 'Edit' or 'Delete' any Honorary Ranks that have been previously made.
'Assign': This will allow you to 'Assign' any Honorary Ranks that have been previously made.
'Delete': This will allow you to 'Edit' or 'Delete' any Honorary Ranks that have been previously made.

4.2 Using PostNuke permissions with the pnForum bulletin board:

This chapter assumes that you already know PostNuke permissions principles.
pnForum implements four levels/instances of controlling access rights to the module.
These are:
Category
Forum
Topic
StatsBlock
You are therefore able to control how a user or a user group may use your forum.

This is also correct regarding moderator access to forums and categories. Moderator access is checked against MODERATE_ACCESS in PostNuke permission system for any given user or group. Setting the moderator parameter inside pnForum administration panel is only for display purposes in forum and category view. The permissions are only defined by the permission system.

Following are some examples on how to use the PostNuke 0.71x permission system in the pnForum module. We will use these names in the examples to give you a "realworld" examples:
Category: General
Forum: Chitchat and discussion
Usergroup: Mygroup
User: JimDude


EXAMPLE 1.
Cut off Unregistered users from accessing private forum. Unregistered users will not even see that a private forum exists.
Go to Administration/Permissions/New group permission

Group Component Instance Permissions level
Unregistered pnForum::Forum Chitchat:: None

Because upper lines override lower, the newly created group permission should be above this line:
Group Component Instance Permissions level
Unregistered .* .* Read


EXAMPLE 2.
Cut off Unregistered users to a whole category. All forums inside the category will be inaccessible.

Group Component Instance Permissions level
Unregistered pnForum::Category General:: None

Because upper lines override lower, the newly created group permission should be above this line:
Group Component Instance Permissions level
Unregistered .* .* Read


EXAMPLE 3.
Let Unregistered users view forums in a category, but not post or reply to posts.
(as the smart eye sees, dropping the following line, will cause unregistered users to have read-access to all categories)

Group Component Instance Permissions level
Unregistered pnForum::Category General:: Read

Because upper lines override lower, the newly created group permission should be above this line:
Group Component Instance Permissions level
Unregistered .* .* Read


EXAMPLE 4.
Let a closed Usergroup access all forums in a category. All users not in this group fully cut off.

The first thing to do is to create the Usergroup and populate it with users. (we will not show how to do this here..).

Group Component Instance Permissions level
Mygroup pnForum::Category General:: Edit
All groups pnForum::Category General:: None

Because upper lines override lower, the newly created group permissions should be above BOTH of these lines:
Group Component Instance Permissions level
Users .* .* Comment
Unregistered .* .* Read


EXAMPLE 5.
Assign moderator rights to a specific user. This is done in two parts.
First you have to define the user as a moderator of the forum, using the pnForum admin pane. (Note, this is only for viewing purposes in the forums at this time...)
Next, you have to give the same user moderator rights in the PostNuke
permission system. This is done using this scheme:

User Component Instance Permissions level
JimDude pnForum::Forum Chitchat:: Moderate

NB! Be very careful of using USER permissions. They will always override any group permissions. If you do something wrong, you may end up shutting your self out! Always use other usernames that your ADMIN name, when playing around with user permissions!!


EXAMPLE 6.
Assign a user to be moderator for two forums.
This is done in two parts. First you assign the user as moderator to both the forums, using the pnForum admin pane.
Next, you have to give the same user moderator rights in the PostNuke
permission system. This is done using this scheme:

User Component Instance Permissions level
JimDude pnForum::Forum (ChitChat|discussion):: Moderate

Note:
Be very careful when using USER permissions. They will always override any group permissions. If you do something wrong, you may end up shutting your self out! Always use other usernames than your ADMIN name, when playing around with user permissions!!

We also suggest looking at the PostNuke permissions documentation :
http://sourceforge.net/docman/index.php?group_id=27927

4.3 Setting up Statistics/Center block

You can activate and place these blocks, using standard Phoenix Blocks administrating.
Create a either a side block or center block of type 'pnForum/pnForum Statistics'/'pnForum/pnForum Centerblock'. Configure it with the PostNuke 'Edit' feature to meet your needs.

4.4 Setting up Search Include

The search routine for pnForum is included in the module core and needs no special set-up to be used with PostNuke.