Fox Forum

Summary: How to build a simple forum with Fox
Version: 2008-07-03
Prerequisites: pmwiki 2.2.0 beta 50 or later and latest Fox (included)
Status: experimental
Maintainer: HansB?
Categories: Forum CMS Fox, CustomPageStore
Download: Attach:foxforum.zip Δ

Questions answered by this recipe

How can I add a simple forum?

Description

You can create a simple forum with Attach:foxforum.zip Δ and Fox. The zip file contains foxforum.php with extensions to Fox, fox.php, foxdelete.php, foxedit.php, fox.css, guiedit.php and image files, and ready made forum template and system pages. Sample-Forum.php contains local group-specific configurations.

With no changes to the Sample-Forum.php file, just by copying it to the local/ folder, and renaming it to Forum.php, you get a forum in group "Forum", which will create pages with one page per topic and with all posts written into the same topic page. A ForumConfig gives choices of display templates, which can change the layout and look of all topic pages and posts instantly.

Features

You can see a working forum on my site at www.softflow.co.uk/design/Forum

Installation

Prerequisites: You need PmWiki version 2.2.0 beta 50 or later (install the latest), and set in config.php:

$EnableRelativePageVars = 1;

Download Attach:foxforum.zip Δ, unzip and copy cookbook/fox/ files into cookbook/fox/ folder, Sample-Forum.php into local/ folder for local group customisation (revise and modify as required). A subdirectory cookbook/fox/templates.d should be created automatically, with all the template and form wikipage files.

Add to config.php: 

# needed for creating other Forum groups, modify as needed
$FoxPagePermissions['Forum*.*'] = 'add,copy';
# needed for adding new page store with ready wiki pages in cookbook/fox/templates.d/
include_once("$FarmD/cookbook/fox/foxtemplates.php");
# main form processor added here so other Forum groups can be created 
# from FoxTemplates/CreateNewForum page 
include_once("$FarmD/cookbook/fox/fox.php");
# add delete links // uncomment next line if foxdelete is used outside Forum group, i.e other Fox forms //
#include_once("$FarmD/cookbook/fox/foxdelete.php");
# add edit links // uncomment next line if foxedit is used outside Forum group, i.e other Fox forms //
#include_once("$FarmD/cookbook/fox/foxedit.php");

Rename local/Sample-Forum.php to your forum's group name (for instance: ChessForum), and edit it as needed.

  1. Choose the type of forum with either (comment out the other)
    • $FoxForum['type'] = 'standard'; //for one page per topic forum
    • $FoxForum['type'] = 'extended'; //for one page per post forum (see below)
  2. Check that the key in variable $FoxPagePermissions is set to your forum group's name, for instance
    $FoxPagePermissions["ChessForum.*"] = 'all';

If you rename it to Forum.php you already got a ready Forum.Forum homepage and pages CreateNewTopic and ForumConfig installed.

This will install (include) automatically foxforum.php, and through it also fox.php, foxdelete.php, foxedit.php and the GuiButtons? recipe for the forum group, if these were not installed already.

Go to page Forum.Forum for a ready made forum. Just create new topics and comments to topics.

Or set up a new forum in a different group, by going to FoxTemplates.FoxTemplates and follow the link and instructions to set up either a standard Forum or a ForumX type forum, which stores each post on a separate page.

Most forum template and system pages are in group FoxTemplates, and will be used from that group. Only the pages CreateNewTopic, ForumConfig and the forum index page (home page) will be copied into a new forum group.

Forum which saves each post on a separate page: ForumX

To set up a one-post-per-page forum (ForumX), go to FoxTemplates.CreateNewForumX, and follow the instructions.

ForumX uses a model of one page per post, where all posts in each topic share similar names. Each new topic you add creates a topic page (to hold a pagelist and other topic info), and a first post page. Later comments are stored on separate pages, named as the topic page, with an added number, which increases for each new comment.

etc. for comment pages

ForumX shares the display templates from FoxTemplates.DisplayTemplates, and also some other template pages. Any alternative pages are marked with an X at the end of the file name.

Custom Forum Group Name or Multiple Forums

To install the forum into a group of a different name, or to have multiple fora on your wiki, do the following. (in this example we will use the name "ChessForum")

  1. Rename local/Sample-Forum.php to ChessForum.php
  2. Edit the local/ChessForum.php file and modify the line as follows:
    $FoxPagePermissions["ChessForum.*"] = 'all';
  3. Rename the files in cookbook/foxforum/templates.d/ as follows:
    Forum.CreateNewTopic --> ChessForum.CreateNewTopic
    Forum.Forum --> ChessForum.Forum
    Forum.ForumConfig --> ChessForum.ForumConfig
  4. or instead of the last step go in the wiki to page FoxTemplates.CreateNewForum and follow the steps there. There is a form which automatically will copy all the necessary files. You just need to type in the new forum group name.

