CapeSoft.Com
Clarion Source Code
Web Forums
Documentation
CapeSoft Logo

CapeSoft Forums
Documentation

Download Latest Version
Installed Version Latest Version

Introduction

CapeSoft Forums is an example of a NetTalk web application. It allows you to easily create, and administer forums on the web.

Requirements

To compile the forum source code you will need the following;

Installation

Install all the supplied files into a new folder. This will include an app and dct file, and other dependent resources (such as icons). 

License

The application is provided in source code format (app & dct) and the source code may not be distributed to other people. However the resultant EXE created with the source code can be distributed, without restriction, royalty free.

Distribution

After compiling the application, you are free to deploy the resulting EXE and DLL on one or more of your servers without additional payment. However you may not resell either the source code, nor the resulting Exe / DLL without permission from CapeSoft.

Supported Windows

the Web Forums Exe will run on any version of Windows from Windows XP, Service Pack 3. If you need to run it on Windows XP before Service Pack 3, then see here.

Compiling

Load the app into Clarion. It is shipped as a Clarion 6 app, so if you are loading it into a later version of Clarion allow it to convert.
Start the compile using the usual methods. This will create (by default) an Exe. You can change this, if you wish, to compile to a DLL, so that it can be run under the Multi-site Host program.

The program is using port 88 by default. This can be changed in the NetTalk Extension in the WebServer procedure.

Updating to a later Clarion / NetTalk

If you update the forums to a later version of NetTalk or Clarion then you may want to check this section for any specific information which may apply to you;
  1. Cannot call procedure as function
    change this line
      packet = clip(packet) & p_web.jQuery('#' & p_web._jsok('menu')&'_f'& loc:menunumber,'accordion',loc:options)
    to
      p_web.jQuery('#' & p_web._jsok('menu')&'_f'& loc:menunumber,'accordion',loc:options)

    and this line
     packet = clip(packet) & '</div></div><13,10>' & p_web.jQuery('#group_' & FGRP:GroupId,'accordion',loc:options)
    to the following 2 lines;
      packet = clip(packet) & '</div></div><13,10>'
      p_web.jQuery('#group_' & FGRP:GroupId,'accordion',loc:options)
  2. Unknown Identifier CRLF
    Change CRLF to p_web.CRLF

Server Settings

When you run the Exe for the first time, you must set all the basic settings for the application. This is done on the Settings tab of the server's Window. The settings are stored in an xml file, ForumSettings.Xml, which is located in the current folder.

Overall Forums Name

This is the name of the forums as presented to the user.

Dns Name

This is the url that the user would enter in order to access these forums. This is used when creating emails, sent to the user, alerting them to a response to their note etc.

User File Path

This is the location of the User.Tps file. This may be in a different place to the other data files if you wish to share a user list among multiple forums. If left blank then the folder containing the EXE or DLL is used.

Forums Data Path

This is the location of the data files on the disk. If left blank then the folder containing the EXE or DLL is used.

Email

There are a number of places in the forums where an email can be sent to a user. In order to do this the forum software needs to know the following details of your Email Server. After setting the email settings it is recommended you click on the Test Email button to make sure the server can send emails.

Server

The IP address, or DNS name pointing at your mail server.

Port

The Port the email server is listening on. This is usually port 25.

From

The "from address" which is valid for the server. Most servers will not accept mail for delivery unless they contain a valid "from" address for that server.

User

If your email server requires that you login before sending, enter your user name for the server here.

Password

If your email server requires that you login before sending, enter your password here.

Layout

Topics Per Page

This is the number of items which will appear in the topics list (the left hand list), per page. Around 20 is a good value here.

Replies Per Page

This is the number of replies that will be shown (the right-hand-list) for each topic, before it in turn goes to the next page. This can be set quite high as in most cases you want to see the whole conversation for a topic.

Features

Add "All Postings" to menus

If this is on then an additional item is added to each Forum Group, which allows the user to see all the topics posted in that forum group.

