w-agora logo documentation

 

For the ancient Greeks, the Agora was a public place where people came to buy and sell goods and to meet to exchange news and ideas.

 

Table of Contents

 

1. Introduction

1.1 installation :

1.2 Concepts :

2. Administration :

2.1. Configuration

General Layout parameters
Frames
Include files
General options for Notes publishing
List and display messages
Search
File upload
Browse server
Send Mail

2.2. Password

2.3. Layout/Publishing

2.3.1. Notes list
2.3.2. Messages
2.3.3. Header
2.3.4. Footer
2.3.5. Html form
2.3.6. Database fields
2.3.7 Document template
2.3.8 Included script

2.4. Delete Notes
2.5. Access forum
2.6. Admin

1. Introduction

This package provide you the ability to create web forums and allows your users to publish and share information/discussions over the web.

Users can post, delete, modify and reply to notes or messages, and upload files.

The same application can be used to install customizable forums (threaded discussions), Bulletins boards, guestbooks, web publishing and so on.

The features are detailed in a separate document:
features.html

1.1 installation :

Read the README file in order to setup w-agora for the first time or to get instructions for migrating existing installations

1.2 concepts :

The goal of the program is to provide a customizable interface to generate HTML documents (called notes) resulting from of FORM filled in by a user.

  1. The user fill in a form to post a message in a " forum "
  2. The program create a note in the database and store the datas submitted by the user and create an HTML document from a defined template.
  3. The new note is now visible to all users of the forum (w-agora list the notes stored in the database)
  4. the same user can then edit (modify) or delete his note (protected by password)
  5. Another user can now view and reply to the note (w-agora runs the same process but in that case, the new note is "threaded" (linked) to the previous one)

Because you can create your own form and your document template (one for the entire forum) and you can define which fields will be stored in the database, w-agora is more than " yet another forum software ".

You can also use it for example:

The principle of the program is succinctly described in the diagram below :


Sheme

2. Administration :

The administration of all forums is accessible at the URL: admin.php3

You can access to the administration of a specific forum by clicking on the forum name listed on the main administration page (admin.php3). You can also access directly to the administration of a specific forum by accessing the URL : admin_forum.php3?bn=<forum_name>

To create a new forum click on the "create" link in the header. You can also create a subforum by clicking on the Add image. This function can be used to create a new forum "linked" to another.

To remove a forum : click on the "Delete" image.

2.1. Configuration

You can configure several aspects of a forum. The first link in the header menu allows you to configure the main settings of your forum :

2.1.1 General Layout parameters :

These parameters allows you to modify the appearance of the forum :

 

2.1.2 Frames :

You can decide whether w-agora will generate frames or not. To suppress the usage of frame, unselect the checkbox. In that case the header and footer will be included respectively at the top and at the bottom of each page displayed.

However, w-agora try to be compatible with old browsers. It had been tested with several browsers (in frame and no-frame mode) such as Mosaic, Opera, Netscape Navigator (1.2, 2.02, 3.1, 4.x) MSIE (3.x, 4.x).