Forum Config

From page ForumConfig you can choose between a number of display templates, and the number of posts you want displayed per page. Templates include a "classic" phpBB look template, and simplified templates which strip/do not display any subject field and footer.

FoxForum has inbuilt support for Captcha? and an "access code" feature to reduce spam.
Install and enable Captcha, and the captcha field will show automatically.
Alternativeley Access code is enabled in your forum localisation file (i.e. for instance local/ChessForum):

$EnableAccessCode = 1;

If you don't want a ForumConfig page, you can set defaults from within config.php.

Customisations

This forum is built using form pages and templates on page FormTemplates for posting forms and templates on page DisplayTemplates for display layouts. Most pages are in the group FoxTemplates. Only the index (home) page and CreateNewTopic and ForumConfig are in the Forum group.

You can customise the forum by modifying the form posting pages FoxTemplates.CommentForm and Forum.CreateNewTopic, for instance to remove guiedit buttons or the subject input field, or add other input fields, change descriptions etc.

The CommentForm uses FoxTemplates.FormTemplates#comment, which determines what gets posted to the page. It holds various replacement variables, which will be filled with the values from the input fields, and calculated values for the increasing post number, etc.

The CreateNewTopic form uses FoxTemplates.FormTemplates#newtopic respectively. This form creates a new topic page with the initial topic post content, sets the title, and also inserts an (:include ...CommentForm:) markup at the bottom, for displaying the CommentForm on each topic page.

The page DisplayTemplates in the FoxTemplates group holds various templates used solely for determining the layout and display of the forum posts. Others can be added there. Similar replacement variables are used in the display template as in the posting templates. Layout is achieved using PmWiki div markup, or table markup, and further styling is achieved using style classes in the divs or table cells.

The separation of content and display is achieved with the use of (:include ... :) markup for each forum post: Each (:include ... :) includes either a DisplayTopicTemplate (for the initial post) or a DisplayCommentTemplate, determined by a page variable. The (:include ... :) then replaces any replacement variables in the template with values it gets from parameters inside its markup, i.e values for author name, subject, message text, date etc. So the same portion of the DisplayTemplate page gets included again and again for each subsequent post, but fills in different values from its parameters, which were posted with the posting forms originally.

Which section of the DisplayTemplate is used is determined by the forum configuration, chiefly on the ForumConfig page, or from within config.php, or from an author's Profile page, by setting the variables $DisplayTopicTemplate and $DisplayCommentTemplate.

Individualisations for authors from their Profiles page

Display templates can now be set also from with an author's Profiles page, to allow for individual display preferences. An author can also include on her Profiles page personal information and an avatar image, which will be displayed (in the "classic" template) on the left side space, and page text variables for an email address and website url, which will be displayed in the message footer.

Entries on an author's Profiles page should be as PTVs, an example: 

my personal info:
(:www: www.example.com:)
(:email: bob@example.com:)
(:info:
Attach:Profiles.AuthorName/avatar.jpg
Location: Scotland
:)

my preferred forum display style:
(:DisplayTopicTemplate: FoxTemplates.DisplayTemplates#classic:)
(:DisplayCommentTemplate: FoxTemplates.DisplayTemplates#classic:)

Notes

The forum uses the templating feature of the (:include .. :) directive for displaying posts in various formats. The formatting is divided from the storage of the post content.

Release Notes

And change in config.php include_once('cookbook/foxforum.php'); to include_once('cookbook/foxtemplates.php'); This will declare the fox/templates.d pagestore for the whole wiki, but foxforum.php will be only included for the forum group.

Upgrade Note from version 2007-05-23/24 to version 2007-10-22/25:'''
All FoxTemplates pages and the ForumConfig and CreateNewTopic pages need replacing. Existing older forum pages will look okay, apart from having a subject field added with a {{$$subject}} string as content, instead of being empty/suppressed. So you might want to change the formatting text in all existing forum pages.
You could do a search-and-replace on all the files in the forum group, after downloading, and upload the saved files later.
Replace {ForumConfig$:DisplayTopicTemplate} with {$DisplayTopicTemplate}.
Replace {ForumConfig$:DisplayCommentTemplate} with {$DisplayCommentTemplate}.
The above is not essential, as the older posts will still take their display template from ForumConfig.
The following will add empty subject fields to get rid of {{$$subject}} displaying.
Add an (empty PTV) (:subject000:::) to the page.
In each posts (:include {$DisplayTopicTemplate} ..... :) line
replace text=$:comment with subject={$FullName}$:subject000 text={$FullName}$:comment. If you don't want a subject field for comments, edit the CommentForm, the FormTemplates#comment section, and the DisplayTemplates.

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

Comments see [FoxForum-Comments]]

See Also

Contributors