A User Guide For The Craft CMS Template Comments Plugin

Compatibility and System Requirements

Craft CMS Version Compatibility

The Craft CMS Template Comments plugin is compatible with Craft CMS versions 3.0 and above. This wide compatibility allows the plugin to be used by the majority of Craft CMS sites.

Installing the plugin on Craft CMS 2.x will result in errors, so it's advised to only use this on Craft 3+ for full functionality. The advanced templating and plugin capabilities offered in the latest Craft iterations enable seamless integration with the Template Comments add-on.

Overall, the plugin aims to maintain backwards compatibility as much as possible. However, to leverage the full range of features and improvements, it's recommended to run the latest Craft CMS version.

PHP Version Requirements

To operate smoothly, the Template Comments plugin requires PHP 5.6 or greater. PHP 7.0 or higher is preferred for optimal performance and security.

Legacy systems running outdated PHP versions below 5.6 will not be able to utilise this plugin. Upgrading to a modern PHP build is highly advised to enable the advanced functionality offered by this add-on.

The plugin is developed to integrate seamlessly with common PHP configurations. There are no special server requirements or settings needed to get the most out of its capabilities.

Database Support

The Template Comments plugin supports MySQL and PostgreSQL databases. These are the most commonly used databases for Craft CMS installs.

On both MySQL and PostgreSQL, the plugin creates the required tables upon installation. There is no need for manual database configuration or setup.

Other niche databases like SQLite may be incompatible. For production sites, MySQL or PostgreSQL are recommended for guaranteed compatibility and performance.

The database requirements are relatively lightweight overall. Even large databases with millions of rows of data can handle the extra tables required by the plugin without issue.

Downloading and Installing

Accessing Plugin Store

To download the Template Comments plugin, you first need to access the official Craft Plugin Store. This is available directly within the Craft CMS control panel for straightforward access.

Simply log into your Craft site's control panel using your admin credentials. Along the left sidebar, click on "Plugin Store" under the "Settings" heading. This will bring up the store interface showing all available plugins for Craft.

In the search bar at the top, enter "Template Comments" to filter for this specific add-on. Select it from the results to bring up the plugin page.

Downloading the ZIP File

On the Template Comments plugin page, you'll see a brief description along with user reviews and details. To get the plugin, click the bright blue "Download" button on the right side.

This will automatically download the plugin as a ZIP file, typically called "template-comments.zip" with a file size around 500KB. The ZIP contains the plugin code and documentation needed to install it.

Save the .zip file to your computer ready for upload into your Craft site.

Uploading and Installing

With the plugin ZIP file downloaded, head to your Craft admin and go to "Settings" > "Plugins" from the left sidebar. On this page, you can manage all your site's plugins.

Near the top right, click the "Install plugin" button. This will bring up a modal prompt allowing you to upload the ZIP.

Click "Choose file" and select the "template-comments.zip" file you downloaded. Once selected, click "Install" to upload and install the plugin.

After a moment, Template Comments will be successfully installed. A confirmation message will appear and the plugin will now be listed along with all other active plugins.

The final step is to click the "Enable" button for Template Comments to activate it. And that's it - the plugin is now installed and ready to use! You can start adding comments to your templates right away.

Global Configuration

Accessing Settings Panel

The Template Comments plugin comes with a few global configuration options that can be accessed from the control panel sidebar.

To access the settings, go to the "Settings" tab in the Craft CMS admin sidebar. Then click on "Template Comments" to open the plugin settings panel.

This will display the available options to tweak the plugin functionality as needed for your specific site.

General Settings

The General settings include basic options for enabling/disabling Template Comments along with setting up core functionality.

The first option allows you to globally enable or disable the plugin across the entire site. Unchecking this will turn off all template comments functionality.

There are also settings for requiring user login to post comments, enabling comment replies, allowing anonymous comments and more. These give control over the core comment features.

Additional options include setting a default comment status and configuring approval workflows. Overall, the General settings cover the basic plugin configuration needed for most use cases.

Advanced Settings

For more advanced users, the Template Comments plugin provides additional options via the Advanced settings tab.

This includes cache settings to fine-tune caching of comments for optimal performance. Caching can be disabled or custom TTLs can be set per content type.

Debug settings are also available to log errors or plugin events for troubleshooting. Optional error notifications and logging can assist developers with squashing bugs.

