************************************************************
CMFpgForum Version 1.0.0 beta - Overview and Features
************************************************************

CMFpgForum is a CMF (and/or Plone) discussion tool that uses
a PostgreSQL database backend for the storage (and rapid
search / retrieval) of threads and postings.

Once installed, a CMFpgForum instance is a complete,
stand-alone website component with the following features:

  * each instance has a customizable front page which can
    be edited using the built-in CMF/Plone editing toolset

  * built-in search functionality with options for
    searching within both message subject and body, only
    within the message subject, or within a single thread

  * the PostgreSQL database backend provides fast search /
    browse functionality, as well as scaling extremely well
    under heavy load, and large volumes of data

  * users can choose separate sort methods for threads and
    search results, selecting between Subject, Author,
    Number of Replies, Date Created, and Last Reply Date,
    in ascending or descending order

  * user sort preferences are stored in a cookie so as to
    remain persistent throughout the users' session 

  * site administrators can mark threads as "high priority"
    which keeps them fixed at the top of the "browse" page
    regardless of which sorting method users choose

  * site administrators can "lock" threads to prevent users
    from adding any more postings within them

  * site administrators can always edit or delete any
    posting or thread, and can choose to preserve or delete
    replies to the posting that is being deleted

  * users can edit their own postings, until either the
    thread is locked, or their posting has been replied to

  * by default, the forum allows anonymous access, but will
    also acquire permission settings from the parent folder

  * threaded flat view, shows messages ordered by thread,
    then date within thread

  * Previous and Next buttons appear to help users browse
    through large numbers of threads or search results


************************************************************
License
************************************************************

Copyright (c) 2003 - Emergence by Design Inc.
All Rights Reserved

This program is free software; you can redistribute it
and/or modify it under the terms of the GNU General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE. See the GNU General Public License for more
details.

You should have received a copy of the GNU General Public
License along with this program; if not, write to the Free
Software Foundation, Inc., 59 Temple Place - Suite 330,
Boston, MA  02111-1307,  USA.


************************************************************
Installation and Requirements
************************************************************

For information, read INSTALL.txt


************************************************************
Using CMFpgForum
************************************************************

Creating an instance of CMFpgForum:

  * follow the installation instructions for this product,
    as detailed in INSTALL.txt

  * insure that you have a working PsycopgDA database
    connection, connected to a live PostgreSQL database
    within your existing CMF or Plone instance

  * log in to your existing CMF or Plone site using an
    account with sufficient permissions for the creation
    of a new content object

  * go to the "folder contents" view  and add an instance
    of "CMF pg Forum" - you will have to assign it a
    unique object ID

  * the initial "edit" page for this instance will behave
    differently the first time it is viewed than on
    subsequent views of the edit page. The first time you
    edit your forum, you will be asked to select a database
    connection from the list of available connections which
    you have created within your CMF / Plone site. As well,
    you will need to assign the forum a "title" before you
    can use the forum

  * you can add text to the "Description" field which will
    appear on the front page of the forum when it is
    viewed, so that you describe the intended purpose of
    the forum, rules of conduct, etc.

Browsing, searching and reading messages:

  * the front page of a CMFpgForum instance shows a listing
    of threads which have been created within the forum. To
    view a thread, just click on the thread's subject. The
    resultant page will contain a "threaded flat" view of
    all of the postings within that thread, showing the
    author, subject, date posted, and the message body.

  * each posting block will be indented the appropriate
    amount to indicate which posting it is in relation to.
    The postings are displayed by thread (reply to reply
    etc.) and then descending chronological order. Small
    arrows are used to indicate the level of indentation
    beside each posting block.

  * a link at the top of the "thread view" page will take
    users back to the front page of the forum. The link
    reads "Back to the message board browse page".

  * if there are too many threads to display on the front
    page, the "message board browse page" will present
    an interface for "paging" through the list of  threads
    within the forum.

  * users can re-order the threads displayed within either
    the "message board browse" or "search results"  pages
    by clicking on one of the column headings to order by
    that column. An arrow shows whether the column is
    being used to sort in ascending or descending order.
    Clicking a column, or the arrow, for a second time
    will cause the ordering to switch between ascending
    or descending.

  * from both the main "message board browse" page and the
    "thread view" page, a search widget can be used. It
    appears above all of the postings. A checkbox allows
    users to specify that they only want to search within
    message subjects. As well, the search widget in the
    "thread view" page also offers an option to search
    only within the current thread.

  * after conducting a search, users can choose to view
    a posting by clicking on it's subject. If the posting
    is not itself the root message of a thread, the user
    will be taken to an anchor within the "thread view"
    page where their selected posting is displayed. As
    well, the selected message will be further indicated
    by a yellow bar above it which reads "This is the
    message which you selected from your search results."

