silverstripe-comments/docs/en/Configuration.md

Configuration

Overview

The module provides a number of built in configuration settings below are the default settings

In order to add commenting to your site, the minimum amount of work necessary is to add the CommentsExtension to the base class for the object which holds comments.

SiteTree:
  extensions:
    - CommentsExtension

Configuration

In order to configure options for any class you should assign the specific option a value under the 'comments' config of the specified class.

SiteTree:
  extensions:
	- CommentsExtension
  comments:
	require_login: false # boolean, whether a user needs to login
	required_permission: false # required permission to comment (or array of permissions)
	include_js: true # Enhance operation by ajax behaviour on moderation links
	show_comments_when_disabled: false # when comments are disabled should we show older comments (if available)
	order_comments_by: '"Created" DESC'
	comments_per_page: 10
	comments_holder_id: 'comments-holder' # id for the comments holder
	comment_permalink_prefix: 'comment-' # id prefix for each comment. If needed make this different
	require_moderation: false
	html_allowed: false # allow for sanitized HTML in comments
	html_allowed_elements:
	  - a
	  - img
	  - i
	  - b
	use_preview: false # preview formatted comment (when allowing HTML). Requires include_js=true
	use_gravatar: false
	gravatar_size: 80

If you want to customize any of the configuration options after you have added the extension (or on the built-in SiteTree commenting) use set_config_value

# Set the default option for pages to require login
SiteTree:
  comments:
    require_login: true

// Get the setting
$loginRequired = singleton('SiteTree')->getCommentsOption('require_login');

HTML Comments

Comments can be configured to contain a restricted set of HTML tags through the html_allowed and html_allowed_elements settings. Raw HTML is hardly user friendly, but combined with a rich-text editor of your own choosing it can allow rich comment formatting.

In order to use this feature, you need to install the HTMLPurifier library. The easiest way to do this is through Composer.

{
	"require": {"ezyang/htmlpurifier": "4.*"}
}

Important: Rendering user-provided HTML on your website always risks exposing your users to cross-site scripting (XSS) attacks, if the HTML isn't properly sanitized. Don't allow tags like <script> or arbitrary attributes.

Gravatars

Gravatars can be turned on by adding this to your mysite/_config.php file

SiteTree:
  comments:
    use_gravitar: true

The default size is 80 pixels, as per the gravatar site if the 's' parameter is omitted. To change this add the following (again to mysite/_config.php):

SiteTree:
  comments:
    gravatar_size: 40

If the email address used to comment does not have a gravatar, it is possible to configure the default image shown. Valid values can be found at http://gravatar.com/site/implement/images/, and at the time of writing are the following:

• 404: do not load any image if none is associated with the email hash, instead return an HTTP 404 (File Not Found) response.
• mm: (mystery-man) a simple, cartoon-style silhouetted outline of a person (does not vary by email hash).
• identicon: a geometric pattern based on an email hash
• monsterid: a generated 'monster' with different colors, faces, etc
• wavatar: generated faces with differing features and backgrounds
• retro: awesome generated, 8-bit arcade-style pixelated faces
• blank: a transparent PNG image (border added to HTML below for demonstration purposes)

To change the default image style, add the following to mysite/_config/config.yml

SiteTree:
  comments:
    gravatar_default: 'retro'

The rating of the image can be changed by adding a line similar to this to mysite/_config/config.yml

SiteTree:
  comments:
    gravatar_rating: 'r'

Vald values for rating are as follows:

• g: suitable for display on all websites with any audience type.
• pg: may contain rude gestures, provocatively dressed individuals, the lesser swear words, or mild violence.
• r: may contain such things as harsh profanity, intense violence, nudity, or hard drug use.
• x: may contain hardcore sexual imagery or extremely disturbing violence.