To install the CHC forum plugin, begin by inserting the plugin on a page. Currently, there are a couple place to where the forum can be configured. Nearly all configuration for the forum is done using the flexform in the plugin record. Some look and feel values may also be configured via typoscript, although the defaults should be suitable for most users. Major changes to the look and feel of the forum should be done by modifying the template files in the extension pi1/templates directory.
To install the CHC forum plugin, begin by inserting the plugin on a page. The next thing you need to do is tell the forum where to store it's records. There are two ways to do this. The RECOMMENDED way is to use the "starting point" field of the forum plugin record. You can also use the general records storage page (GRSP) field in the page header of the page containing the forum, although the forum will use starting point before GRSP if it's available.
TIP: To set the general records storage page value, click on the icon for the page containing the forum in the pagetree. Select "edit page header" from the clickmenu. This is where you set the general record storage page value -- in the header of the page containing the forum. You can set it to a folder, or even to the forum itself.
All regular configuration for the forum is done via the plugin's flexform. This is also a change from previous versions; in versions prior to 0.5.0, the configuration was done in the backend module. This is no longer the case. When you create an instance of the plugin, you can set the following values in the flexform. To access the flexform, you need to edit the forum plugin record. The flexform will be midway down the page. The tabs at the top represent the different configuration categories. Save the plugin record to finalize the changes.
Required Settings:
Frontend user storage folder PID: The forum needs to know where to look for frontend user records, so be sure to enter the PID of the frontend user storage folder (you can find out what the pid is by holding the mouse pointer over the icon of the user storage folder in the page tree listing).
Profile Settings:
Disable user profiles: Check this box to prevent users from viewing profiles (their own and other users) and editing their own profile.
Disable user imags: Unless this is checked, the forum will display the image in the “image” field of an author's frontend user account. Check this box to prevent the forum from displaying user images. Note: if cwt_community integration is enabled, this setting will not be observed.
Disable user image uploads: If you check this, the forum will still display user images, but users will not be alllowed to upload new images. Note: if cwt_community integration is enabled, this setting will not be observed.
Disable email addresses: Checking this box will stop the forum from displaying user email addresses in user profiles (and in the profile edit view).
Disable website field: Check this box to disable the website field in user profiles.
Disable AIM field: Check this box to disable the aim field in user profiles.
Disable Yahoo field: Check this box to disable the yahoo field in user profiles.
Disable MSN field: Check this box to disable the MSN field in user profiles.
Custom IM option: Not wanting to be too ameri-centric, I've added the option for an additional IM field in user profiles. Just enter the name here and users will have the option of adding a value in their profile for this field, and it will also be displayed in user posts if the user has entered a screen name (as is the case with the other IM fields)
Alternate User Image Field: If you want the forum to display pictures from a field other than the “image” field in fe_users (the alternate field must, however, be in the fe_users table), which might be the case if you want to display photos from a custom extension, enter the name of the field here.
Alternate User Image Relative Path: Enter the path, relative from index.php, to the folder where you store your alternate image files. If you're using cwt_community integration, this path will be set automatically.
Post Settings:
Author Email is Optional: Check this field to make the email field on the post form an optional field (default: required).
Display Author Username instead of Full Name: check this to force the forum to use usernames instead of full names.
Allow post ratings: if you check this, the post rating form will appear on the bottom of all posts (see below). This form allows users to rate the post and the forum will display the average rating for each post. Users may change their rating, but the forum records the IP address of the rater and will not allow the same IP to rate the same post more than once, so the results should be pretty fair. See the typoscript configuration options for more information on how to configure the look and feel of the ratings box.
Appearance Settings:
Custom Template Path: If you would like to use your own templates instead of the ones that come with the CHC forum, you can set a path to them here. The path should be relative to the root of your typo3 installation (that is, assume that you're starting at index.php). So, if you put the templates in fileadmin, for example, the path would be “fileadmin/templates/” -- remember to add a slash to the end of the path. If you want to use the templates that come with the forum, leave this field blank.
Extension for template images (default: png): There are a number of images that come bundled with the chc_forum extension (buttons, for the most part). By default, the forum is set to use .png files because they have better transparency. However, there are problems with internet explorer and png images, and you may want to use .gif versions of the images instead. The forum comes with both .png and .gif versions -- to switch to gifs, simple set this field to "gif".
Forum Title: Enter the title of your forum, which will be displayed at the top of every page.
# of posts required for a thread to be considered "hot" (default: 20): When a thread is hot, a red folder icon will be displayed next to it:
- Last post info subject field trim (max chars): Sometimes long subjects can mess up the layout of the category and conference view. Set this value to trim subject lines in the conference view to X number of characters.
Number of posts to display per page: This number tells the forum how many posts to list on each page (default: 10).
Number of threads to display per page: This number tells the forum how many threads to list while viewing a conference (default: 20).
Date format: Set how you want the date to be displayed in the forum using the strftime format string (default is %b %d %Y. For more details, see http://php.net/manual/en/function.strftime.php).
Time format: Set how you want the time to be displayed in the forum using the strftime format string (default is %I:%M %p. For more details, see http://php.net/manual/en/function.strftime.php).
Sort conferences by: Set the method for sorting conferences. You can sort them alphabetically, reverse alphabetically, or by their order in the backend list module (which uses the sort field).
Sort categories by: Same as the previous configuration, only for categories.
Sort threads by: sort threads by last post date or creation date (crdate) either ascending or descending.
Sort posts by: sort posts by creation date ascending or descending.
Disable User LIst View: The userlist is still in the alpha stages, so you may want to disable it. Check this box to do so.
Emoticons:
Disable emoticons: Check this to remove emoticons from posts and to prevent the forum from parsing posts for emoticons code.
Emoticons path: This is the path to the folder containing the emoticon images. The default is EXT:pi1/templates/img/emoticons
Custom emoticons: The default emoticons are listed below. To add your own emoticons, enter a new code / file name pair on each line of this field. For example, one could enter ":frown:,frown.gif" to add a frown emoticon to the forum
Site URL: When the mailer sends out emails to users, it includes a link back to the parent thread. To generate the link correctly, the forum needs to know the URL of your website, so enter it here.
Merge default and custom emoticons: if this is checked, the forum will use the default emoticons as well as any custom emoticons (see above). If it is not checked, and custom emoticons are present, the forum will only use the custom emoticons.
Mailer Settings:
Site URL: When the mailer sends out emails to users, it includes a link back to the parent thread. To generate the link correctly, the forum needs to know the URL of your website, so enter it here.
From email address: This is the "from" address on all messages sent by the forum mailer
Disable Mailer: If you'd like to disable the mailer, check this box. This will also remove the mailer preference section from the user profile (default: enabled);.
Disable Thread Monitoring: Users are currently allowed to monitor both threads and conferences via email. By disabling this, users are only allowed to follow conferences via email.
Mailer template: This template will determine what the messages sent by the mailer look like. Enter the message as you want it to appear, and be sure to include the following markers:
{author_name} = the name of the author of the post.
{conference} = the name of the conference in which the post was posted.
{thread} = the subject of the thread in which the post was posted.
{text} = the body of the message.
{link} = the link back to the thread in which the post was posted.
Maintenance Settings:
Age: This is the maximum number of days old that a message can be before it will be deleted when you clean the forum tables. So, for example, if you set this to 100, the forum will automatically delete all posts old than 100 days everytime it cleans the tables. Tables are cleaned any time you add, delete, or modify a record using the backend module, or when you select “clean forum tables” from the backend module main drop-down menu. To turn off pruning, set this to 0 (default: 0).
Security Settings:
Enter a secret word: the forum uses a secret word to generate secure hashes. This should be a random string; something that is hard to guess.
Only show user list to logged in users: Check this to only show logged in users the site's user list.
Max user imag size: Set the maximum file size for the image files that users can upload when they edit their profile. The number is in Kb (default: 100).
Max attachment size: Set the maximum size for attachments, in Kb (default: 100).
Allowed file types: A comma separated list of allowed extensions for uploaded files. Do not add any executable extensions here, and do not allow html or php files, since doing so poses a serious security risk. These files are stored in /uploads/tx_chcforum, so they aren't secure. Users could, in theory, enter the URL for an attachment that was uploaded in a conference to which they did not have access. And, since these files are under the web root, they can be viewed (or executed) in a browser, which is why you don't want to allow html, php, cgi files, etc. (default is .doc, .png, .jpg, .gif, .xls, .ppt).
Allowed mime types: A comma separated list of allowed mime types for uploaded files. When a file is uploaded, the forum checks the extension to make sure it belongs to the list of allowed file types, then it checks the mime type (reported by the browser) as a further security check. For an attachment to be considered valid, it must satisfy both these requirements (defailt is word documents, image files, powerpoint and excel files).
3rd Party Extensions:
Rather than re-invent the wheel, we think that it's easier to integrate existing extensions into chc_forum when appropriate. Let us know if you have an idea for an integration between chc_forum and another extension!
Enable cwt_community integration: check this button to enable cwt_community integration. You must have cwt_community (0.8.2 or later) installed for this to work (see the section on cwt_community integration, below).
At this point, all of the forum configuration should be done. The next step is to begin setting up the forum categories, conferences and groups.
Access to the forum is set on a category by category basis and a conference by conference basis. Category access permissions uses the same techniques that one uses to restrict access to a page in typo3 - in other words, you can restrict a category to a single group, or leave it open to all users. You may also assign access to categories using forum groups. Permissions in the chc_forum are always inherited, so if a user does not have access to a category, he/she will also not have accsess to conferences that belong to that category. The forum will first check if a user has access to the frontend group assigned to the category. Then, it will check the user against any frontend groups (the user only needs to authenticate for one forum-group to access the category – not all of them). So, in order to authenticate for a cateogry, a user needs to belong to the frontend group assigned to it AND any one of the forum groups assigned to it.
Forum groups make up the core of the CHC forum's method for handling access to conferences. Conferences can be set to public, which means that they can be accessed by any and all users, including users that aren't logged in at all (anonymous or guest users) or access can be restricted to one or more forum groups. Each forum group is composed of one or more frontend groups and/or one or more frontend users. For a user to belong to a forum group, she must belong to all the frontend groups that are included in that forum group record, or she must be one of the frontend users listed in the forum group record. So, for example, if a forum group was composed of group X, group Y, and user Z, a user would EITHER have to belong to frontend groups X and Y OR be user Z. Access to a conference can be granted to one or more forum groups - in order for a user to access a conference, she must belong to only one of the forum groups.
Unless all of your conferences are going to be public, you should begin by setting up any forum groups that you anticipate needing. This should be done via the backend module (although it could also be done via the list module, if you find that approach easier). To create a new forum group, select “manage forum groups” from the chc_forum backend module and then select “add a forum group”. Use the ctrl key (apple key on macs) to select more than one group or user from the menus.
If you don't set any access to a conference - if you don't assign any forum groups and you don't allow anonymous access, then the conference will be available to any logged in user, but not to anonymous (not logged in) users.
Once you've set up your forumgroups (you can always add more later), you should set up one or more categories. Categories and conferences have a parent / child relationship, and all conferences must belong to a category in order for them to be displayed, which is why you should set up categories before setting up your conferences. Again, use the backend module to do this. Select “manage categories” from the drop-down menu and then choose “add a category”. You can limit category access to a frontend group and one or more forum-groups, or you may leave it open to all groups and manage access in the conferences. When you're done filling out the form, press submit.
Set up one or more conferences (either using the list module or the forum module). Assign forum group(s) to the conference to limit access, or give read / write access to anonymous (not logged in) users. You can also select one or more users to act as moderators for this conference - moderators have the ability to delete and edit other users posts. There is also the option of selecting which forumgroups can attach files to posts. You can select multiple groups and users here by holding down ctrl (windows) or command (mac) while you click on them.
For more information on file attachments, see step 1.
