Ext: sg_comments

License: GNU GPL, Version 2

Repository: https://gitlab.sgalinski.de/typo3/sg_comments

Please report bugs here: https://gitlab.sgalinski.de/typo3/sg_comments

TYPO3 version: >=9.5

About

sg_comments is a powerful comment system, used by sg_news and sg_events.

Integration

  1. Install the extension sg_ajax 1.0.0 or higher.
  2. Install this extension.
  3. Check, that the node_modules are up to date, by executing npm install in the extension folder.
  4. Add the static TypoScript template "Comment System" to your root template.
  5. Make sure the static template of sg_news is loaded before the sg_comments TypoScript.
  6. Configure the extension in the TypoScript Frontend/setup.txt depending on your needs.

    First, make sure that the following two values are configured in your TYPO3 instance:

     $GLOBALS['TYPO3_CONF_VARS']['MAIL']['defaultMailFromAddress']
     $GLOBALS['TYPO3_CONF_VARS']['MAIL']['defaultMailFromName']
    

    A list of all possible settings:

     settings {
         # If it's true, then all new comments needs to be approved in the backend module.
         moderateNewComments = 0/1
    
         # Define the moderator email addresses
         moderators =
    
         # Additional recipients will get a mail for each new approved comment.
         additionalMailRecipients =
    
         # The comment date format in the frontend
         relativeDate.absoluteFormatFallback = %d.%m.%Y
    
         # The prefix for each comment id.
         commentAnchorPrefix = thread-comment
    
         # The amount of chars, which a comment can show, until it will be cropped.
         maxAmountOfCommentCharsBeforeCrop = 200
    
         # The id and the name of the honeypot field
         hiddenFieldName = authorDoNotFill
    
         # The class of the element, which is containing the honeypot field
         hiddenField = hidden
    
         # Default settings for a comment thread
         commentThread {
             # A comment type, which is registered by the following function: "\SGalinski\SgComments\Service\CommentTypeService::registerCommentType()"
             commentType = pages
    
             # Thread identifier (Needs to be set, if a site has multiple threads. This must be unique.)
             threadPrefix =
    
             # Enable notify me (The users will be notified, if he allows it, as soon as a new comment was posted.)
             notify = 0/1
    
             # Enables the possibility to create answers on comments.
             enableReplies = 0/1
    
             # Only logged in users are able to write comments
             loginRequired = 0/1
    
             # Respect language (Shows only comments with the selected language in the frontend)
             respectLanguage = 0/1
    
             # Disable the moderation for this thread
             disableModeration = 0/1
    
             # New comments are on the top
             newCommentsOnTop = 0/1
    
             # Close this thread for new comments
             closeThread = 0/1
    
             # Slim view (removes message count and notifications)
             slimForm = 0/1
    
             # Email address requried for non-logged-in users
             emailRequired = 0/1
         }
    
         # File upload settings
         fileUpload {
             # Enables the file upload
             enabled = 1
    
             # Max amount of files, which could be uploaded in one comment
             amountOfFiles = 25
    
             # A list of file types, which are allowed for the uploader
             fileTypes = gif, jpg, jpeg, pdf, png
    
             # The folder in the fileadmin, where the files are saved.
             fileadminFolder = sg_comments
         }
    
         # Rest settings
         rest {
             # The default storage pid, if the given storage pid is less or equals to 0.
             defaultStoragePid = 1
         }
     }
    
  7. Add the "Integration Code" to the extension of your choice. There are two possible ways to do this:

    #### Viewhelper Usage

    Example usage:

      {namespace sgc=SGalinski\SgComments\ViewHelpers}
      <sgc:commentThread commentType="pages" threadPrefix="foo" notify="TRUE" fileUpload="TRUE" />
    

    Arguments:

    • commentType (string): Configure the comment type for the thread
    • threadPrefix (string): Prefix for the thread identifier
    • notify (boolean): Enables notify me feature
    • fileUpload (boolean): Enables file uploads
    • fileTypes (string): Comma seperated list of file types
    • amountOfFiles (integer): Amount of files allowed
    • maxfileSize (integer): The maximum file size in MB. 0 means infinity.
    • respectLanguage (boolean): Respects the language for the comments
    • enableReplies (boolean): Enables the reply feature
    • loginRequired (boolean): Enables that the user needs to be logged in
    • disableModeration (boolean): Disables the moderation for this thread
    • newCommentsOnTop (boolean): Newest comments are on the top
    • closeThread (boolean): Closes a thread
    • format (string): Request format for the comment index action

    ###### Format/SubstringViewHelper Enables the usage of the php substr method in a Fluid template.

    The parameters are exactly the same as in the php function.

    Example usage:

      {namespace sgc=SGalinski\SgComments\ViewHelpers}
      <sgc:substring string="abcdef" start="0" length="-1" /> // returns "abcde"
    

    ###### Format/UrltolinkViewHelper Renders URLs as Hyperlinks.

    Parameters:

    • rel:

      The resource the link should point to.

    • target:

      How should the link be opened on click ?

      Following values are possible:

      _blank: Opens the linked document in a new window or tab.

      _self: Opens the linked document in the same frame as it was clicked (this is default).

      _parent: Opens the linked document in the parent frame.

      _top: Opens the linked document in the full body of the window.

    Example usage:

      {namespace sgc=SGalinski\SgComments\ViewHelpers}
      <sgc:urltolink rel="https://www.sgalinski.de/stylesheet.css" target="_blank" />
    

    ###### AddCssFileViewHelper Allows to add a css file to your Fluid template.

    Example usage:

      {namespace sgc=SGalinski\SgComments\ViewHelpers}
      <sgc:addCssFile cssFile="styles/stylesheet.css" />
    

    ###### AddJavaScriptFile Allows to add a JavaScript file to your Fluid template.

    Example usage:

      {namespace sgc=SGalinski\SgComments\ViewHelpers}
      <sgc:addJavaScriptFile javaScriptFile="scripts/MyScript.js" />
    

    #### TypoScript Integration

    These are the available TypoScript libraries.

     lib.sgCommentsIndex               (Shows the comments of the current page)
     lib.sgCommentsNew                 (Renders the form, where the user can create comments)
     lib.sgCommentsGetCount            (It shows the count of comments of this page)
     lib.sgCommentsGetCountWithLabel   (It shows the count of comments of this page with a localized label)
    

    Example usage:

     <f:cObject typoscriptObjectPath="lib.sgCommentsIndex" />
    
  8. (Optional) Edit the email templates.

    You can adapt these templates by editing language labels within the following files:

     typo3conf/ext/sg_comments/Resources/Private/Language/[languageKey].locallang.xlf
    

    ##### Used language labels

    The approved comment email, which the comment creator gets.

     Labels:
     backend.approvedMailSubject
     backend.approvedCommentMailText
    
     Available Markers:
     ###USERNAME###          = The comment author
     ###DATE###              = The creation date of the comment
     ###COMMENT###           = The comment text
     ###LINK_TO_COMMENT###   = The link to the comment in the frontend
    

    The email, which the comment creator gets, if the comment is deleted.

     Labels:
     backend.deletedMailSubject
     backend.deletedCommentMailText
    
     Available Markers:
     ###USERNAME###          = The comment author
     ###DATE###              = The creation date of the comment
     ###COMMENT###           = The comment text
     ###LINK_TO_COMMENT###   = The link to the comment in the frontend
     ###REASON###            = The reason, why the comment was deleted
    

    The email, which all moderators will get, after a new comment is created, if the moderation system is activated.

     Labels:
     frontend.mailSubject (Be careful same as the default mail)
     frontend.authorMailText
    
     Available Markers:
     ###USERNAME###          = The comment author
     ###DATE###              = The creation date of the comment
     ###COMMENT###           = The comment text
     ###LINK_TO_COMMENT###   = The link to the comment in the frontend
    

    The email, which all users within a page will get, if a new comment is created or approved.

     Labels:
     frontend.mailSubject (Be careful same label as the moderator email)
     frontend.mailText
    
     Available Markers:
     ###USERNAME###          = The comment author
     ###DATE###              = The creation date of the comment
     ###COMMENT###           = The comment text
     ###LINK_TO_COMMENT###   = The link to the comment in the frontend
    
  9. Clear the caches.

