Table of Contents

  1. Ext: sg_comments
  2. Version 9 Breaking Changes

Ext: sg_comments

sgalinski Logo

License: GNU GPL, Version 2 Repository: gitlab.sgalinski.de/typo3/sg_comments

About

sg_comments is a powerful, threaded comment system for TYPO3. It supports replies, moderation, email notifications via sg_mail, and file uploads. It is also the underlying comment system for sg_news.

Installation

  1. Install the extension via composer: 
    composer require sgalinski/sg-comments
  2. Include the static TypoScript template "Comment System" in your root template.
  3. If you use sg_news, ensure its static template is loaded before sg_comments.
  4. Configure the extension via TypoScript (see below) or in the extension configuration.

Integration

ViewHelper Usage

The easiest way to integrate a comment thread is using the CommentThreadViewHelper:

{namespace sgc=SGalinski\SgComments\ViewHelpers}
<sgc:commentThread commentType="pages" threadPrefix="my-unique-prefix"/>

Arguments

  • commentType (string): The type of comments (default: pages).
  • threadPrefix (string): Unique identifier for the thread.
  • notify (bool): Enable the "Notify me" feature.
  • fileUpload (bool): Enable file uploads.
  • respectLanguage (bool): If true, only comments in the current language are shown.
  • enableReplies (bool): Allow users to reply to comments.
  • loginRequired (bool): Only logged-in users can post comments.
  • disableModeration (bool): Skip the moderation queue.
  • newCommentsOnTop (bool): Show newest comments at the beginning.

TypoScript Libraries

For integration in Fluid or TypoScript:

  • lib.sgCommentsIndex: Renders the full comment thread.
  • lib.sgCommentsNew: Renders only the comment form.
  • lib.sgCommentsGetCount: Returns the total comment count.
  • lib.sgCommentsGetCountWithLabel: Returns the count with a localized label.
  • lib.sgCommentsGetAverageRating: Returns the average rating (if enabled).

Example:


<f:cObject typoscriptObjectPath="lib.sgCommentsIndex"/>

JavaScript Initialization

To initialize the frontend components (replies, uploads, lightbox), import and call the initialization in your main JavaScript entry point:

import SgComments from 'EXT:sg_comments/Resources/Public/JavaScript/sgComments.js';

SgComments.init();

Frontend API

The frontend widgets use public sg_apicore routes. Custom integrations should generate URLs with the api:uri.api ViewHelper and use JSON requests for comment creation and subscriptions. Uploads remain multipart form data with the file in the files field. See UPGRADE.md for the endpoint list and migration payload.

Configuration

Global Settings (TypoScript)

You can customize the behavior in plugin.tx_sgcomments.settings:

plugin.tx_sgcomments.settings {
	# Require moderation for new comments
	moderateNewComments = 1

	# List of moderator email addresses
	moderators = moderator@example.com

	# Date format in frontend
	relativeDate.absoluteFormatFallback = %d.%m.%Y

	# File upload settings
	fileUpload {
		enabled = 1
		amountOfFiles = 5
		maxfileSize = 10 # in MB
		fileTypes = jpg, png, pdf
	}
}

E-Mail Templates (sg_mail)

This extension uses sg_mail for all notifications. The templates are registered automatically and can be edited in the Mail Templates backend module.

Available Templates:

  • approved: Sent to the author when a comment is approved.
  • commentators: Sent to users who subscribed to a thread.
  • declined: Sent to the author when a comment is rejected.
  • disapproved: Sent when a previously approved comment is hidden.
  • moderator: Sent to moderators when a new comment is posted.

Common Markers:

  • {USERNAME}: Author of the comment.
  • {COMMENT}: The comment text.
  • {LINK_TO_COMMENT}: Link to the specific comment in the frontend.
  • {DATE}: Creation date.

Backend Module

The Comments backend module allows editors to moderate, view, and delete comments across the entire TYPO3 instance. It provides filters for approval status and nesting levels.

Version 9 Breaking Changes

  • The backend warning for sg_comments:checkConsistence now lets administrators create or activate the task. The recommended task runs daily at 02:45; review the schedule in the Scheduler module after deployment.

  • sg_comments no longer depends on sg_consistence. Run the Migrate sg_consistence scheduler task for sg_comments upgrade wizard before removing that extension. The wizard preserves the old task's schedule and activation state and replaces it with sg_comments:checkConsistence.

  • If sg_account is installed as well, run its corresponding scheduler migration wizard too. Verify that both dedicated commands are scheduled and that sg_consistence:checkConsistence no longer exists.

  • If the legacy task was disabled, enable the migrated tasks explicitly after validating their schedules.

  • TYPO3 14.3 or newer is required for this major version.

Upgrade to TYPO3 14

  • sg_comments no longer registers sg_ajax endpoints. sgalinski/sg-apicore is required by the extension.
  • Replace custom legacy page-type requests with the public API routes below. JSON requests must send Accept: application/json; errors outside normal comment field validation are RFC 7807 Problem JSON.
    • GET /api/public/v1/comments/altcha/challenge
    • POST /api/public/v1/comments
    • multipart POST /api/public/v1/comments/uploads with the file in the files field
    • POST /api/public/v1/comments/subscriptions
  • The comment-create request accepts the rendered form data as a JSON payload: comment, optional commentThreadSettings, files, notifyMe, altcha, and honeypot. Uploaded files return an opaque path identifier; pass this identifier back in files, and do not expose or rely on absolute server paths.
  • If you override NewComment.fluid.html or NotifyMe.fluid.html, replace legacy AJAX URI ViewHelpers with <api:uri.api path="/comments" />, <api:uri.api path="/comments/uploads" />, and <api:uri.api path="/comments/subscriptions" />. The AltchaViewHelper already creates the new challenge URL.
  • Clear TYPO3 caches and test comment creation, ALTCHA, file uploads, replies, and subscription toggles in every site.
  • No extension-specific manual migration is required for this release.
  • Review any project-specific overrides or integrations that depend on internal templates, JavaScript modules, hooks, events, middlewares, or PHP APIs provided by this extension.

Version 8 Breaking Changes

  • Dropped TYPO3 12 support
  • Dropped PHP 8.0, 8.1 and 8.2 support

Version 7 Breaking Changes

  • Dropped TYPO3 10 and 11 support
  • Dropped PHP 7 support
  • Removed unused SysLanguageService
  • Removed CleanupDuplicateNotificationsUpdate wizard
  • Removed MigrateDefaultUserLanguage wizard
  • Removed Common/setup.typoscript, because it is unused
  • Changed JavaScript files from requireJS to JavaScript modules

Version 6 Breaking Changes

  • Dropped jQuery/Magnific popup implementation
  • Dropped php 7.3 support
  • Dropped TYPO3 9 support
  • Dropped sg_mail 6.x support
  • removed afterIndexAction SignalSlot, migrate to AfterIndexActionEvent
  • removed BeforeBuildUri SignalSlot, migrate to BeforeBuildUriEvent

New main entry point for the JavaScript code:

import SgComments from 'sgComments';

SgComments.init();

Version 5 Breaking Changes

  • Dropped TYPO3 8 support

Version 7 Additional Changes

  • Dropped TYPO3 9 Support
  • removed old non-event dispatches, use Events instead