EXT: CHC Forum¶

Sponsoring the CHC Forum¶

Almost all development for the CHC forum is done by Zach Davis and Lucas Thurston of Cast Iron Coding . We are committed to continuing development of the forum as a way of giving back to the TYPO3 community. We hope you'll consider us for your typo3 development projects.

A few users have been kind enough sponsor the development of the forum with small contributions or with code additions. If you've used the forum in one of your sites, or for a client, please consider making a small donation to the developer or to Kasper, the guy who makes it all possible.

Many thanks to those of you who have made donations, given gifts, or contributed a significant amount of time to the development of the forum:

Gregory Remington, mediatech.net Vincent Picou, Dassault Systems Ben Van 't Ende, netcreators.nl Sacha Vorbeck, unlimited-vision.net

Thanks as well to those of you who have reported bugs (especially Janno Schouwenburg for his help bug testing), translated the forum into other languages, sent me patches, made suggestions, and been generally supportive! Please report any bugs on the TYPO3 bugtracker ( http://bugs.typo3.org ) and join the forum newsgroup ( news://news.netfielders.de/typo3.projects.forum) to discuss forum development.

What does it do?¶

The CHC Forum is a frontend plugin that adds an integrated discussion board to your website. This extension was written to be used in an academic setting, although word has it it's being used in other environments as well. The following features are currently included in the extension:

• Threaded discussion board: the forum is organized in terms of categories, conferences, threads, and posts.
• Backend Module: use the backend module to configure the forum, manage categories and conferences, setup forum usergroups, and run maintenance on forum tables.
• Flexible Permissions: the CHC Forum adds an access management layer on top of typo3's page permission system. Conferences can be completely public, or restricted to one or more frontend groups or users (or a combination of the two). This flexible system means that a conference can be set up for anywhere from a handful of users to all users on a site. It is also possible to grant anonymous read and/or post access.
• Community Features: includes an interface that allows users to edit their user profile to include a website address, IM screen names (including custom messaging services defined by the forum admin), a photograph (which is displayed next to their posts), and their preferences for the forum mailer. These community features can be disabled, should you prefer a trimmed-down forum. The forum can also output a searchable user list, although this particular feature is still in development. I plan to add private messages and the ability to email users in the next version.
• Internal Templating System: the CHC forum uses a templating class to separatelogic from presentation. In theory, users should be able to “skin” the forum to server their needs. Furthermore, thanks to the hard work of Ben Van 't Ende, who generously revised the forum stylesheet and default templates, the forum output validates as XHTML.
• New Post Tracking: the CHC forum tracks which posts users have read and includes notices of new posts when users return to the forum.
• Search Interface: users can search messages in any or all conferences and/or categories; searches can be limited by author username.
• Receive New Posts Via Email: users can opt to receive new posts via email. The CHC forum includes a php mailer script which can be set to run via a cron job. This script will mail copies of new posts (and a reply link) to users who have asked to receive new posts via email (configurable on a conference by conference basis)
• Post features: the CHC forum incorporates a modified version of PhpBB's post form, which allows users to quote previous messages, include imagesand links, and apply some formatting to post text (bold, italic, underline).
• Moderator Functions: one or more users can be assigned to “moderate” a conference, which gives these users the ability to edit and delete other users' messages.
• Ability to include attachments: groups of users can be given the ability to attach files to conferences. Files are checked against a list of allowed extensions and mime types.
• Auto-maintenance: using the back end module, it is possible to quickly repair any inconsistencies in the forum tables, which might happen if records are deleted in the backend.
• Pruning: the forum can be configured to delete all posts that are older than a user-defined number of days.
• As far as I know this forum works in languages other than english and it is compatible with simulate static documents. Furthermore, you should be able to have more than one forum on a site.
• cwt_community integration adds buddy lists, private messaging, and a user list to the forum.

Screenshots¶

The CHC forum opens with a view of all categories and child conferences to which the user has access:

When the user clicks on a conference link, the forum returns a list of threads that belong to that conference. The most recently updated threads appear at the top of the list, as well as the thread starter (author) and information about the most recent reply in the thread. The post form will also be displayed on this page (assuming the user has post access to the conference), allowing the user to create a new thread.

Threads are composed of individual posts, which look like the image below. Note that users can include some HTML formatting in their posts, as well as a picture (inserted automatically). Posts can also contain links to web pagesand images.

Users can also edit their profiles to include IM account information, website URL, email address, mailer preferences, and a picture:

As of version 1.3, it is possible to integrate the cwt_community extension with chc_forum. Enabling cwt_community integration will make it possible for your users to maintain a buddy list:

With cwt_community integration, users can also send private messages to one another:

The forum also boasts advanced search functionality:

The CHC forum also installs a backend module for managing categories, conferences, and forum access groups (some people like to use this custom module, other people prefer to use the standard typo3 list view -- you choose!):

Posting Messages¶

The post form is based off of (and uses some of the code from) the PhpBB post form, and it works in roughly the same way. To post to a conference, you must belong to one of the forum groups assigned to that conference (see below) or the conference must be set to allow anonymous post access.

The post form looks like this:

The header at the top of the form (where it says "start new thread" or "reply to this thread") will explain what this form does. In this case, submitting this form will begin a new thread because we're viewing a conference. If we were viewing a thread, the header would change, informing us that the form is now a reply form. In any case, submitting this form will add a new post to the forum.

If you are logged in to the site, the name and email fields will be automatically filled in. If you are replying, the subject field will also be filled in, although you may choose to change it. If you are not logged in, and the administrator has allowed anonymous access to this form, you will need to enter your name and email address. It is possible for the forum administrator to make the email field optional, in which case you won't have to enter one. If it is required, however, and you fail to enter an address, you will be prompted for one before posting the message.

While composing your message, you may apply formatting to the text using the buttons above. If you are using Mozilla or Internet Explorer, you can simply select a segment of text and click on one of the buttons to apply formatting to it. You can also click on a formatting button to open a tag where the cursor is located, and then click on it again to close the tag after you've finished typing. Alternately, the “close tags” button will close all open tags. To receive an example of how the tags should be used, simply position the cursor over the button and consult the text in the help field below the buttons. There are also keyboard shortcuts, which can be used to quickly open and close tags. The formatting buttons seen in the above capture of the post form are as follows: bold, italics, underline, colored text, quoted text, insert image, insert URL, and close all tags.

Users can also include an image that is hosted online somewhere by using the img tag. To use this tag, wrap the url of the image in [img] and [/img]. The forum will take care of the rest! The same formatting can be used to add a link to a post. For example, to link to typo3.org one could include either “[url]http:/typo3.org[/url]” or [url=http://typo3.org]The best CMS ever![/url]. The later format allows you to include a title for the link.

The quote tag is used to offset a section of text, and it gets automatically applied when you click on the quote button at the bottom of a post. To add an author to a quote tag, follow the same formatting that we saw with the URL tag: “[quote=author]quoted text here[/quote]”.

While the javascript used for this form seems to work well with most browsers, I've noticed that much of the functionality doesn't work with Safari. Safari seems unable to insert tags at the cursor position, for example. Any fixes for this would be much appreciated!

The javascript for these buttons is taken from the code for the phpBB post form more or less verbatim.

Once you've finished writing your message, press the “post message” button to submit it to the forum. If you'd like to see what your message will look like, you may preview it by pressing “preview message”. Doing this will bring up a preview of the post, which you can then edit and post or, if necessary, preview again.

User Configuration¶

Click on the edit profile link on the front page of the forum to configure your user account. The link is in the toolbar at the top of every page, although it will only show up if there is a logged in frontend user.

The image below shows the profile screen. The top part of the page (Contact Information and Forum Information) is what other users can see when they look at your profile. Beneath those two sections are a series of fields that allow you to edit your profile.

The options that can be set here include:

• Forum Mailer Preferences: If the admin has set up the forum mailer, then this section will probably be enabled (otherwise, it may not show up). Users can choose which conferences they want to follow via email. All the conferences to which a user has access will appear on this page. If the user checks a conference, all future posts in that conference will be sent to the user as an email. The message will contain the actual text of the post as well as a link back to the parent thread.
• User Image Upload: Users can upload an image of themselves here. The file will be stored in /uploads/pics (which is where the newlogin box extension stores images). The uploaded file must be either a gif or a jpeg file, and its size can never exceed 100k (the administrator can set the max size to less than 100k, if desired).
• IM Screen Names: Users can add / edit their instant messaging screen names here, making this information visible to other users who view their profile.
• Email: Users can update the email address for their frontend account.
• Web site: If the user has a website, it can be listed here.

After editing their account preferences, users should press submit to finalize the changes.

In some cases, forum administrators may choose to disable the user preferences functionality, in which case these options will not be accessible. If cwt_community integration is enabled, this page will look a bit different because it will include the account options bundled with cwt_community, in addition to teh forum mailer preferences and IM screen name options (assuming they have not been disabled).

Forum Moderation¶

Forum administrators can select one or more users to act as moderators of a conference. Moderators may hide and unhide threads and posts, lock threads, delete posts, and edit messages. If the forum administrator has assigned you as a conference moderator, you will see a button below each thread title in the conference view that allows you to hide the thread:

Clicking on the red button will set the thread to hidden. Once a thread is hidden, neither the thread nor any messages in the thread will be visible to regular users. The thread will, however, appear in the conference view for any moderators viewing the thread. Hidden threads will have a green button under the thread title. Clicking on the button will unhide the thread:

At the bottom of each message, moderators will have a few options:

As with threads, moderators may hide individual messages (making them invisible to all but other moderators). Moderators may also click on the delete button to delete a message (they will be asked to confirm the delete action before it's finalized), and they may also click on the edit button to edit the contents of a message.

Moderators also have the option of locking threads. Once a thread is locked, no new messages may be posted to the thread until it is unlocked. To lock a thread, simply click on the "lock thread" link while viewing the thread. If a thread is already locked, this link will change to "unlock thread."

Step 1: Set Forum Configuration¶

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 separatedlist of allowed extensions for uploaded files. Do not add any executable extensions here, and do not allow htmlor phpfiles, 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 separatedlist 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.

Step 2: Setup Forum 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.

Step 3: Setup Categories¶

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.

Step 4: Setup Conferences¶

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.

Setting up the mailer¶

The CHC Forum comes with a script that sends new messages to users who have opted to receive new posts via email. The mailer is not part of the extension itself because in some cases it may be sending hundreds or thousands of emails (depending on how many users you have in your forum) when a new message is posted, and users should have to sit their waiting while it runs. Therefore, your best bet is to have the mailer run on a regular basis via a cron job. If you have the CGI version of PHP installed (it's compiled as a standaloneapp rather than as an apache module), then you can execute it via cron as though you were executing it from the command line. If PHP is installed as an apache module, which is probably more likely, then you can execute it using the text based browser Lynx. In this case, the entry in crontab might look like this:

*/5 * * * * lynx -dump http://www.yourdomain.com/path/to/mailer.php

This would cause the mailer.php script to be executed every 5 minute. For more information on setting up PHP scripts as cron jobs, take a look at http://www.phpfreaks.com/tutorials/28.0.php

When the mailer is executed, it looks through the post table for all posts where sent_flag is set to 0, which is the default for all new posts. It then grabs the post information, and puts the message in its own queue. Once it's queued all the messages that need to be sent, it takes each message, one at a time, gets a list of recipients, and sends the emails using a pear bulk mailer, which is bundled in the extension.

In versions prior to 0.5.*, the mailer "from" address was set in the mailer.php file, which is at path_to_ext/chcforum/mailer/mailer.php. As of version 0.5.*, this setting has been abstracted from the mailer script and placed in the forum plugin flexform. This is also true for the message template. So, be sure to set the from address in the "mailer" section of the flexform. You'll also need to set the message template using the markers listed above (in the "Set Forum Configuration" section of the documentation). A sample template might look like this:

Posted by: {author_name}
Conference: {conference}
Thread: {thread}

{text}

This message was sent by the chc forum because you have opted to receive new posts via email.
{link}

You may also need to change the path to localconf variable, at line 11, depending on where you installed the extension. If you installed the extension locally (in the typo3conf directory), you shouldn't need to change this setting.

Changing the Look and Feel of the forum¶

Changing the look and feel of the forum isn't too difficult. The styles are located in the ext_typoscript_setup.txt file. If you want to modify them, just copy them into your template and change them according to your needs. Thanks to Ben van t'Ende, the colors for the forum have been taken out of the setup file and put into the ext_typoscript_constants.txt file. This means that you can quickly modify the forum color scheme via the typo3 backend. Simply click on the template module and select the template for your site. Choose the constant editor from the dropdown menu and select “CHC_FORUM” from the category drop-down menu. Almost all of the colors for the forum can be set here, allowing you to quickly fit the forum into your own site's design.

If you want to change the colors of the rounded buttons that appear on individual posts, you will need to modify the two files in chc_forum/pi1/img/. There are two files in this folder, btn_bkgrnd.gif and btn_bkgrnd_hov.gif, which are used for the button rollover effect. The text for these buttons is created dynamically by the forum, so changing the color of the buttons should be as easy as modifying the files in a graphic editor.

All of the HTML for the forum is located in chcforum/pi1/templates/. These files are HTML templates that get parsed with the tpower class (slightly modified version of TemplatePower - http://templatepower.codocad.com ). The markers are contained in '{ }' brackets, and it should be easy enough to modify these templates.

The best way to begin skinning the forum is to copy the contents of chcforum/pi1/templates to another location (somewhere in fileadmin is probably a good bet). Using the backend forum module, add the path to the new folder containing these templates to the forum configuration (see above, step 1 of forum administration). Once you've set the path to your template files, the forum will use these rather than the default ones. Now that you've moved the new template files out of the forum directory, you don't have to worry about your files getting written over each time you upgrade the forum. Modifying the templates should be rather self explanatory - you need to leave the block markers as they are (eg. <!-- START BLOCK : blockName --> CONTENT <!-- START BLOCK : blockName -->), and you should make sure that you don't leave out any of the markers for dynamic content (the sections that are surrounded with { and } ).

If you don't want to modify the templates, you should be able to change the look and feel dramatically by modifying the style sheet. I did my best to keep the templates sparse and rely on the style sheet for most, if not all, formatting.

If you come up with a great template or a fantastic set of styles, send me a copy and I'll see if I can include it in future releases. It would be nice to bundle some default skins with the forum.

The following table shows the purpose of each template file as well as the available markers in each template. Many template contain sub blocks that repeat in the template, which are signified by <!-- START BLOCK : name --> and <!-- END BLOCK : name -->. In the available markers column of the following table, the block name is signified by italic text. The "root" block is the master block in the template (not explicitly noted in the file). All content markers are surrounded by { and } -- for example: {header_title}.

Common Problems and Solutions¶

• 9 out of 10 problems have to do with not setting the general records storage page or starting point value correctly. You must set this value for the forum to work correctly -- set it by editing the "page header" of the page that contains the forum plugin -- set the "general records storage page" value to the page on which you want to store forum records.
• If the forum isn't working properly, try disabling caching for the page in which it resides. To do this, edit the header of the page and check the “no cache” option (right below the page title field).
• If the mailer isn't working, it might be because you've installed it globally rather than locally - that's fine, but you may need to change the path to localconf by editing the mailer.php file (there's a comment near the beginning of the file that explains what you need to change). Make sure you set up the template correctly in the forum flexform.
• Attachments not working? Having problems with the forum? Make sure that you've configured the forum correctly using the plugin flexform.
• Need to change the order of the text in some of the labels? Check out the typoscript setup for the forum.

((generated))¶

fcode_tpl.code_open¶

fcode_tpl.code_close¶

fcode_tpl.url¶

fcode_tpl.color_open¶

fcode_tpl.color_close¶

fcode_tpl.size_open¶

fcode_tpl.size_close¶

fcode_tpl.email¶

fcode_tpl.img¶

fcode_tpl.quote_open¶

fcode_tpl.quote_author¶

fcode_tpl.quote_close¶

posts.post_info_string.all_cats¶

posts.post_info_string.single_conf¶

single_conf.preview.form¶

single_thread.preview.form¶

rating.voteCountString.showString¶

rating.voteCountString.oneOrMore¶

rating.voteCountString.ifEmpty¶

rating.voteCountString.avgDecimals¶

rating.showEmpties¶

gpvars¶

gpvars.view=single_conf
gpvars.cat_uid=1
gpvars.conf_uid=2page.typeNum = 0

rating.imghtml¶

userImg¶

userImg {
        file.minW = 0
        file.maxW = 100
        file.maxH = 75
        file.minH = 75
}

cwtCommunity¶

plugin.tx_chcforum_pi1._CSS_DEFAULT_STYLE¶

Reporting Bugs, Recommending Features¶

All bugs should now be reported on bugs.typo3.org in the tx_chcforum section. Registering for an account there is easy, and reporting bugs on the bugtracker is the best way to ensure that I fix them, because I will go through every bug before releasing a new version. Feature requests should also be made on the bugtracker -- just be sure to label it as a feature. If the feature is important to you, you might consider including a pledge to make a small donation in the request -- feature requests attached to pledges or donations will be implemented as quickly as possible (and those of you who have been following the development of the forum know that I tend to release often).

Version 1.2.x and 1.3.x¶

• merged translations
• fixed bug where usernames would link to user's CWT profile instead of author CWT profile.
• fixed bug #1002 (inconsistency in keeping track of new posts between threads and replies)
• fixed bug #0963 (user images are generated using typo3 IMG_RESOURCE rather than using the original image. This will help keep load time down) If, for some reason, image magick doesn't work and the image isn't generated, the forum will default to the original file.
• Implemented Janno's suggestion in which clicking the PM button on a post will populate the pm form with re: post subject and quoted post text (maybe the latter isn't so good...let me know).
• Cleaned up the flexform a little bit and added notes by the fields that won't be respected if cwt_integration is on.
• Removed the "re:" form label from the php code and abstracted it to locallang
• Added a flexform field "enable cwt_community integration". In theory, if cwt_community is installed, all you have to do to make the integration work is check this box.
• cleaned up the TS conf for cwt_community in chc_forum TS. Users can declare their own templates for cwt_community here, but if they don't, the forum is coded to automatically use the default cwt templates that are bundled with the forum ext.
• removed the ID attribute from the userpic and changed it to a class attribute (because ID needs to be unique, I believe).
• added some default configuration for user images: if cwt_community integration is set, the forum will automatically look for user images in the cwt upload directory, unless alternate image path is set to something else.
• cwt_community integration included
• added ratings to posts
• added the ability to watch a thread (previously, users could only watch conferences)
• added ability for moderators to lock and unlock threads
• added ability for moderators to hide and unhide threads and posts.

Version 1.1.x¶

• Added update script to deal with expanded authentication methods.Admins can now set read and write access to conferences using forumgroups. The new permission system works as follows:Anonymous read access: any user, logged in or not, can read messages in the conference.Anonymous write access: any user, logged in or not, can read messages in the conference and post messages to the conference.Forumgroup read access: any user belonging to any one of the forumgroups assigned to the conference can read (but not write) in the conference.Forumgroup write access: any user beloning to any one of the forumgroups assigned to the conference can read and write in the conference.
• Sub-toolbar: I've added a box that I'm calling the "sub-toolbar" to the conference and thread view. It will contain buttons that should only show up in these views -- if anyone can think of a better place to put this stuff, let me know.
• Open thread / Close thread: If a user is viewing a thread that he/she is allowed to moderate, the option of opening or closing the thread will appear in the sub-toolbar. I'll add the option of making a thread sticky here at some point -- it will be easy now that the foundation has been laid.
• Watch conference / ignore conference
• These options show up in the sub-toolbar when a user is viewing a conference. Clicking on watch conference adds the conference to the list of conferences that the user wants to follow via email. Clicking on ignore conference will remove the conference from this list.
• Watch thread / ignore thread: these options show up in the sub-toolbar when a user is viewing a thread. Clicking on watch thread adds the thread to a list of threads that the user wants to follow via email. Clicking on ignore thread will remove the thread from this list.
• Updated mailer: I had to update the mailer to allow thread watching and to handle the new conference permissions system. A lot of people have requested that they can make it so that users only get the first new post in a conference or thread via email until they visit the thread. This functionality has not yet been added, but I'm planning on including it soon.
• Rewrote all authentication methods: I completely rewrote how the forum checks whether a user can access conferences, threads, etc. The new version was written with speed in mind -- by my calculations, the optimization that I did should shave at least a few seconds off of page load times.
• Added post caching: in previous versions, the forum would run a series of regular expressions on a post every time it was displayed to parse the forumcodes ([quote], [url], etc) and turn them into HTML. This was a waste of resources, so I added an extra field to the post records that cache the results of the forumcode parsing and stores it. When a post is displayed, the forum will check the date of the cached version against the last time the forum was edited via the frontend or the backend. If the cached version is more recent, the forum will use it. By my calculations, this shaved off aproximately 1.5 seconds of load time on pages that displayed 10 posts (eg., thread view).
• Removed all pi_list_query calls and replaced them with more efficient calls using DB API.
• Fixed bug that allowed users to post in closed threads.
• Fixed bug where reply and quote buttons would be included in posts in closed threads
• Fixed missing label from appearance section of flexform.
• Rewrote major parts of the backend module so that editing records is done via TYPO3 API (using TCA) -- this makes it much much easier to expand this module in the future, and it makes it easier to add new fields, because they're not hard-coded into the backend mod.
• Minor bug fixes with author name displaying
• Fixed bug with GRSP and Starting Point
• Added ability to sort posts in thread by date ASC or DESC.
• Merged translations
• Added "secret word" configuration value to the flexform security tab. This word will be used by the forum to create hashes (when necessary), to obscure / secure data. See the next entry for an example of how it will be used.
• Added encode method to the shared library and decode function to the pi1 class. When you pass a string to this encode method, the string will add an md5'd secret word (see above) to an array containing the string. This is all serialized and base64encoded and passed via the post / get data. The forum decodes the information and checks whether the secret word is correct. This can be used to obscure data sent via the URL -- in this case, I'm using it to encode author UID sent via URL. This should prevent somebody from writing a script that could make the forum output one username after another by feeding it &author_uid=1, &author_uid=2, etc. This is no longer possible, since the $author_uid value needs to be encrypted correctly (with the secret word), for the forum to do anything with it.
• Added a new configuration value to the appearance tab of forum flexform: "extension for template images". The default value is .png, although it could also be set to .gif. I removed hardcoded .png extensions from the forum code -- it will now get the extension from this value. So, if you wanted to use gifs instead ofpngs, just set this to "png", and the forum will look for filename.gif instead of filename.png. Because I like you guys, I went ahead and added gif versions of the default image files. Go crazy templaters!
• Fixed bug where IE users couldn't attach jpegs (I think -- wasn't able to reproduce it).
• Fixed colspan error in user_list template
• Fixed user image upload bug where forum failed to check for alternate img path.
• Fixed bug where user email addresses showed up in user list even though disable email was set to true. I added a quick check in the display class to prevent emails from showing up in the user list if disable email is set. However, this is a _quick_ fix, since the email column still shows up. For now, you should just edit this out of the template if you don't want it there -- in the future, I'll come up with a better fix. The user list is still very beta -- once I have some more time / sponsorship, I want to build some community features around the userlist, and I'll probably get rid of the email addresses all-together in favor of private messaging or a forum mailer.
• Abstracted the '>' divider in the nav path out of the code and into the locallangfile, as per Brendan Jocson's suggestion.
• Added some short term caching to the conf and cat read auth methods to try to speed them up. I'm pretty sure that it's the authentication scheme that's slowing down the forum. This part of the forum probably needs to be reconceived, but that's a project for the next release, I think. Hopefully this fix will help in the mean-time.
• rewrote the methods for dealing with new posts so the forum stores serialized arrays of the posts. I'm not sure that this is going to be faster... but it will be easy enough to go back to the old method, if necessary.
• fixed bug (feature?) where new posts link wouldn't display if user profiles were disabled. NOTE: this meant modifying the toolbar template file. Update accordingly.
• Made the forum PHP5 compatible
• Changed when the toolbar html is generated -- from now on it gets generated after the bulk of the HTML for each view is produced, which means that the new posts count will be correct, since it will take the current view into consideration when its calculated.
• Added "mark read" button to toolbar; marks all posts as read
• Changed post form submit button text to "edit post" if the user is editing (rather than "post message")
• Added new icons from Ximian project to the post form toolbar.
• Added emoticons (thanks to Jan Wulff!)
• Changed quote HTML tags from id attributes to classes (if I understand correctly, xhtml strict can't have more than one tag with the same id attribute).
• Fixed forum code problems -- mainly by redoing the code, basing it closely on phpBBs bbcode.
• Added new forum code: color, size, email, and code tags!
• Removed tables from quote view -- replaced with divs
• Added button for text color
• Fixed bug where forum mailer preferences would be overwritten when there were multiple instances of the forum plugin present on a site.
• Added a subject field trim option in the last post info cell.
• abstracted some fcode wrappers out of the PHP and into typoscript setup.
• abstracted some HTML out of the forum and into typoscript setup.
• Modified the forum so that it's possible for other scripts to add GETvars to the URL of forum links via typoscript -- used for Rupi's forum / tt_news connector.
• Modified templates for this version: tool_bar.tpl, post_form.tpl
• Made it possible to set forum starting view via TS
• Fixed backend module access problems for non-admin users
• Various other misc. bug fixes (see bugs.typo3.org)