For full customization, the plugin offers a "Template Comments" variable that exposes all available settings and objects. This gives developers low-level control for complex implementations.

The Advanced settings ultimately provide deeper control for expert users with more complex needs. But for most sites, the General settings have all the necessary configuration options.

Template-Specific Settings

Enabling Comments

While the plugin can be enabled globally, Template Comments also allows granular control over comment functionality per template.

Within any template, you can output the {{comments}} tag pair to display comments.

However, this will have no effect unless comments are enabled for that specific template.

To enable comments for a template, go to Settings > Template Comments in the Craft admin sidebar. Here you can check/uncheck templates to override the global settings.

For example, you may want to disable comments on contact or legal pages even if enabled globally. The template settings make this easy.

There are also options to close or delete comments on a template while retaining previous comments. This allows existing discussions to remain visible.

Display Settings

The plugin provides template-specific display settings to customize how comments appear for individual templates.

For example, you can set the ordering of comments - newest first, oldest first, or random. Or choose between pagination or infinite scroll loading.

Formatting options are also available on a template basis, like toggling between threaded or flat comment views. Nested reply indents can be controlled too.

Advanced settings allow devs to override templates for functionality like comment forms and rendering. But the display options cover most visual configuration needs.

Custom CSS/Design

To seamlessly match the visual design, custom CSS can be applied to comments on a per-template basis.

Under each template's settings, there is a "Custom CSS" textarea field available. This allows adding any CSS overrides to fine-tune the styling of comments.

Simple tweaks like colours, typography, margins, etc can alter the look and feel. More complex rules can change layouts, add animations, and more.

This enables the comments to blend right into the template without inconsistencies. The custom CSS option is invaluable for perfecting the styling.

Displaying Comments

Comment List Template

To display comments on the front-end, the Template Comments plugin utilises two templates - one for the list and one for individual comments.

The _comments/list template renders the full list or stream of comments. It handles the wrapping container along with overall styling, pagination, etc.

Within this list template, each comment is rendered via the _comments/comment sub-template which outputs the markup for a single comment.

Separating these concerns into discrete templates allows for easier customization and formatting of the output.

Individual Comment Template

The _comments/comment template is used to display each individual comment. It outputs the comment author, text, date, and any other meta information.

This template is called automatically from within the list template when looping through the comments to display. It does not need to be called directly.

However, it can be fully customized to alter the markup and styling for each comment. Tweaking this template enables full control over the frontend appearance.

Conditionals can also be added to check for current user, admin status, etc. to alter the rendered output where needed.

Display Code Example

Displaying comments in a template only requires the {% comments %} tag pair. For example:

{% comments for="entry" %}

{% endcomments %}

This will output the full list of comments for the current entry using the default templates and settings.

To customize, the templates can be explicitly set:

{% comments for="entry" listTemplate="customList" commentTemplate="customComment" %}

{% endcomments %}

Additional options like disabling, limiting, sorting etc. can also be passed to the tag pair. But the above covers the basic usage.

Comment Moderation

Enabling Moderation

The Template Comments plugin offers robust tools to moderate and manage incoming comments. This allows site admins to maintain quality discussions.

Moderation can be enabled globally from the plugin's settings, requiring all comments to be approved before publishing. Or it can be enabled on a per-template basis.

Per-template moderation allows granular control, like requiring approval only on public-facing pages but not private support topics. The flexibility is invaluable for dialling in moderation needs.

For blogs or other high-engagement areas, pre-approving comments avoid spam and abuse while supporting active conversations.

Moderation Workflow

When moderation is required, submitted comments will have a "pending" status and be held for review. Site admins are notified to approve or reject the comments.

In the Craft admin area, there is a Template Comments section that lists all pending comments. Admins can approve, edit, or delete submissions with ease.

Bulk moderation options are also available for times when there are many pending comments to manage. Comments can be flagged if unsure for another set of eyes.

Email and web notifications keep admins in the loop on pending comments requiring action. The workflow ensures no input falls through the cracks.

Additional Moderation Options

For advanced needs, optional spam detection and blacklists can automatically flag or block suspect comments during moderation.

Akismet integration brings robust spam analysis. Plus custom word/email blacklists offer flexible protections beyond spam.

Admins can also close or disable comments on individual entries once discussion is finished. This avoids having to delete previous comments entirely.

