How does it work? Comments are submitted through a simple web form and are written into a plain text file, stored on your web server. This user-contributed material remains under your complete control and ownership. Some clever scripting is able to read each comment from the plain text file and display it on the page, with comments ordered newest first. Potential uses for CommentsStack includes a visitor guest book for holiday accommodation, product ratings, customer feedback and community consultation. It is possible to manually import comments from elsewhere. Likewise the plain text file can be edited to delete old or unwanted comments.

Key features

Here are some points of interest about CommentsStack for RapidWeaver:
  • Fully EU GDPR compliant. No identifiable information is ever collected from users. Users can choose to provide a screen or fake name if they prefer. Email and IP addresses are never recorded.
  • No SQL databases. Comments are saved within a simple 'flat file' plain text file on your server. This stack is lightweight and reliable - meaning less to go wrong! Easy to move between servers and keep backed-up.
  • All elements are translatable to any language. The basic layout and styling is extensively customisable from within the stack settings. Mock comments are displayed in RapidWeaver preview to help you visualise your completed CommentsStack
  • Can be used for comments, reviews or a simple online guest book. Change the form labels to suit your setup. Hide the star rating if it's not required or change the name field to a field for review titles.
  • Present comments in a single column or styled as mini 'cards' in a multi-column / masonry layout
  • Lock the submission form after any length of time, if you want to stop people continuing to review old or outdated products / services. Or use the stack to only display comments you upload via FTP.
  • Various basic measures to protect against spam and comment form abuse - blocks on excessive use of the return key, disabling of full HTML markup in comments, bad word lists, honeypots and math questions to confuse automated spam bots.
  • Your comments can be seen and indexed by popular search engines
  • Every comment gets allocated a unique permalink, which you can use to link-to or promote featured comments
  • Can be used behind a SiteLok or Lockdown firewall (not included), if you prefer to only have trusted, logged-in members view or write comments
  • Ability to easily edit the flat-file database at any time, to edit comments, delete comments or manually import new ones from elsewhere. Editing can usually be done securely via your existing FTP software and any plain text editor.
  • There is a provided option to get simple email notifications when a new comment is posted (on supported hosting companies only).
  • Optional cookie tracking can limit multiple postings within a specified time period.
  • And as your collection of comments grows longer, automatic pagination makes for a more comfortable reading experience!

CommentsStack requires a minimum of Stacks 4 and PHP 8. Optional email notifications require a compatible web host that supports PHPMail and an email account of the same domain as the website.

Example

This is a real working example of the CommentsStack, with the default settings applied. Try leaving a comment yourself. Tell us what part of the world you are in and what the weather is like today.
 
zzzz
zzzzz
 

Setup

Follow these steps for getting a single CommentsStack setup in your website:
  1. Give the page a .php extension, in the RapidWeaver Page Inspector
  2. Open the Prefix box in the RapidWeaver page inspector and enter <?php session_start(); ?>
  3. Drag and drop a copy of the stack into the page, from your Stacks library
  4. Within the settings, the database name and time zone can be changed if required. Please see this webpage for details about what the timezone can be changed to. Database name always needs to be in a 'web safe' format - that is to mean it starts with a letter and contains no spaces or special characters. Comment count controls how many comments are shown on each pagination panel. Fields control what data you collect from users and is fully translatable into any language of your choice
  5. The CommentsStack Advanced Settings is the place to go for turning cookie tracking on or off, setting up simple email notifications, changing the viewing mode (i.e. start the page with the comments form hidden) and other features like switching the CommentsStack into read-only mode.
  6. Publish the page to your web server. Navigate to the page in the web browser and initiate setup of the database. This normally requires the page to be refreshed once or twice, to establish the new database (text file) that the comments will be stored within. From thereafter, website users can begin to leave comments or reviews.

