1     Introduction

1.1      Important notes before proceeding

2     Installation (for system/web server administrators)

2.1      Requirements

2.2      Download and install

2.3      Setup and configuration

2.3.1      Create a database

2.3.2      Grant a user for that database

2.3.3      Create tables (forums, forums_seq and user)

2.3.4      Link script to the database

2.3.5      Change Password

3     Moderation (for moderators)

3.1      Set up or change D3E-phorum defaults

3.1.1      Changing a forum’s default look-and-feel

3.1.2      Switching a forum's default options on/off

3.1.3      Managing smilies ;-D

3.1.4      Other administration tasks

3.2      Create a forum for a document published by publisher's toolkit

3.3      Changing a forum’s look-and-feel

3.4      Forum administration

3.4.1      Deactivating and Deleting forums

4     End user notes (for end users of discussion fora)

4.1      Subscribe/unsubscribe to email list

4.2      Message formatting

5     Acknowledgement

1       Introduction

If you’ve come this far we assume that you already know about the Digital Document Discourse Environment (D3E), other wise please read the relevant background at http://d3e.sourceforge.net

D3E-Phorum is a discussion environment tailored particularly for D3E. It works with D3E Publisher's Toolkit  (http://d3e.open.ac.uk/d3e-toolkit.html) to generate an on-line digital document discourse environment.  After a document has been published by the D3E Publisher’s Toolkit, an ‘discussion initialisation’ file is uploaded to D3E-Phorum which then generates a web discussion space, and provides tools to maintain the forum including administration, user control, message filtering, moderating and editing.

1.1      Important notes before proceeding

This version of D3E-Phorum is designed for a single moderator. The creation, administration and maintenance of all discussion forums is assumed to be carried out by this person. However, the moderator can give moderation rights over a forum to anyone by issuing a forum-specific password. They can customise the discussion site by login D3E-Phorum admin with that particular password.

2       Installation (for system/web server administrators)

2.1      Requirements

D3E-Phorum needs to be installed on a server that runs PHP and MySql:

1.  MySQL

version 3.22.25 or later http://www.mysql.org

2.  PHP

Php4 version 4.0.1pl2 compiled with --enable-track-vars   http://php.net/

(most ISPs compile PHP with --enable-track-vars)

or PHP3 version 3.0.6 compiled with --enable-track-vars  http://php.net/

(most ISPs compile PHP with --enable-track-vars)

3.  Web server

Apache version 1.3.3 http://www.apache.org/, or IIS4+

2.2      Download and install

Download D3E-Phorum from the D3E download site.

You can choose to run it from this site or save it on your hard drive and run it later. Once you start to run it, an installation process will start automatically. Follow the instructions from the screen, until you see the following window:

 

By default it will install D3E-Phorum into directory "C:\temp\d3e-phorum". You are advised to change "C:\temp" to your web root. For example, if your web root on your web server configuration is "E:\web\pubroot", replace "C:\temp" into "E:\web\pubroot", so in the above screen shot, you will have "E:\web\pubroot\d3e-phorum". Click "next" to continue. The installer will install d3e-phorum into your web root and copy all the files into "d3e-phorum" directory automatically. Follow screen instructions until finish.

2.3      Setup and configuration

2.3.1     Create a database

We planned initially to create the database and connect the database from automatic scripts, but for security reasons we will leave this to you to do manually. If you have managed to install MySql, the following procedure will be straight forward. Otherwise please consult MySql documentation.

 

Under DOS prompt, goto "mysql/bin/" directory and run mysqladmin.exe.

 

 

here, <user> is the mysql root user or a granted user who has the privilege to create a database; <password> is the password used by that user.

 

(If this is the first time you’re use MySql, it may well be that the user "root" with no password is open to you. Therefore you can use that user name and password to create a database. However in most case, when installing your MySql, you will create a password for the root user. If you did, use that password; if you use mysql client and the MySql server is maintained on another machine, ask the MySql administrator to create a user and issue a password for this purpose.)

2.3.2     Grant a user for that database

We assume you now have the privilege to access mysql with full access. The first task is to create a user and password that will be used by the D3E-Phorum scripts. The privileges the user needs are select, insert, update, delete, create, alter and drop for operate.  The scripts will use this name and the password to access MySql. To grant a user, we use mysql.exe rather than mysqladmin.exe.

 

 

If you have a problem accessing mysql, most likely you have used a wrong user name and password. Please make sure you have the correct user name and password.  Once you have entered mysql, issue the following statement terminated with ";"

 

           

If you want access from another machine rather than where the MySql is installed, you also need to grant the

