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.
General Layout parameters
Frames
Include files
General options for Notes publishing
List and display messages
Search
File upload
Browse server
Send Mail
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
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
Read the README file in order to setup w-agora for the first time or to get instructions for migrating existing installations
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.
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 :
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.
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 :
These parameters allows you to modify the appearance of the forum :
Y - Year eg. 1995
y - Year eg. 95
M - Month eg. Oct
m - Month eg. 10
F - Month eg. October
D - Day eg. Fri
l - Day eg. Friday
d - Day eg. 27
z - Day of the year eg. 299
H - Hours in 24 hour format eg. 13
h - Hours in 12 hour format eg. 1
i - Minutes eg. 5
s - Seconds eg. 40
U - Seconds since epoch eg. 814807830
A - AM/PM
a - am/pm
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>)
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.
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)
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).
This is the file that contains all messages displayed by w-agora. See later.
This is the file that define how the notes are listed.
Contains the form that will be displayed in the post,reply and edit functions.
Contains the template for the displayed message.
Contains the database fields definitions .
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.
Some options can be enabled or disabled at any time :
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.
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
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.
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)
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)
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.
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.
This option allow users to receive replies to their message by email.
This page lets you to change the password associated to the forum.
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
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
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.
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.
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.
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.
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).
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.
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.
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.
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.
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