Because the database used to store user-submitted content is generated separately to your website, it is impossible for RapidWeaver to accidentally delete it on subsequent republishes. However you should take care not to delete it yourself when managing files on your web hosting account. If you want to store the comments database elsewhere on your hosting account, please provide a relative path in the database name e.g. ../../comments/product-reviews.txt

Multiple CommentsStacks can be configured to share the same database. For example, you may wish to display a full set of comments on one page, and perhaps only a summary in 'read only' mode on your website homepage etc. When linking-to databases elsewhere on the hosting account, it is imperative that relative paths are always used; the same as if you were using another PHP stack like ProGallery. If you are unsure what a relative path is, you can search for this online using your preferred search engine.

Always keep your database files backed-up. Consider setting a reminder to do it regularly. You can also take backups of the comments from the email notifications you get sent. Most better quality web hosting companies already offer free backups. It may be possible to configure CRON jobs to create automated backups of comment files at set intervals. Your hosting company will be best-placed to advise you about this.

Configuring ratings

Ratings often form the basis of many feedback and review setups. But there can be huge variances in what rating options a RapidWeaver user may wish to present to end users. With this in mind, we have opted for a more 'opensource' approach; in letting you take full control of setting up a desired ratings or review system. You have complete control of both the backend and frontend configuration.

By default, a 5-point star rating system is used with radio buttons:

<div class="stars">
<input class="star star-5" id="star-5" type="radio" name="star" value="5">
<label class="star star-5" for="star-5"></label>
<input class="star star-4" id="star-4" type="radio" name="star" value="4">
<label class="star star-4" for="star-4"></label>
<input class="star star-3" id="star-3" type="radio" name="star" value="3">
<label class="star star-3" for="star-3"></label>
<input class="star star-2" id="star-2" type="radio" name="star" value="2">
<label class="star star-2" for="star-2"></label>
<input class="star star-1" id="star-1" type="radio" name="star" value="1">
<label class="star star-1" for="star-1"></label>
</div>
This is the HTML markup to provide end users with the ability to rate a product or service on a scale of 1 to 5. Certainly you could replace stars with something else or increase the resolution of recording; to perhaps something like a 10-point star rating system. A theme that includes Font Awesome icons is required.

The choice of rating the user selects is recorded into your database as a simple integer (whole number).

When viewing the comments, the rating gets appended onto a class like this:

guest-rating-4
In this case, the user provided a rating of '4'. So then you can write custom CSS to output text or other content (like stars) to provide a visual representation of the rating:

label.star:before {
content: '\f006';
font-family: FontAwesome;
}

.guest-rating {
font-family: FontAwesome;
font-size: 30px;
color: #FD4;
text-shadow: 1px 1px 1px rgba(0,0,0,0.5);
letter-spacing: 5px;
}

@media screen and (min-width: 768px) {
.guest-rating {
position: absolute;
top: 15px;
right: 15px;
}
}

.guest-rating-1:after {
content: '\f005 \f006 \f006 \f006 \f006';
}

.guest-rating-2:after {
content: '\f005 \f005 \f006 \f006 \f006';
}

.guest-rating-3:after {
content: '\f005 \f005 \f005 \f006 \f006';
}

.guest-rating-4:after {
content: '\f005 \f005 \f005 \f005 \f006';
}

.guest-rating-5:after {
content: '\f005 \f005 \f005 \f005 \f005';
}
The 'content' attribute is a CSS method of writing content into the page. In this example we use unicode Font Awesome stars. However you can use unicode for other characters (like favicons) or output a string of text. This could be an example of text to use for a 5-star rating:

.guest-rating-5:after {
content: 'Excellent';
}
Again this is completely opensource, so you can take the code from the stack, edit it in your preferred code editor, and paste it back in. Users of CommentsStacks have been able to successfully replace stars with numbers, word descriptions, favicons and other rating representations. You are certainly not limited to only being able to use 5 star ratings. With this stack, you can practically invent any rating system of your desire. Setup and testing of customised rating systems is not provided for free as part of the stack purchase; this is a service you would need to book in advance and hire a developer to oversee for you, if you are unable to create a customised ratings configuration yourself.