same user access on any other machines by using the same grant command but change localhost to @%.

           

 

 

Here "d3eforumuser" is the user name and "admin" is the password. You can replace them by anything you like. However, whatever you chose, you need to take a note because they will be asked for later in the configuration.

2.3.3     Create tables (forums, forums_seq and user)

Copy d3e-phorum.sql from "D3e-phorum\db" directory into the directory where mysql.exe resides (normally in "C:\mysql\bin\").

 

 

This will create three tables:  forums, forums_seq and user.

2.3.4     Link script to the database

Go to D3E-Phorum administration page from a web browser (http://../d3e-phorum/admin/) and you should see this page.

 

 

If you cannot see this page, open file "forum.php.php" in "d3e-phorum/include" directory,  check that the value of the $forum_url matches the file path in your file structure. Change it if it is not. Try to reload from your web browser. If you still have a problem to see admin page after reloading, change the value of the $forum_url to "localhost/d3e-phorum". Once you see the admin page you can change it back to the full URL of the D3E-Phorum in your web server from the admin page.

 

Input "admin" (all lower case) as password. You can change your password now or at any point later.

 

Click "Global Settings" on the menu, and "database" from the next level menu. The following screen will be displayed on your screen.

 

Change MySql server name to the name of your local machine, e.g. d3e.blah.org. Input the name of the database you have created by using mysqladmin.exe in this case it is "d3eforum", then the name and password you have granted by using mysql.exe. Then hit "Update" button. It will tell you that your operation is successful.

Don't worry if the top-right corner still shows "No Database Connection Available". It will be changed following any action that now takes place. For example, you could click "Refresh D3E-Phorum Service" now, and you will see it will change to "Database Connection Established".

2.3.5     Change Password

Change your password to keep your site safe.

You are advised to change your D3e-Phorum admin password now (though you can change it any time you like).

Click "Change password" from the "Global settings" then input your new password twice, and finally hit "Update". It has been illustrated in the next screen shot.

 

3       Moderation (for moderators)

The moderator can control numerous parameters. A moderator is able to do everything necessary for the discussion site to be fully functional and continuously running.

The main tasks include:

1.     Set-up or change defaults in D3E-phorum look-and-feel

2. Create a forum for a document published by D3E toolkit
3. A particular forum's control and maintenance

3.1      Set up or change D3E-phorum defaults

You hardly need to change your forum database, script file's name and extension once it is up running. However, you could do so if it is needed. Please make sure that you know what you are doing when dealing with them. If you don’t, ask your system administrator for help.

You may need to change your forum root URL. It can be done by click on the "URL/Files/Paths" from "Global settings".

 

 

A form is displayed, enter with the suitable value then hit the "Update" button. The important thing to remember is that you can not enter an URL and assume it will work. You need to make sure the "URL" is match with the file path in your web server root. In addition that is the path you have provided to the user of the D3E publisher's toolkit.

3.1.1     Changing a forum’s default look-and-feel

A forum's look and feel, once it is created, is taken from the default feel and look. This is where you can change it. Click "Forum Look and Feel" from the "Global settings". You will see the following form (we have added the visual key on the right to help).

 

The value of a variable has been indicated on the right hand side of the screen. Enter the value you want then hit the "Update" button on the bottom of the screen. If you are not sure the value of a variable, it is not crucial, you can check it from newly created forums and change it any time you want.

3.1.2     Switching a forum's default options on/off

There are a number of options, which will affect a forum's look-and-feel. You can switch them on/off here. Click "Forum Options" from the "Global settings" you will see the following form:

 

 

Variables you may wish to change are d3e_forum_name, default email, and smilies.

*       D3e_forum_name is used when an email alert is sent to a user through your email system. It appears in the subject field to indicate the source. The current setting will thus look like this in the email message Subject line:

*       Default email address is used in two places. One is used in the "From" field in an email message; the other is to set an email account with this "box name" so that a user reply the email message will be inserted into the forum (threading email replies back into the web page is not available in this version).

*       Smilies are a set of preset small icons that can be used to indicate the nature of a message. This function can be switched on/off from here. Managing the actual smilies themselves is explained in the next section.

3.1.3     Managing smilies ;-D

Similar to email, smilies in D3E-Phorum are icons used in subject and body of a message to indicate either the sender’s feelings/emotions, or perhaps to classify a message (e.g. you could design icons for Action Item, Question, Problem, CounterArgument, etc). It can add flavour, but it can also make a serious message appears less formal. Therefore use it or not is merely a preference.

Smilies work only in a ‘smilies-aware’ forum. It works through typing "short-cut" into desired place like subject or body of a message. The number of icons, the appearance and the shortcut can be modified, deleted and added through this facility. Clicking on "Smilies" from the "Global settings" gives the following screen:

 

 

*       View and remove existing smilies.
Default smilies are listed in the table (see above). Notice that each smilie has a short-cut associated with it. You can change the short-cut by typing in the new one; you can also remove a smilie by ticking its Remove checkbox. Hit the "Update" button to register the changes.

*       Add new smilies.
In order to add a new smilie, you have to create the new smilie first. You can either select one smilie from the directory "d3e-phorum/images/extra_smilies/" or create a brand new one in an image processing tool. If you create a new smilie, you need to be aware of the image size (check an existing one). You then move the smilie into " d3e-phorum/images/smilies/" directory.

Now you can go to D3E-phorum admin and click "Add smiles" button. In the next screen type the smilie's src in a format of "smilies/boo.gif" then the short-cut you want to be associated with that smilie. Hit the 'Add' button. See next screen shot.

 

3.1.4     Other administration tasks

1. You can turn off the whole D3E-phorum service for maintenance by clicking "Stop D3E-Phorum service". Once you complete your work, click "Start D3E-Phorum service".
2. There is no harm at all in clicking "Refresh D3E-Phorum service" at time you like. What is does is just refresh all settings.
3. There are other hidden functions that you as an moderator can use:
• Allows for censored posting. This had been in an included file called censor.inc in "include" directory. There are instructions in that file as to how to use it. By default certain words are censored. You can change them into whatever you want to be censored.
• User Banning. You can ban users by their email, name, or their IP/HOST. See bad_*.inc in include directory for details of use.
• Allows for disallowing service to a given author, email or domain. Entries in bad_names.inc, bad_hosts.inc and bad_emails.inc will be checked for when a message is posted. If any are present, the user will be forwarded to violation.php. There are instructions in those files as to how to use them.

3.2      Create a forum for a document published by publisher's toolkit

Once a document is published by the D3E Publisher's Toolkit, a discussion initialization file named "disc.inf" will be created and stored in the "articles/out/<input-doc-name>/D3E-Phorum/" directory. It is this file that is needed by D3E-Phorum to generate a forum for it. The following procedure is valid for any forum created in D3E-Phorum.

For test purposes you do not necessarily need to have the D3E Publisher's Toolkit running. You can simply use the sample "disc.inf" file in the "example\test\" directory created with this distribution. The following instructions are based on this test file. For a real forum creation, you use the "disc.inf" file generated by the D3E Publisher's Toolkit.

Go to the administration site

In your web browser go to admin (http://your-web-site/d3e-phorum/admin/)

When the D3E-Phorum administration login appears enter the password.

Previewing the discussion header file

Before create a new discussion forum, you can preview the discussion header file generated from the D3E Publisher's Toolkit (disc.inf). Select "View disc.inf files" from the top menu. A file selection window will pop up:

 

Either enter the pathname  for the disc.inf file or select it using the "Browse" dialogue. Once located, hit "Enter". The contents of the specified "disc.inf" file will be displayed, allowing you to check that the right thread topics have been created.

You can create a forum now.

Create a new discussion forum

Select "Create new forum" for the top menu. Specify the target "disc.inf " file, then hit Upload. Confirmation that the disc.inf file has been parsed, and a new forum has been created is displayed:

If you created this forum for a document published by D3E Publisher's Toolkit, you can go back to the output files and verify that the correct discussion is now displayed in the frameset.

Important note: If the discussion you have generated does not appear in your document web site, check the Setup tab in the D3E Publisher's Toolkit. Is the value of "Discussion Server " correct? If not, all the links to the discussion will have the wrong URL. See the Publisher's Toolkit User Guide for details: http://d3e.sourceforge.net/UserGuides/D3E-Toolkit-Guide.html

If you processed the test disc.inf file, just click on the link at the foot of the page to view the newly generated discussion site.

3.3      Changing a forum’s look-and-feel

Once a forum is created, you are able to see it in action now. If you are not happy with its look-and-feel (e.g. want it to match your particular document's look-and-feel) you can change it at any time.

D3E-Phorum allows you to change various colours, and set custom headers/footers (e.g. logos).

Change a forum's Look-and-feel

Select "Manage existing forums" from the top menu. All existing forums will be listed. Click on the one you want change its look-and-feel. Be aware that it may have same name in different forums, but its ID will be different. Make sure you selected the correct one by check the ID and the name on the top of the screen against the one you want.

 

 

In the menu of the next level, select "Edit Forum Look&feel and Other Properties", as illustrated in the next screen shot,

In the next screen, scroll down to the bottom from the side slider bar. You should see same variables listed as in the default look-and-feel. Enter desired value and click "update" button.

 

Don't' worry about other fields which you don't know in the moment. Just try to remember your forum id and name.

Now click 'View forums' on the top menu, all the existing forums will be listed. Select the one you have changed, you should be able to see your changes take effect.

Create a new header and footer

You can also add images as background or a logo at the top or bottom of the discussion. You can do so by create a brand new header and footer file. An example is given with this distribution in "example/exHeaderandFooter/" directory. You can view them from your browser.

To create one yourself you can copy and past them into your include directory and modify them to what you want. Remember the names are important. If you want the forum 'disc5' using a header and footer, you need name them header_disc5.php and footer_disc5.php   

3.4       Forum administration

3.4.1     Deactivating and Deleting forums   

Deactivating an existing forum removes the forum from visible service but does not completely remove it from the system. It can always be activated  later. It is wise to deactivate a forum for a while before deleting it.

To deactivate a forum, in D3E-Phorum admin select "Manage Existing Forums" from the top menu. In the next level menu select the forum you want to deactivate. Then click "Deactivate this forum":

 

Deleting a forum purges it completely from the database. A deactivated forum will just invisible to end-users. Clicking 'Delete This Forum' will ask for your confirmation. Always make sure you select the correct forum!

If you feel that there may be users who are trying to use a forum which you want to deactivate or delete, you can always stop the whole D3E-Phorum from service first. Stopping D3E-Phorum, click "Global settings" from the top level menu and then  "Stop D3E-Phorum Service". See the next screen shot. Remember to start D3E-Phorum after your operation.

 

 

2. Administration of individual messages

 D3E-Phorum provides some administrative facilities for individual forum maintenance tasks at the message level: editing, hiding and deleting.

Easy admin.

From D3E-Phorumadmin page select "Manage Existing Forums" from the top-level menu, choose the forum you want to carry out administrative tasks.

 

 

Select "Easy Admin (Delete/Edit/Hide msgs)". See next screen shot.

 

 

Notice that by default all messages are approved. In the next screen all messages are listed. Specifically,  the message id, author and post date are displayed. (you may need to know id for other quick operations such as delete, edit, approve or hide). See next screen shot.

 

On the right of screen three possible actions are supported. Delete is to purge the message from the forum. Once a message has been deleted it can not be recovered. You can edit a message by click 'Edit'. You can hide a message by click 'Hide'. Hidden message becomes invisible to user. You can always turn it into visible by click 'Approve'. 'Approve' option only appears once the message has been hidden.

Quick Edit/Delete/Approve.

D3E-Phorum provides quick administrative facilities if you knew the message id that you want operate on.

 

Once all existing forums are listed, select the operation you want. Then the action you want. They all work similar to the actions in the "easyadmin".

Reset the sequence of message id.

Once you’ve carried out a number of deletions in a forum, the message id numbers will be discontinuous. You can reset msg id numbering using “Reset Sequence of Msg Id”.

Any change you made can always be checked by goto "View forums" from the top-level menu.

4       End user notes (for end users of discussion fora)

The threaded discussion interface is relatively straightforward and self-explanatory. However, here are a few hints on things that are not so obvious, e.g. getting formatting into the content of messages.

4.1      Subscribe/unsubscribe to email list

D3E-Phorum has two different email lists in a published document. One is on the document level. If you subscribe to this list, D3E-Phorum will send you an email copy of any new comments posted to the forum. The other level is on the message level, where you can specify that you want to be notified by email of any new replies to a specific message.

To subscribe at the document/whole discussion level, click on "Subscribe" at the top-left corner of the discussion page (see next screen shot):

 

A new page prompts you to enter your email address. Hit "Submit" button:

 

 

You can always unsubscribe once you have received an email message. Every email message has a footer with a link that will direct you to the unsubscribe page.

To request email notification of all replies to a specific comment you have made, in a forum's post comment page (see next screen shot), simply tick the box at the bottom: "Email replies to this thread, to the address above":

 

4.2      Message formatting

When you compose a comment, you can use some HTML tags and links in your message. The following box lists what you can use and how.

In addition, if a forum has been set to "allow html" (contact your moderator), full html is allowed that means you can post your message in a completely html format.

You can also quote the message you are replying to by clicking "Quote". The text appears, ready to insert your comments.

5       Acknowledgement

D3E-Phorum is developed at the Knowledge Media Institute, Open University, UK. by Gangmin (Gary) Li and Simon Buckingham Shum. The D3E Project gratefully acknowledges the support of BP Amoco Exploration, Sunbury-on-Thames, UK, in developing this software.