Starting a new thread:

  * from the front page of the forum, users can click on
    the link which reads "Add New Message".

  * the resulting page contains a form which asks the user
    to enter both a Message Title and the Message Body.
    Enter values for both and then press either "Post
    Message" or "Preview Message Before Posting".

  * If the user presses "Post Message", the message is
    posted immediately and the user is taken back to the
    front page of the forum.

  * If the user pressed the "Preview Message Before
    Posting" button, they are taken to the Message
    Preview page where they can see how their messsage
    will appear. There are two submit buttons presented:
    "Post Message" and "Edit Message". The "Post Message"
    button posts the message immediately and returns the
    user to the front page of the forum. The "Edit
    Message" button takes the user back to the Add New
    Message interface, presenting them with the same
    form as described above, but this time the form is
    pre-filled with the Message Title and Message Body
    which had already been entered. The same options are
    then presented again; Post Message and Preview Message
    Before Posting.

Replying to a posting:

  * unless the thread has been locked by an administrator,
    all postings are displayed with a link that reads
    "REPLY" in the far right of the top bar of the posting.
    Clicking on this link will take the user to a form
    page which is identical to the form page described above
    in the section "Starting a new thread". Upon completing
    this same process by choosing to post their message,
    the user will be returned to the "thread view" page that
    they came from when they clicked the REPLY link.   

Editing or deleting postings:

  * if a user has posted a message, but that message has
    not been replied to yet, the author will have the option
    to edit or delete their own posting. This option will no
    longer be available once a reply has been added to the
    message. There are a couple of notable exceptions:

      - if a user posts a message while not logged in,
        they will be unable to edit or delete the posting
        as there is no certain way to verify their identity
        as the author.

      - Administrators can always edit or delete a posting
        regardless of who the author is and how many replies
        there are to the posting in question. Deleting the
        thread will cause all replies (recursively) to be
        deleted as well. Deleting a post within a thread
        will present an Administrator with two options if
        the post has been replied to:

	  (1) Delete the message along with all replies
              to it (recursively), and

	  (2) Delete the message and "reassign" all
              of it's replies to it's parent message

Locking threads:

  * while logged in as an Administrator, the user will be
    presented with the option to lock a thread from the
    "thread view" page. This option appears near the top of
    the page, right below the search widget.

Changing thread priority:

  * while logged in as an Administrator, the user will be
    presented with the option to alter a thead's priority
    from the "thread view" page. This option appears near
    the top of the page, right below the search widget. If
    a thread has a priority set to "high", it will always
    appear in the top rows of the front page of the forum,
    no matter what options users select for ordering the
    threads in this view.


************************************************************
Credits & Contact Information
************************************************************

This product was created, and is maintained by:

Emergence by Design
200, 11209 - Jasper Avenue
Edmonton, Alberta, Canada
T5K 0L5

http://www.emergence.com

Email: cmf_pg_forum@emergence.com

Tel: 780-413-6397


************************************************************
Known Issues
************************************************************

  * the front page of an instance of CMFpgForum has an
    HTML-level problem in a default Plone install; the right
    side of the "Thread Browse" table has no right border on
    certain browsers. As CMF / Plone sites are typically
    customized before deployment, the HTML included in this
    product probably needs to be worked on anyway for the
    purpose of integrating with the customized site
    appearance, and customized CSS class names.


************************************************************
ToDo
************************************************************

  * an administrative tool for subdividing an existing forum
    into two or more new message boards, contained within
    the existing forum object

  * an advanced moderation system, allowing for separate
    configuration options for each forum instance

  * ability to mark own postings as being "off-topic"

  * ability to select and customize alternate thread views,
    such as choosing number of levels / replies to show, or
    allowing views like "simple threaded"

  * optional patch for integrating search functionality into
    CMF / Plone site search - this can already be done by
    creating a customized method of "search" in a default
    CMF instance, using SQL examples from within this
    product's code


