Back to the Forums

This User Manual covers fcForum Product version 0.0.15-beta and 1.0.0 RC1

Table Of Contents

1. Product Description
2. Why This Product?
3. Features
4. USER'S GUIDE
1. Browsing the Forums
2. Registering (Sign-Up)
3. Logging in / Logging out
4. Editing your profile
5. Language settings
6. Subscriptions
7. Post a new Topic
8. Respond to a Topic
9. Editing a Topic
10. Search for Topics
11. Special Formatting Codes
12. Contacting another Member
13. Contacting the Administrator
5. ADMINISTRATOR'S GUIDE
1. Manage Forums
2. Manage Topics
• Parent Topics
• Children Topics
3. Manage Users
4. Pagination
5. Permissions & Security
6. INSTALLATION GUIDE (Technical notes for the enlightened zopista)
7. Credits
8. License
9. Disclaimer
10. Achnowledgements

Product Description

fcForum is an Open Source forum (Messageboard) system developed in Zope. Zope is a next-generation Open Source application server and portal toolkit developed by Digital Creations and a large active community of users. It runs on nearly all UNIX platforms as well as Windows NT and can be used with most popular web servers or its own built in web server. Zope is written (and extensible with) Python, a powerful object-oriented programming language, with performance sensitive components written in C.

Back To Top

Why This Product?

Isn't there a lot of "free" full-blown Message Board products already in the market?, you might ask, well, my response is: "There's none in Zope" (at least not as standardized and clean). While Browsing through the Zope Main site, I was looking for a way to "store" news and/or events in a way that it would be easy for the visitors of my personal website to understand, read and participate in them. I found some interesting ones, but "fixing" them, so they'd have the "look and feel" that I wanted was so hard (color definitions everywhere inside the code, specific hardcoded font sizes, poor compliance with web standards, etc, etc) that I'd be better off writing one of my own. That I did, fcForum is compact, web-standards compliant, clean and fast, it does not require a database back-end (such as the PHP based forums, or MySQL ones), Zope has a super-fast relational, object-oriented, transactional database (ZODB) embeeded in it, that all it required was the code to put it to work.

Back To Top

Features

Here are the main features of the product:

• User Registration. Instead of asking for absolutely all your information, even your refrigerator's invoice number, etc, You can register on the system just by responding to 5, that's five questions only (and one of them is the confirmation for your password), in fact, all you need in order to register in the system is giving your username and password (with confirmation) that's it, no ICQ number, no SSN, no Federal Tax ID Number, nada.
• Simple. Displaying of topics and forums is easy and clean, yet elegant, no complicated color schemes, no flying fire-throwing-dragons arround your screen, and of course, no ads. Replying to topics requires only a few keystrokes and a click of a mouse. Ergonomically-friendly
• Secure Password information is stored encrypted using the unix crypt() methods, Zope's security model makes the entire system virtually unhackable.
• Administrative Tools. Administrators have absolute control over all parameters of the forums, including pagination (number of topics shown per page), user management, forum management, topic management, among the most important functions.
• Language Support. fcforums currently fully supports English and Español Languages for topic posting and for presentation.

Back To Top

USER'S GUIDE

This user guide will try to provide information on the use of the system to the regular user, either registered or not

Browsing the Forums

The main forums page should contain a list of the available Forums, click on any forum's title to enter that forum, once you are inside a forum you will see a list of Topics ordered by posting date, click on any Topic's title to view the complete topic description and all the responses (if there are any), use the links provided to navigate the site, such as back, back to main, etc.

Back To Top

Registering (Sign-Up)