Enable Subscriptions functionality

If this is on then the user is able to subscribe to some specific forums.

Add First User

When you connect to the server for the first time you will be prompted to add the first user. This will become the supervisor, or overall administrator, of the site. To add the first user, click on the New User link.

Note: When adding a user, the forum server uses a slightly different approach to other forum software. Rather than require a captcha to be entered, the form requires a code to be entered. This code is emailed to the user as the user enters his details. For the first user this code is always 1111, and so the default value can be accepted.

Customize Styles and HTML

Three HTML snippets are included in the web folder. These are used to determine the basic layout of the site. They are;
All 3 of these files can be modified by the user, but care should be taken to backup these modifications when updating the forum software itself.

NOTE: The Header.Htm should consist of a xHTML compliant snippet of HTML. In other words, if it contains code which is both HTML AND XML compliant, then the menu will be updated "live" on the screen when the forum details change. The two most important thing about making HTML also XML compliant is
a) Every opening tag must have a closing tag and
b) "attributes" must have a value, and the value must be in quotes.

This is not xml;
<p>hello
<p>my site
<img  src="whatever">
<input type="text" readonly>

This is
<p>hello</p>
<p>my site</p>
<img  src="whatever" />
<input type="text" readonly="readonly">

In addition to the HTML, you can also add additional CSS files to the styles folder in order to override the default styles. You should put your custom changes into a file called site.css (which you will need to create). After editing this file, re-run the Gzipall.Bat utility. the Gzipall.Bat utility is generated for you when you compile the app, and requires the Gzip.Exe program which is in your Accessory/Bin (or /3rdparty/bin) folder. When deploying your app it is recommended you ship the GzipAll.Bat, and Gzip.Exe files and place them in the folder immediately above the Web folder. In this way you can edit your site.css file live, re-run GzipAll.Bat, and see the effects, without needing to recompile the program.

Forum Types

The basic idea of a forum is to let people communicate with each other in a group context. However the basic structure of this communication can change by changing some very simple parameters. When creating each forum you will be able to make them behave differently to each other by changing the forum type.

Forum

A forum allows anyone to start a new thread, and anyone can comment on any thread. Only the original posted (and system moderators) can edit the original posting.

Blog

A blog is similar to a forum, except that only moderators can start a new thread. Thus while anyone can comment the number of people who can start a new topic is limited.

Wiki

A Wiki is a forum where any person can edit the original posting.

Task

A task is a forum topic which can be "Assigned" to a user. Using this approach the topic can be closed when completed. It also has an optional Urgent setting which can be applied when the topic is created.

Users are able to click on the To Do menu item to see which topics have been assigned to them. They are able to comment on the topic, assign the topic to someone else, or close the topic.

Forum Administration

If you log in as an administrator (the first user is automatically an administrator) then you will be able to configure various aspects of the forums. Two extra menus will appear, one for Forum Management, and another for Assign Access Rights.

Forum Management

If you are setting up the forums for the first time, then we recommend you start by clicking on the Forums item. This menu is only available to system administrators.

Users

All users are not created equal. There are Administrators, Moderators and Users. Administrators have complete control and can add new forums, manage users and so on. They can also appoint users to be Moderators of one or more groups.

Another way to assign the access rights to a group is to choose the Forums item under the Assign Access Rights menu. Select the forum to inspect, and then from the list of users determine who has access, and who the moderators of the forum are. This option is also open to moderators, for groups that they moderate.

Forums

In this software there are two layers that identify a forum. the first is the "Forum Group". This is a group name given to a collection of individual forums. This group will appear as its own menu on the left hand side of the screen. Inside each group can be one or more forums.
Example:
Group Name: NetTalk
Forums: Web Server, Email, FTP

The ORDER setting allows you to determine the order of the Foum groups, as they are displayed in the menu on the left.