Bad word lists

Comments that contain profanities or other 'bad words' won't be blocked from being submitted. There are potentially some genuine cases where you might still want to receive such comments. However you can block those words or phases from being showed publicly on your website. We use Javascript to look at the words in each comment and compare those words against a list of bad words you provide. If a bad word or phase is detected, the letters get replaced with asterisks. The bad word list needs to be added in the stack as a string list, like this:

'bad', 'words', 'and phrases', 'go', 'here like', 'this'
There are many lists of swearwords / profanities available online already. Some may be ready in the correct format to use or can be easily edited in a plain text editor. If you find they are not in the desired format (and you know a little Python programming), you can convert them into a list ready to paste straight into the stack using this Python function we've written:

badwords = """paste your
list of
bad
words and phrases
on each
line like
this"""

new_list_of_bad_words = badwords.split("\n")

print(new_list_of_bad_words)
When this function is run, the list of words and phases will be split at each line break (\n) and converted into string list format, ready to be pasted directly into the stack.

User average ratings

The following information is still valid, however you may find the new RatingStack easier to use and more feature-rich.

You might collect a lot of reviews in your CommentsStack. Ordinarily displaying an average rating might not work very accurately, because you would only be able to generate an average review total from the five-or-so comments visible in each pagination panel. To overcome this problem, we simultaneously write ratings into their own database text file. It's named database-001-ratings.txt where database-001.txt is the name of your database.

There are a huge number of possible ways a RapidWeaver user may want to use and display average ratings. And indeed, users may wish to display average ratings elsewhere on a website, like in the 'hero' unit on a website homepage. With this in mind, we have completely open-sourced user average reviews. To fetch ratings, calculate and average and output text, you can use PHP code like this:

<?php
// Relative path and name of the text file acting as the database for your ratings
$filename = "database-001-ratings.txt";
$fp = @fopen($filename, 'r');
if ($fp) {
$array = explode("\n", fread($fp, filesize($filename)));
}
$average = array_sum($array) / count($array);

// Calculate the average rating, rounded to 0 decimal places
$average_zero = number_format((float)$average, 0, '.', '');

// Calculate the average rating, rounded to 1 decimal places
$average_one = number_format((float)$average, 1, '.', '');

// Calculate the average rating, rounded to 2 decimal places
$average_two = number_format((float)$average, 2, '.', '');

// Display the average rating, within some HTML and text
echo "<div class='average-rating-$average_zero'>Average rating of $average_one from our reviewers!</div>";
?>
Simply paste this code into an HTML stack. Make sure the page has a .php extension set. About the only part that requires attention might be line #3 where you set the relative path and name of the database file holding your ratings. The rest of this PHP plugin will calculate the average rating and output this number in either zero, one or two decimal places via this variable:

$average_zero
$average_one
$average_two
On its own, this PHP taken from above should work well. If you are not afraid of messing around some more with this code or you have some experience of working with PHP, then there are potentially some seriously cool things you can do with average user ratings! Again help is available for hire if you're seeking to get something special setup in your webpages.

As with the main database file used for CommentsStack, the text file that ratings are stored in is completely opensource on your server. It is possible to edit this with any plain text editor to adjust ratings or delete older ones. Newest ratings are displayed at the top.

Linking to the first comment and the submit form

In CommentsStacks v1.3.0 append #read onto the page link, to have CommentsStack scroll-down to the first comment, as the page is loaded. To have CommentsStack scroll-down and open the submit form as the page loads, add #write onto the page address. Completed links might look something like this:

https://example.com/mypage/#read
https://example.com/mypage/#write
These links will work from other webpages. If you want to disable smooth scrolling or change the anchor names used, this can be done in the Advanced Settings.