Go inside any of the available forums, then, on the top-right corner of your screen, you will see two buttons labeled "Sign Up" and "Log In", respectively, the Sign Up button is used when you want to register yourself as a new user. Click on the button and you will be taken to the New User Registration page. Select a valid login name, use names such as a combination of your first and last name, (i.e. John Smith --> jsmith), or a specific "nickname" (i.e. souldcrusher, and select a password and confirmation. Please note that username and password are BOTH case-sensitive. Optionally, type in your Name and email and click the "Add" button.

You will then be taken back to where you were right when you clicked the Signup button, if for some reason you selected a name that is already on the system, or an invalid response, you will be taken back to the register page and a message will be shown telling you exactly what went wrong. After You successfully register in the system, please note: you will not be logged in, you will have to go and click on the "Log In" button in order to complete the operation, of course you can choose not to log in at that time and come back later, knowing that your username and password information was already stored in the system.

Back To Top

Logging in / Logging out

Go inside any of the available forums, then, on the top-right corner of your screen, you will see two buttons labeled "Sign Up" and "Log In", respectively, Click the Log In button to display the Log In page, you'll be asked for your Username and Password, remember that Username is not case-sensitive, whereas Password is. Click the "Ok" button after your selection, if successful, you will be taken back to the page you were before and the buttons at the top-right section of your screen, will change to "Edit Profile" and "Logout your-user-name", You can now add new topics or respond to existing topics, use the link labeled Add New Topic to add a new topic, or enter any of the topics and go towads the bottom of the page and you'll see that now you can respond to topics.

Back To Top

Editing your profile

Once logged in, you can change your password, email or name by clicking on the "Edit Profile" button located at the upper-right corner of your screen, Clicking this button will display the user's properties available for modification, change them as desired and click the "Update" button to save your changes, or click on the "Cancel" button to return without saving. Note: Passwords are stored encrypted and cannot be retrieved, not even by the administrator, in the event that you forget your password, contact the administrator, which will chamge your password to some temporary one and will email it to You. Make sure you change it as soon as you can successfully log back in, to protect your privacy.

Back To Top

Language Settings

There are two types of language settings, one is the "presentation" language, and the other is the "topic language". It is very important to knoe the differences between both settings, since it is essential for spanish-speaking people. Presentation Language - This option sets the language of the errors, column titles, button labels, etc. Topic Display Language - This option sets the language under which the topics will be saved and pulled for viewing. Example: Supose that you are a spanish-speaking individual, but you also read and write in english, your "suggested" settings would be presentation in spanish and topics display language in engish. It is important to note that if your Topic Display Language is set to spanish and you Add a new topic, that topic will only be seen to anybody that has the Topic Display Language set to spanish. Responding to an already created topic will "inherit" the Parent topic's language settings, so Topic Display Language is applicable to New Postings only. Most english-speaker users will ignore this settings and use the default us/en language settings for both presentation and topic display.

Back To Top

Subscriptions

Subscriptions allows the user to be informed via email when a thread is changed. You can Subscribe/Unsubscribe from any Topic thread by viewing the Topic and selecting Unsubscribe or Subscribe Link at the top of the screen. In Addition, the user can manage her/his subscriptions from the Edit Profile button.

Back To Top

Post a new Topic

Once logged in the system, locate the link labeled Add New Topic located towards the top-left section of your screen, click the link and add the topic title and content, click the "Add" button to save your newly created topic, click on the Bold Topic checkbox to make your title stand out on the main topic display page. Important Note: Currently, only Administrators can "edit" topics, so be careful with your posting, once submitted, only an email to the administrator will allow you to change any information you previously posted.

Back To Top

Respond to a Topic

Once logged in the system, locate the Topic (Post) You want to respond to, and click on its title (to open the thread page), once you are in that page, locateh the link labeled Add Reply and click on it, or go towards the end of the page, and locate the Add Reply form window, It will already have the date and your username, ready for you to add a comment or response to the thread. When You are ready responding, click on the "Add" button, and then a confirmation window will pop up showing your entire message and it will ask You if you are ready to post your reply. Select the "Ok" button if you are satisfied with your message, or click on the "Cancel" button to return and make changes or corrections. After You successfully have added a reply, you will be returned to the same page You were before, and You will see the reply You've just added into the thread list.

Back To Top

Editing a Topic

The current version of the forums does not support editing of posted messages (except Administrators), in order to prevent imporper use or misleading postings by the user, however, future versions of the program may have this feature incorporated.

Back To Top

Search for Topics

Once inside a Forum, you can search for a title or content of any postings, by clicking the link labaled Search Forum link, or by manuall clicking on the Search Forum text area located at the bottom-right of your screen, type in a word, sentence or words and the system will perform a search on both titles and contents to find a match. If a match is found, then a list of topics will be returned, your search match will be highlighted for easier preview, however the word will be highlighted only if it matches EXACTLY the word typed, even though the actual search is case-insensitive.

Back To Top

Special Formatting Codes

• [b][/b] - Bold - [b]Hello[/b] will generate Hello
• [i][/i] - Italic - [i]Hello[/i] will generate Hello
• [big][/big] - Big Font, [big]Hello[/big] will generate Hello
• [img][/img] - View Image - Will generate necessary code to display an external image. Example: [img]http://yoursite.com/folder/image.png[/img]
• [url][/url] - URL link - Will create a link. Example: [url=http://yoursite.com/page.html urltitle=URL Title][/url]

  You can also combine the codes, for instance, "[b]Hi there, [i]sexy[/i][/b]" is valid, and will produce "Hi there, sexy.

  Starting with version 0.0.15-beta, a wizard is provided that allows the user to input these codes via a friendly-interface that is located below the emoticons section of the Add/Reply sections. Just click on any of the available links and a pop-up window will show asking the user the necessary information that will be used to "construct" the final html code.

  Back To Top

  Contacting another Member

  Any reistered member of the forums can contact another member via the internal email system of the forums. You can now select a member and send him/her a message, by clicking on the User List link located at the top left of the main forums page; upon selecting this link, the member is presented with a list sorted by member id. By clicking on a member ID, the user can send him/her an email. Note that the intended receiver must have his/her email settings set to allow to receive messages, otherwise the forum system will warn about it and the user will not be able to send a message to that specific user.

  Back To Top

  Contacting the Administrator

  In the event that the user needs to contact the administrator, a link has been provided in which the user can send a message to Administrator, and it can be an anonymous one. Any user can send a message to Admin, regardless on whether the user has logged in the system already or not. This could change in the future.

  Back To Top

  ADMINISTRATOR'S GUIDE

  This section is intended for the manager of the site, a person who will be in charge of all the parameters and policies of the system, and the responsible for managing forums, topics, users and global settings.

  Back To Top

  Manage Forums

  From inside a forum, clich on the Admin this forum link located at the top-left section of the screen, from the main administrative page, locate the link that is labeled Back to Main Admin Page. The options relevant to managing Forums in that page are:

  • Edit (Link), click this link to change either the forum's title, or description, this information is what the user sees when she arrives to the main forums page.
  • Any Forum Title (Link) - Click on any forum's title to enter the Topic administration page, where you can Manage Topics for that forum. Note that this is the only way to "go back" to the regular forum view, if you do not understand that now, just use the system for a while, you'll see what I mean :)
  • Delete Selected Forums - Understand what it deleted: everything. in that forum, all topics, entries, forum itself, todo. A future version will have a confirmation message, right now it does not have one!. You've been warned.
  • Add New forum (Link) - Use this link to create a new forum, the system will automatically assign a random 12-digit ID (via python random() module), so you do not have to worry about that, just supply the title and the forum description, and you should be set.

  Back To Top

  Manage Topics

  From inside a forum, click on the Admin this forum link located at the top-left section of the screen. Important information regarding children and parent topics is displayed in the main admin index page, read it and understand it.

  Available options in the page are:

  • Add Parent Topic - Has the same function as Add new Topic from the regular forum page, it adds a parent topic.
  • Parent Topics - A parent topic is an objece that contains several properties that children topics do not use, for example, these objects have the parent_flag internal property set, so the system recognizes which are which. See the actual class instance to view all object's properties.
  • Children Topics - A children topic will always "depend" on a parent object, these objects have the parent_id attributer set, so the system knows who they depend from. See the actual class instance to view all object's properties.
  • Back to Regular forum View - Switches to the regular user-oriented interface, sort of the "Back to Main Topic".
  • Back to Main Admin View - Sort of misleading, if coming to the admin page via the regular forum, then the "Back.." word is irrelevant, this link will take you to a section of the administrator to allow other administrative tasks such as managing users, managing topics and other functions, which are explained in their respective sections in this manual.
  • Language Setting - Same as the user's Language Settings section.
  • Delete Selected Topics (Button) - Got to understand what this button "e;deletes"es;, if a Parent topic is checked and deleted, ALL its children topics are deleted as well, regardless if all or some of its children are already selected. If you select one or more child topics from a Parent topic, only the selected children topics are actually deleted, this is clear enough.

  Click on any link of any topic (either parent or children), you will be able to change all available topic's parameters from that screen

  Back To Top

  Manage Users

  From inside a forum, click on the Admin this Forum link located at the top-left section of the screen, from the main administrative page, locate the link that is labeled Back to Main Admin Page. The options relevant to managing users in that page are:

  • Manage Users (Link) - Click on this link to view a listing of all users in the system, click on the user's username to change any of the user's registration information, click on the user's email (if available) to send the user an email, check any user's checkbox and click on the delete button to remove the user from the system. Note that the user's postings will be left intact, but the link to the user's email from the postings that the user placed (if any) will be removed

  When you are ready to "go back" (whatever that would mean to You at that point), and you are in the main forum (not topic) administration page (the page that shows the Manage Users link), in order to view a forum you must select a forum (to administer) and from there you can select the link Back to Regular forum View to resume "normal" operations.

  Back To Top

  Manage Pagination

  From inside a forum, click on the Admin this Forum link located at the top-left section of the screen, from the main administrative page, locate the link that is labeled Back to Main Admin Page. The options relevant to managing pagination in that page are:

  • Change Pagination (Link) - Select this link to change the system-wide default number of topics to show per page inside a forum, if more parent topics are available, "pagination" links will be shown in the main topic view page.

  Back To Top

  Permissions & Security

  This system relies on Zope's native security implementation. most of the methods and scripts' security settings have been updated accordingly.
  Actors: There are THREE main security ROLES (actors) in the system:

  • Anonymous User: This person can browse the entire site but he/she cannot add or sespond any topics in the system, the casual user.
  • user: This person is someone that registered into the system, he/she has a username and password and logs in the site with them, this actor can browse the site, add and respond to topics only.
  • SysAdmin: "Administrative" role, this user has complete control over the system, can do the same as the above two roles, plus he/she can manage (add/edit/remove) users, forums, topics and global system settings.

  Back To Top

  INSTALLATION GUIDE

  fcForum is composed of TWO main modules, a ZClass-based Object which defines the "topic" object, and a presentation layer, which contain all the interfaces between the system and the user/administrator. Next, I define all the objects used in this system:

  • fcForumObject.zexp - Simple ZClass containing the definition of a topic, the file fcForumObject.zexp must be imported in the Zope Product Folder before anyting else.
  • forum.zexp - Folder object containing all the presentation and the interface layer, you need to import this file in any place of your zope hierarchy, for the sake of all references, I will assume you will import it in your root folder, which will "insert" a forum folder. The Objects used inside the forum folder are:
  • Main forum folder. contains a property called forum_base which contain the name of the "root" folder of the forums, this will allow You to change the name of the "forum" to something else and by changing this property to match the ID of the folder, the entire program will know where everything is located
  • fcforum Folder. You must leave this folder intact, (i.e. do not rename, etc), this folder contains several properties that are considered system-wide, You can change them manually or via the UI, in this folder's properties You can set the version of the product, the title and the "topics-per-page" properties.
  • Python Scripts. Low-level functions such as adding objects, modifying properties of the ZClass, etc, etc.
  • DTML Methods. Contain all the presentation layer (User Interfase)
  • Standard Zope Folder Objects (Inside fcforum folder). Used as containers for Forums, they contain the textarea property fdesc, which in turn, contains the "brief" description of the forum, everytime you create a "forum" through the UI, this property is created as well.
  • fcForumObject (instances). Inside the forum containers, you'll find these objects, I set up a "properties" method so You (the Manager) can modify the object properties via the manage interface, of course you have total control over them via the UI

  You will ALSO need

  • Andrew Milton's exUserFolder Zope Product, installation is really easy and there's plenty of documentation for its installation, fcForum uses an instance of the acl_users object from this product, and it is (and should be left alone) located in the forum's root section.

  Putting it all together
  For a successfull installation, you should follow the procedures in the order they are presented below:

  1. Stop Zope
  2. Install exUserFolder in your Products folder
  3. Copy fcForumObject.zexp and forum_dev.zexp to your "import" folder
  4. Copy striphtml.py to your "Extensions" folder
  5. Start Zope
  6. Import fcForumObject.zexp in your Products folder (from within the Zope interface, that is).
  7. Import forum_dev.zexp in your root folder in zope (from within the interface)
  8. Assuming you have your test installation running locally, access the system via http://localhost:8080/forum/index_html

  Email Configuration

  Email configuration is straightforward, however, the user MUST have knowledge to edit zope pages via the management interface in order to change the mail server that will be in charge of managing email sending. To do so, manage the /forum_dev folder (or the main folder where the forum system is located), then, locate the "MailHost" object, select it and change to reflect your email server, save it and you should be set.

  fcForum System will always send email on behalf of the forum "administrator" account, so it is a good idea to change the administrator email to the "real" administrator, otherwise the server which will be handling the emails might think the system administrator is trying to relay (read: spam) emails and won't allow the operation. fcForums is set in a way, that any email errors will be ignored by the system.

  Username and Password For SysAdmin is: administrator/administrator (Do not forget to change it to something else). Use this login to "grant" SysAdmin "rights" (Role) to your beloved ones

  Back To Top

  Credits

  Chris "Coach" Klein, CFO at CodeIt Computing for giving me the time to write this product, Tim Kelly, for the "external" QA needed for this job.

  Back To Top

  License

  This product is governed by the Zope Public License (ZPL) 2.0.
  Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions in source code must retain the above copyright notice, this list of conditions, and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. The name Zope Corporation (tm) must not be used to endorse or promote products derived from this software without prior written permission from Zope Corporation.
  4. The right to distribute this software or to use it for any purpose does not give you the right to use Servicemarks (sm) or Trademarks (tm) of Zope Corporation. Use of them is covered in a separate agreement (see http://www.zope.com/Marks).
  5. If any files are modified, you must cause the modified files to carry prominent notices stating that you changed the files and the date of any change.

  Back To Top

  Disclaimer

  THIS SOFTWARE IS PROVIDED BY CODEIT COMPUTING ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL CODEIT COMPUTING OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

  Back To Top

  Acknowledgements

  Thanks go to Casey Duncan for his excellent ExternalEditor Zope Product, when you work mostly on Linux Mozilla, that nifty product saves a lot of trouble. Also to Andrew Milton for his ExUserFolder (XUF) product, that works wonders on these type of systems.

  Back To Top

  
  

  Main Page | User's Manual