Once you have created one or more forum groups, you can go ahead and add individual forums to each group. Most of the forum settings are pretty self-explanatory, but it is worth noting that you can set a specific URL for a forum here. This is particularly useful if you want to alert the user to an existing forum, but in the case where the actual forum is on another site. If the URL field is left blank (which you will want to do in most cases) then the forum is considered to be internal to these forums.

You also have the opportunity to set a forum to be a Blog, or a Wiki. A blog is where only pre-appointed persons are allowed to start a new thread (the administrator, or forum moderators), other users can only comment. A wiki is where multiple users are allowed to change both the original post and the replies. A private group is invisible to all users, and access is by "invitation only" - ie the administrator must grant specific access rights to users to that group.

When viewing the forum groups, and forums, you will also see a list of users. For more information on the user list see the section above.

Server Settings

This is the Web-Interface version to allow you to set the primary settings for the forum software.

Bulk Email

This allows you to send an email to all the users who have either subscribed or registered with the forum. (Each user has the ability to turn off the receipt of these emails on their profile.)

Assign Access Rights

This menu is open to Administrators, and Moderators. It allows you to grant, or deny, access rights to users to specific forums.

User Manual

Once logged in the user will be able to subscribe to forums, post to forums, post replies to entries, search past entries, and edit their profile. These options are briefly discussed here.

Subscribe To Forums

Inside a forum group it's possible to have a large number of forums. Usually the user will not be interested in all the foums, but may want to pay attention to only a few of them. To limit the list of forums on the menu the user can choose to Subscribe to forums. If they have subscribed to forums, inside a forum group, then only the subscribed forums will appear in the menu.
If the user has not subscribed to any of the forums in the group, then all the forums in that group are displayed.

Search

The Search functionality does a full text search of the existing posts, across all forums (that the user has access to.)
The search term can consist of multiple fields. These are by default "OR" fields, in other words any result which matches and of the searched fields will be retrieved. In addition to this search terms can be prefixed with a + or - character. If prepended by a + character a field MUST be in the result, if prepended by a - character the field MUST NOT be in the result.
For example;
+example -sql
will return all the posts that include the word "example" but do not include the word "sql".
+"sql example"
will return all the posts that contain the phrase "sql example" in the text.
The search results are sorted by date, the most recent post which matches the search is displayed first.

Edit Profile

The user can change their personal details here.

Features

This section describes some features of the software that may not be obvious when first using it.

Editing & Deleting Posts

Users can edit their own posts, and posts can be deleted if there are no replies to the post.
Moderators can edit, and delete all posts, and replies, in the forums that they moderate.
Administrators can edit and delete all posts and replies.

Sticky Posts

If a particular topic needs to remain at the top of the forum, then it can be marked as Sticky. A Moderator, or Administrator is able to set this (or clear this) for any post. Stickies are usually used for informational type posts, or posts which need to be easily found by all users of the forum.

Convert to SQL

The forums source code is shipped as using a TPS data store. However it can be converted to using a SQL data store using whatever conversion approach you prefer. If you have any problems during the conversion, or you identify code you feel is not suitable for SQL data stores, then please contact us.

Modifications

This section discusses possible modifications you may need, or want, to make to the software.

Support Windows XP, before SP3

The default hashing algorithm for hashing the login passwords is SHA-512. This is only available on Windows XP Service Pack 3 and later. If you run the forums software on a machine that does not support SHA-256 you'll get the following error;

Cryptonite. Error in CreateHash(): Could not create the Hash object. Windows CryptoAPI error -2146893816: 80090008h: Invalid algorithm specified.
Solutions:
a) Update the machine to XP Service pack 3. (recommended)
b) Use another machine to host the Forums software.
c) Recompile to use a different hashing algorithm.

Pros: It'll run on Windows XP SP2 and earlier.
Cons: Because Hashing is a "one-way" operation you won't be able to change the algorithm later on (without resetting all the passwords.) SHA-1 makes the passwords slightly more vulnerable to cracking than SHA-256.

Code change:
Login Attempt procedure. Search for cs:CALG_SHA_512 and replace with cs:CALG_SHA1

Version History