File access

By default, direct access to file attachments (e.g. calling the url directly) is prevented. These files are still accessible by the user who uploaded them! If you want to whitelist a filetype you need to add the file extension to the pipe seperated list of allowed filetypes in the extension settings.

The following filetypes are whitelisted after installing sg_comments:

png,gif,bmp,ico,jpeg,jpg,ps,psd,svg,tif,tiff,dds,pspimage,tga,3g2,3gp,avi,flv,h264,m4v,mkv,mov,mp4,mpg,mpeg,rm,swf,vob,wmv,aif,cda,mid,midi,mp3,mpa,ogg,wav,wma,wpl

The backend module

With the Comments module you can filter by the nesting level inside a comment and/or by approvement status of the comments and editors have different options to moderate the comments depending on the configuration.

Approve the comment
View the comment
Delete

The frontend plugin

sg_comments also comes with a plugin that renders a thread in your frontend.

Settings

General

Mode

There are two different modes:

  • Page comments: The default mode. Use this if you want a thread identifier with just a simple text. An empty identifier will be replaced with the current page id.

  • Extension comments: This mode will change, how the thread identifier is generated. With this option you can use POST/GET variable names comma-separated within your thread identifier. These names will be automatically replaced, if a user opens a site with these variables. The variable name will just be replaced, if it exists, otherwise the variable name will be visible in the identifier.

