Log in
HispaZope
Discusión sobre Zope
Zopix: live CD para Zoperos
Forgot your password?
The Following Manual has not been updated to Version 2.0.0a, it is updated for 1.1.x versions and below, although 90% of the current manual is correct, there are many new features that need to be updated in this manual, documentation for 2.0.x series will be completed shortly.
Table Of Contents
- Product Description
- Why This Product?
- Features
- USER'S GUIDE
- Browsing the Forums
- Registering (Sign-Up)
- Logging in / Logging out
- Editing your profile
- Language settings
- Subscriptions
- Post a new Topic
- Respond to a Topic
- Editing a Topic
- Search for Topics
- Special Formatting Codes
- Contacting another Member
- Contacting the Administrator
- ADMINISTRATOR'S GUIDE
- Manage Forums
- Manage Topics
- Manage Users
- Pagination
- Email Password Upon Signup
- Permissions & Security
- INSTALLATION GUIDE (Technical notes for the enlightened zopista)
- Credits
- License
- Disclaimer
- 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.
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.
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
- 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.
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
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.
Public Forums are forums accessible to all visitors, regardless on whether they are logged in the system or not, even though public forums can be seen by anybody, only registered members can post new messages to them.
Member-only forums are forums which are "hidden" for the user. This type of forums appear in the forum list (main index) page upon logging in the system with a valid username and passwords. A registered and logged-in user can see both Public and Member-Only forums, and can post messages to them also.
Forum Admin Forums are available ONLY to Forum Administrators, noone but them can see them and they are intended to be used to discuss system related issues amongst Administrators.
Starting with version 1.1.5, each topic has a "topics expansion" toggle link, marked with the legend "+/-" next to each topic title. By clicking on it, the entire topic thread is "expanded", click on the link again to "collapse". Please note that the expanded thread shows a preview of the thread, although it will show all the topic replies, only a preview of each reply (and without formatting) will be shown. This will be sufficient on most instances, but thr user/member is encouraged to enter the actual topic thread display page by clicking on the main topic title, as it has been in previous versions.
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. soulcrusher, 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. Depending on the forum policies, users may not be required to specify his/her own password upon registering, the system will rather email the password to the user's specified email address, then the user can change it to his/her likes once logged into the system with this password.
After registration, 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.
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.
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.
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.
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.
Once logged into 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. Starting on version 1.1.5, a new "Preview" button has been added. This will allow the user to view the posting before submitting it, keeping all the formatting and pseudo-code intact. 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.
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. Starting with version 1.1.5, a new "Preview" button has been added. This will allow the user to view the posting before submitting it, keeping all the formatting and pseudo-code intact. 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. Optionally, you may reply to a specific posting in a topic thread, by selecting the "Quote w/Reply ]" link next to each topic thread, this will add the original contents of the intended topic inside the response textarea, and will enclose it between block quotes, which have it's own internal formatting. It is highly suggested that you "preview" your message when using this "Quote w/Reply ]" option, for clarification purposes.
The current version of the forums does not support editing of posted messages (except Administrators), in order to prevent improper use or misleading postings by the user, however, future versions of the program may have this feature incorporated.
Once inside a Forum, you can search for content on 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. Currently, the system looks at the "topic creator", "topic modifier", the "topic title", and the "content" attributes of every posting for search purposes.
Due to security reasons, html and javascript code inside messages is not permitted, the content parser will remove any html code you place in either your topic title ot the contents of the topic. However, a pseudo-html sub-set of instructions are available to the user in case You want your message to "stand out", the codes currently available are:
- [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.
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.
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.
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.
Starting on version 1.1.5, all global program settings (attributes) are contained in the special system account, which is located inside the Members folder, it is a folder container and has all the available properties in the system.
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 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.
- Forum Type - Forum type refers to a new feature added in version 1.1.4, it shows the tyoe of forums listed in the administration listing, possible values are: Public, Members and Admins. The administrator can change this values by clicking on the "Edit" link in the Admin Forum Listing.
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
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.
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.
Click on the link, then select the checkbox to prevent the new users to be shown a password/confirmation box upon registering, and have the system automatically email a pseudo-password to his/her email specified. Uncheck the box to allow any new user to be able to select a password and thus, log in at the same time.
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.
- Member: 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.
- Reviewer: "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.
- Manager: Manages is the superuser role and for functionality purposes, it has the same permissions as the Reviewer Actor.
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_dev folder. The Objects used inside the forum_dev folder are:
- fcForum Folder. You must leave this folder intact, (i.e. do not rename, etc), this folder is used throughout the system to reference absolute locations of different objects, it the "compass" of the system.
- Python Scripts. Low-level functions such as adding objects, modifying properties of the ZClass, etc, etc.
- ZPT Pages. Contain all the presentation layer (User Interfase)
- Standard Zope Folder Objects (Inside fcforum folder). Used as containers for Forums, they contain the textarea property
- 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
- Shane Hathaway's CookieCrumbler Zope Product. CookieCrumbler is Zope product that enables cookie-based authentication, even if the user folder doesn't support cookies. It is useful for providing a friendlier authentication process. Just unzip the contents of the archive in yur Products Folder of your Zope installation and you're set.
Putting it all together
For a successfull installation, you should follow
the procedures in the order they are presented below:
- Stop Zope
- Unzip CookieCrumbler in your Products folder
- Copy fcForumObject.zexp and forum_dev.zexp to your "import" folder
- Copy striphtml.py to your "Extensions" folder
- Start Zope
- Import fcForumObject.zexp in your Products folder (from within the Zope interface, that is).
- Import forum_dev.zexp in your root folder in zope (from within the interface)
- Assuming you have your test installation running locally, access the system via http://localhost:8080/forum_dev/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 Reviewer is: administrator/administrator (Do not forget to change it to something else). Use this login to "grant" Reviewer "rights" (Role) to your beloved ones
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.
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:
- Redistributions in source code must retain the above copyright notice, this list of conditions, and the following disclaimer.
- 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.
- 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.
- 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).
- 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.
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.
Acknowledgements
Shane Hathaway for his CookieCrumbler Product. CookieCrumbler is currently used on Plone and CMF and most likely will become the de-facto standard in zope form-based authentication processes.
[ Main Page | User's Manual ]