Between granular controls, anti-spam measures, notifications, and bulk actions, the moderation toolset enables a clean, high-value discussion area on any site.

Managing Existing Comments

Editing Comments

Once comments are published, moderators still have tools to manage them. The Template Comments CP section lists all existing comments.

From here, moderators can edit the text, author name, email, and metadata for any comment. Just click the pencil icon for the comment.

A modal will appear allowing edits to the comment details. When done, click "Save" and changes will be applied instantly.

Edits are logged so moderators can track changes over time if ever needed. It offers transparent comment management.

Removing Comments

To delete unwanted or inappropriate comments, moderators again can use the main Template Comments CP section.

Find the comment and click the trash can icon. You'll be prompted to confirm deleting the comment. This will permanently remove it.

Deleting is immediate and irreversible, so the plugin asks for confirmation as a safeguard. But it enables cleaning up unwanted discussion.

Remove permissions can also be assigned to certain user groups as needed. Not all admins may require comment management access.

Flagging/Reporting Comments

For sites accepting anonymous comments, users can flag inappropriate comments for moderator attention using a quick form.

The interface allows picking a reason like "spam", "offensive", etc. to help categorize the report for review.

Flagged comments are highlighted in the CP so moderators can investigate and take action based on the report details.

Enabling user flagging empowers the community to self-police and maintains a high bar for discourse even with anonymous commenting.

Integration With Other Plugins

Compatibility List

The Template Comments plugin aims for seamless integration with the wider Craft ecosystem of plugins.

It is officially compatible with several popular plugins including:

• Craft CMS SEO (for adding SEO fields to comments)

• Redactor (for rich-text comment fields)

• Smart Map (for location-based commenting)

• Akismet (for advanced spam filtering)

The plugin code is developed to play nicely with common Craft plugins and avoid conflicts. Continued compatibility updates are planned as well.

Integration Guide

For key plugins, the Template Comments docs provide detailed integration guides:

• Syntax Highlighter - Adds code block formatting to comments.

• Social Logins - Allow comment login via Facebook/Twitter/Google.

• Salesforce - Syncing comments with Salesforce accounts and contacts.

These walk-through setup steps, template configuration, and customization options for deep integration.

Code samples are provided where applicable. The goal is to make integrating with essential plugins simple for developers.

Customization/Hooks

For ultimate customization, Template Comments offers a robust set of hooks allowing developers to respond to events and extend functionality.

Actions are provided for key points like when a comment is saved, approved, flagged, etc. Filters allow modifying rendered HTML, email notifications, and more.

The hooks enable developers to tweak functionality to meet the needs of custom implementations. Events can trigger external updates, notifications, analytics, or any other logic imaginable.

Between official compatibility testing, detailed guides, and custom hooks, the plugin is built to play nice with the rest of the Craft ecosystem.

Troubleshooting

Installation Errors

When installing the Template Comments plugin, there are a few common errors that may appear:

• Invalid ZIP file - This means the downloaded ZIP file is incomplete or corrupt. Re-download a fresh copy and retry.

• Craft version conflict - The plugin requires Craft 3+ to function. Upgrade Craft first before installing.

• PHP version too low - Double check your server PHP version meets the 5.6+ requirement and upgrade PHP if needed.

• Database error - Some servers may block the database changes needed to install the plugin. Contact support for assistance bypassing.

Following the basic requirements and ensuring all your plugins are updated should avoid initial installation issues in most cases.

Display Problems

If comments aren't displaying properly on the front end, here are some things to check:

• Comments enabled for template? Double-check the settings.

• Correct template tag usage - Verify {% comments %} tags are correct.

• Template caching issue - Try clearing caches.

• Permissions error - Check user group permissions are set properly.

Enabling the debugging setting can provide more clues by logging errors and exceptions during display. This helps narrow down template conflicts, caching problems, etc.

Performance Issues

If the plugin seems slow, there are a few performance optimizations to try:

• Enable caching - Use Redis or database caching for comments.

• Use eager loading - Enable eager loading of relations in plugin settings.

• Limit comments displayed - Only display 10-20 recent comments versus all.

• Optimize DB tables - Inspect indexes/table schema for optimizations.

• Cache comment HTML - Cache rendered HTML snippets for repeated display.

Between database and frontend caching options, performance can be tuned significantly. It's a matter of finding the optimal settings for each unique site.