If you choose the default frame mode, you can define the size and position of the frames (tags <FRAMESET> and the header and footer frames (tag <FRAME>)

2.1.3 Include files :

You can define here the files that will define the look&feel and behaviour of your forum.All files will be picked from the forum directory. If you leave blank one field then the default file (located in templates/default) will be used.

All the files can be edited into your browser in the layout/publishing section.

Style sheets :

This file is included inside the <head></head> tags. It is specifically usefull to include cascading style sheets (CSS) but you can also include whatever can fit inside these tags (javascript, conditional PHP code)

Header and footer :

You can here specify the names of the Header and footer files w-agora will insert at (respectively) the bottom and the head of each page.
These files reside in the directory of the forum.
If you leave blank the footer file name, then no file will be inserted.
You can define a non existent file then later edit it thru the administration.
Be careful to define at least a consistent file name for the header (contains the toolbar).

Messages

This is the file that contains all messages displayed by w-agora. See later.

Listing outline

This is the file that define how the notes are listed.

Form

Contains the form that will be displayed in the post,reply and edit functions.

Template

Contains the template for the displayed message.

Fields names

Contains the database fields definitions .

PHP file included before access

You can define a PHP file which will be executed by w-agora. Specify the name of the file that is automatically parsed just before access the database (view / insert / modify / delete). This file is included with the include() function.

This feature is useful to add your own processing (for exemple, increment some values, create file, log informations) before each read/write access to the database.

Before calling your script, w-agora set the variable $bn_action to "view", "post", "reply", "getfile", "delete", "insert" or "update" depending on the context in which the file is called. You can check this variable and add your specific processing depending on its contents.

2.1.4 General options for Notes publishing:

Some options can be enabled or disabled at any time :

use cookies

post in popup window

Allows replies (thread notes)

This option allow users to reply to the messages.

If enabled w-agora will add a " reply " button at the bottom of the document accessed.

Allow modifications

This option allow users to modify their notes.

If enabled w-agora will add a " modify " button at the bottom of the document accessed.

A password is necessary to allow modification of the note (the password set by the user when he posted the note). If the user did not set a password when he posted his note, then the administrator’s password is used.

In all cases, the administrator’s password can be used to modify a note

Allow delete

This option allow users to delete their notes.
If enabled w-agora will add a " delete " button at the bottom of the document accessed.
A password is necessary to allow removing of the note (the password set by the user when he posted the note). If the user did not set a password when he posted his note, then the administrator’s password is used.

In all cases, the administrator’s password can be used to delete a note.

Allows HTML

Use smileys

Convert URLs

 

2.1.5 List and display messages

Append reply form to displayed message

No toolbar in message

No thread in message

Append post form to messages listing

2.1.6 Search

Search support

W-agora support can search in the document contents. The search can be made using an external search engine (currently "swish" or "namazu") or directly into the database.

If the option is enabled then w-agora will add a link in the header and (if needed) will start an indexation each time a document will be added in or removed from the forum.

You can also indicate the pathame to the external program that will be used (if a search engine is used)

2.1.7 File upload

File Upload support

W-agora allow users to upload files to the server.

If this function is enabled then the program will add automatically the appropriate field in the form and will attach the file to the note.

You can specify a maximum size allowed for uploaded files (managed by PHP)

2.1.8 Browse server

This function allow users to browse and attach files located on the WEB server to the notes. This feature can be a security hole, so it is not enabled by default.

However, w-agora controls that users can not attach files located outside the directory (and subdirectories) you have specified (default : /tmp).

This feature is useful in an intranet context : users can upload or create files if they have a login on the machine. Then they can easily put their documents on the WEB server. You can for example put on the WEB documents received via FTP.

2.1.9 Send Mail :

Send mail to administrator

If this option is enabled, W-Agora will send mails to the owner of the forum each time a note is posted or deleted.

You can modify the mail address of the administrator (owner of the forum) and the text sent in the message.

Allow mail reply :

This option allow users to receive replies to their message by email.

2.2. Password :

This page lets you to change the password associated to the forum.

2.3. Layout/Publishing :

This part of the administration allow you to :

You can do each operation in any order.

Each part of this section will update a specific configuration fiel which has been defined previously in the configuration section

2.3.1. Notes list

The list of the notes is done by scanning the database. All fields stored in the database can be displayed in this page (see Database fields " in the publishing chapter).

This screen lets you customize the whole page which display the list of documents.

For example documents can be displayed as a default HTML ordered or unordered list, in a table or any thing else.You can also define which fields will be listed (date, author, mail address, subject, …).

The contents of the fields (variables) can be displayed by preceding the field name with a $.

Some variables are defined by w-agora and have a specific meaning :

$bn : the forum name
$note : the key used to retrieve the note in the database
$formated_date : the creation date of the note in the format defined in the configuration file.

This example show how w-agora display each element defined in this page.

<head list>
<begin thread> (first_odd_line)
<line> (even_line)
<begin thread> (first_odd_line)
<line> (even line)
<line> (odd line)
.
.
<end thread>
<line>
.
.
<end thread>
<end list>

Head of listing : is displayed once at the top of the list

Begin of thread : is displayed for each new thread (if the current note have threaded notes)

Lines : the note itself, must contains the variables to be displayed. These variables (or fields) must have been stored in the database (see Database fields). Ie. you can define the HTML link to the note itself  (view.php3?bn=$bn&key=$note).
Since 3.0.b5 , lines have been splitted in 4 different lines (first/even, first/odd, odd and even). This allows you to define a different headline for the first message in the thread and for the replies. (odd / even pairs allow you to define a different contents (eg. Color) for alternates displayed lines.

End of thread : is displayed at the end of a thread (after the last note on the same level)

Footer : is displayed once at the end of the list

2.3.2. Messages

All the texts (such as buttons, messages, titles) displayed by the program can be redefined. This page allow you to change the messages contents.

You can also include PHP variables (such as form's field names) in the message contents by prefix the variable name with a $.

The contents can also be empty, in this case nothing will be displayed.

You can edit the messages file created by w-agora or you can create your own messages file, assuming you respect the messages numbers.

Notes to PHP developpers : The messages are stored in a PHP array ($msg[]) included by the program, each message is displayed by an echo (stripslashes($msg[n])) statement.

Example : The message 59 contains :
"<center><b>$msg[0] $note has been modified</b></center>"

This message is displayed when a user has modified a document. It contains HTML tags and PHP variables:

$note is a variable containing the file name of the document
$msg[0] is the contents of message #0 ("note" for instance). Using $msg[0] instead of "note" save you to replace this string in all messages.

2.3.3. Header

This page allow you to edit into your browser the contents of the header file displayed (included) by w-agora (see "include files" in the configuration chapter). This file must be located in the directory containing your forum.

This file is included in the "header" frame if the frame option is selected.

If the no-frame option is selected then w-agora include this file in the top of each page displayed.

You can insert PHP code in the text.

2.3.4. Footer

Like the header file, this page allow you to edit into your browser the contents of the footer file displayed (included) by w-agora (see "include files" in the configuration chapter).

This link is displayed only if a footer has been defined (see "include files" in the configuration chapter).

If a footer has not been defined, first go to the configuration page, define a footer filename. Click on the submit button then go back to this page and edit your footer.

2.3.5. Html form

You can edit the form displayed to users to post notes. You may not have to insert the tags <FORM> and </FORM>, they will be inserted by w-agora.

Click on the submit button to save the contents of your form.

Click on the "undo" button to cancel you last modification.

The program automatically add the necessary input fields to manage file upload (associated documents) if the option is selected. The password is also managed by the program.

Some fields may be presents in the form if you use the mail feature:

username : this field contains the user's name

useraddress : this field is set to the user's address, it is used to send mails to the user

subject: it contains the subject (title) of the note posted by the user. It is used as the subject in the mail sent to the administrator and in the mail replies so if you plan to use the user mail feature, it is preferable to keep this field.
This field is also displayed in the summary (list of notes)

body : this field contains the text filled in by the user. It is used as the body in the mail sent to the administrator and in the mail replies, so if you plan to use the user mail feature, it is preferable to keep this field.
This field is also used as a "quoted text" in the reply form.

2.3.6. Database fields

Each field defined in the form corresponds to a PHP variable, each variable can be stored in the database or/and written to the HTML file (see document template below).
This page allow you to specify the fields w-agora will store in the database.
You may have to define database fields :

If you want a field to be displayed in the list of notes (subject, username, ...)

If you want the notes to be generated dynamically.

w-agora also use the database fields to allow the users to modify the notes (for exemple: the field "body" is used for the "quoted reply" function and can be modified).
If you want to limit the space used in the database, you may prefer to not specify all form's fields.

You can define a field as required, if this case w-agora will add the corresponding (client side) Javascript and (server side) PHP code to check that the field has been filled in by the user.

The size associated with the field is used by w-agora when it create a forum table. It is only meaningful if you use an RDBMS (m[y]SQL, postgreSQL, oracle).

To rename a field : simply change the contents of the fieldname.
To delete a field leave blanks in the field name.
To add a new field : fill in the last line in the table the click the "save" button. The new field will automatically be displayed and a new empty line will be added.

Caution:

Currently, if you add or remove fields over existing forums, then you will have to manually add/delete the corresponding field in your table by using an "alter table".

This is not necessary with DBM forums, but in that case, you will not be able to delete fields (but only add fields at the last position).

2.3.7 Document template

Each note created by w-agora is created from a "document template". This page allows you to dynamically modify this template.

You can of course insert HTML tags and PHP variables.
To insert a variable (coming from the form) prefix its name with a dollar ($).

You can choose the way w-agora will create notes (static or dynamic):

In the static mode, w-agora create an html file for each new posted note. The note is created from the template and the variables are substituted by their values. The static mode is useful if you want to perform full text search with swish.

If you choose the "dynamic" option the w-agora will create dynamically an HTML page when the user access the note. The note is also created from the template, but in that case the variables are substituted from the values stored in the database. If you choose this mode, you limit the space used in the filesystem but you can not use the search feature.


Note that you can switch from a mode to another if the fields needed in the note are also stored into the database.

2.3.8 Included script

You can edit a specific PHP script (called before_access file) which act as a sort of plugin in w-agora and can change the behaviour of your application.

The script will be parsed for each page displayed and before w-agora displays anything. This script
This allows you to send an header or cookie before the first header will be sent by w-agora.
The script is executed before writing to the database (ie. in insert.php3 and update.php3) and after reading anything (view, getfile, list, edit, post).
This allows you to perform some operations, ie: incrementing a hit counter before displaying the message, or update some user fields before inserting the message into the database.

2.4. Delete Notes

This page lets you delete several notes into the forum

You can delete notes between 2 dates ( the format is DD/MM/YY) or select individuals notes to delete.

If you select several notes to delete, w-agora tells you the number of notes corresponding to the criteria and ask you for the admin password.

If only one note is selected, it is displayed into the browser and a password (user or admin) is asked for.

2.5. Access forum

This link open the forum in a new window, it is useful to observe the changes made to the configuration. You may have to reload the page to see the last changes.

2.6. Admin

Click on this link to exit administration of this forum and return to the main administration page



Thank you for using w-agora.

Please send your comments, suggestions, bug reports to the
development forums or to mdruilhe@w-agora.com.

Updates and new versions of W-Agora can be downloaded from
www.w-agora.net.



documentation last updated : 2000, September 15