Enable notify me

The user has the opportunity to enable notifications about new comments.

Respect language

If selected, only comments with the selected frontend language will be shown.

Save frontend user

If selected, the comment will be associated with the user object (if logged in).

Thread identifier

A unique identifier for your Thread. Only necessary if you have multiple instances of a thread on a single page.

Appearance

New comments are on the top

Option to show comments at the top of the thread instead of the bottom.

Slim view

If selected, the message count and notifications won't be shown in the Thread.

Max. characters visible

Determines how many characters are displayed, before the comment is cropped. You can still expand a cropped comment to its full length. If the max. character count is 0, nothing will be cropped.

Autogrow

By default, the textarea where the user enters his comment uses autogrow. You can disable the autogrow feature, by adding the class disable-autogrow to your textarea.

Administration

Only logged in users are able to write comments

If selected, only logged in users can write and answer comments.

Enable replies

Block or enable replies to a comment

Disable moderation

Comments don't need to be approved anymore if this option is selected.

Close this thread for new comments

Prevent new comments in this thread.

File-Upload

Enable file upload

If file upload is enabled the following settings are in effect.

Max amount of files

Determine how many files a user can upload.

File extensions

A comma seperated list of allowed file extensions. If a file extension is not allowed, the user will be noticed

The max file size

Determine the maximum file size. If set to 0, the server settings are in effect.

REST API

A REST is already integrated. It requires the extension sg_rest. Once installed the following call

https://www.website-base.dev/?eID=sgRestApi&request=comments/comment/list

should return the message "{"message":"Auth token was not provided or was invalid."}" This happens, because the required POST data argument "authToken" is missing. See the README.md in the sg_rest extension for more information.

Breaking changes

With version 3.0 the following changes will break TYPO3 instances that had older versions of sg_comments before the upgrade:

No TYPO3 6.2 support anymore

The code to ensure running sg_comments in TYPO3 versions older than 7 have been removed.

Create comment template forms

As seen in the template sg_comments/Resources/Private/Partials/NewComment.html, the form fields in the create comment form now use the name instead of the value attribute. Doing otherwise will result in unpredictable caching behaviour.

After changing the attributes, please check if the index of the resulting POST array still matches.

sg_mail Templates

Since sg_comments requires the installation of sg_mail 4.1 and above, the whole process of registering your mail templates has changed. Please see the sg_mail documentation on further information.

How to initilize the new lightbox

After integrating the `project_theme_lightbox` extension you can change your import and initialization function in your main theme.

import SgComments from 'sgComments';
SgComments.init();

File download lightbox

For the lightbox feature of a comment file to work, you need to supply an additional class popup-image to the tag within your template that renders the attached files.