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?

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

  • one page per topic, or one page per post with the ForumX forum.
  • topic name can include spaces and special characters.
  • one forum per group, multiple fora possible.
  • display layout of messages (posts) via templates, independent from posted content pages.
  • possibility of different layout for first post (topic post) and subsequent posts (comment posts), useful for blogs.
  • styling of display layouts via stylesheet, default classes included in fox.css (see Fox), colour integration with Gemini , FixFlow and Triad skins.
  • author can set display preferences on the author's Profiles page.
  • author can set email address and website url, as well as personal info including an avatar image on the author's Profiles page.
  • individual messages can be deleted using FoxDelete.
  • individual messages can be edited using FoxEdit.
  • post counter.
  • integrated Captcha? or access code support.
  • subject (subheader), text and author name field.
  • automatic breaking of page into subpages with easy navigation.
  • easy creation of forums with different names (each in a different group).
  • possible mail notification using FoxNotify, in various formats, including whole post content could be mailed to list of subscribers.

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.

  • TopicPage (topic page with pagelist displaying all associated pages)
  • TopicPage-001 (original post content)
  • TopicPage-002 (first comment post)
  • TopicPage-003 (next comment post)

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

  • 2008-07-03: Added message 'Preview' with included FoxTemplates.EditMessageForm, latest fox.php and foxedit.php
  • 2008-06-19: Update including latest fox.php, foxdelete.php and foxedit.php. Internationalisation of 'Page' word in foxforum.php. Fixed CreateNewForum form. Updated README.txt with new installation instructions.
  • 2008-03-30: Update to latest fox.php. Added foxedit links. Fixed bug in page urls. Small changes to some templates.
  • 2007-12-20: Changed FoxCountFilter function to read FoxCount when post gets processed, this fixes bug for wrong count number when two posts are submitted at about the same time (posting conflict).
  • 2007-12-07a: Added configuration switch to local/Sample-Forum.php to choose forum type. This will exclude non-forum type specific code from loading (in foxforum.php). This will improve speed of standard forum page loads. For updates to the latest foxforum.php please revise your local forum php file(s) and add the relevant line from Sample-Forum.php. For a standard forum you need to add:
    $FoxForum['type'] = 'standard';
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.
  • 2007-12-07: Changed the installation README.txt. Added foxtemplates.php for inclusion in config.php. Recommend foxforum.php to be included only from local/Forum.php (local/ForumGroupName.php), so PmWiki performance is better on pages outside the forum group.
  • 2007-11-27: Updated to latest Fox for full Blocklist support. Added PmWiki version checker.
  • 2007-11-24: Fixed bug in info section of DisplayTemplates, added captcha support to ForumConfig, added author conditional to foxforum.php
  • 2007-11-20: Added message editing by including foxedit.php (FoxEdit) and message edit form and added edit links to messages. Updated to latest fox.php (Fox).
  • 2007-11-11a: Removed wikiword markup extension from foxforum.php, and replaced use of it in DisplayTemplates with pagename markup extension. Added conditionals to show accesscode or captcha entry boxes if they are enabled.
  • 2007-11-11: update with latest fox (bug fix in handling ptv targets)
  • 2007-11-05: Update to accomodate changes in latest fox.php, affecting FoxTemplates.CreateNewForum
  • 2007-10-31: Modified DisplayTemplates and added a WikiWord markup expression definition to foxforum.php, to handle author names with spaces and odd characters better.
  • 2007-10-28: Updated the whole package for the latest fox.php. Removed the foxptvreplace.php filter script, updated templates accordingly. A new Sample-Forum.php holds all major configurations. Fox and GuiButtons? are included in the package, for easier installation, and included as default from foxforum.php. Scripts are in a fox/ directory, and template page files in a new fox/templates.d/ PageStore directory.
  • 2007-10-25: Integrated all forum template pages into just 2 pages: FormTemplates and DisplayTemplates. Added summary messages for RecentChanges. This release needs Fox version 2007-10-25 to handle the template sections.
  • 2007-10-22: Further alterations to allow ForumX forums to share the same display templates. New page templates for ForumX are added, alternate page templates for ForumX have an X at the end of their names.

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.

  • 2007-10-21: Substantial alterations: ForumX files are temporarily removed (not ready yet for this new format). Display templates are all on one page. Display templates can be set in ForumConfig or by an author on her Profiles page, or simply in config.php, without need for ForumConfig. Added a subject field to forms. Added optional display of author info, avatar, and also email and www details, if entered on the author's profiles page. Changed display templates to include a template of "classic" phpBB look, with space for avatar pic and author info on a left side space. The new templates require the latest update of fox.css (see Fox), which includes new message style classes. This version allows greatly improved customisation and individualisation by authors.
  • 2007-05-24: Added ForumX page files. Added new PTV pattern for text storage.
  • 2007-05-23: Changed display templating from FeralFormattedEntry to (:include ''templatepage'' .... :)
  • 2007-05-05: Total new type of forum with FeralFormattedEntry? data display, giving the choice of switching display formats without need to change the post pages.
  • 2007-04-14: Fixed some bugs in prebuilt wiki pages
  • 2007-04-13: Attach:foxforum.zip Δ initial release

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