Installation manual v3

Last updated: May 05, 2021.

This version of CommentBox for SharePoint requires SharePoint v2013 / 2016 / Online. You find an older version here.

Updating from an older version

Most of the settings have changed in this new version, and to update an existing version of cBox you must go trough all settings in the file spjs-cBox_CEWP.html the parameters for configListName and configListBaseUrl replicates the parameters from your existing version. The configListName parameter had a default value of SPJS-CommentBox.

How to install

  1. Download the files from here. This package includes all files necessary for setting up the solution.
  2. Unzip the file and upload all the files to a document library named SPJS where you want to use the solution. The contents of your /SPJS/cBox/ folder should be like this:
    folder: css
    folder: js
    folder: tinymce
    folder: tinymce_ie
    file: spjs-cBox_CEWP.html
  3. Go back to your local download folder and open the file spjs-cBox_CEWP.html and correct all the <link> and <script> tags so that they have the correct “href” and “src” to the files you just uploaded.
  4. Continue editing the file spjs-cBox_CEWP.html to ensure all settings are set up like you want them – you find an overview of all settings below.
  5. Upload and overwrite the file spjs-cBox_CEWP.html in the /SPJS/cBox/ folder.
  6. Copy the full path to the file spjs-cBox_CEWP.html to your clipboard and go to the page where you want your CommentBox to appear. Add a Content Editor Web Part (CEWP) to the page, and edit the web part. Paste the path to the file spjs-cBox_CEWP.html in the Content link field in the web part properties.
  7. Save the changes to your CEWP and refresh the page. Follow the on screen instructions to create the lists used to store comments, likes and subscriptions.

Configuration options

All the configurations is done in the file spjs-cBox_CEWP.html in the variable cBoxArg. You find a description of all options below. The list is sorted alphabetically an I have tried to keep related settings together. You should read trough all settings to see what each setting does.

attachments

type: boolean

Determines whether or not to allow for attachments. Default value: true.

attachmentSizeLimit

type: number

Size limit for attachemnts in MB. Default value: 50 MB.

allCommentsMustBeApproved

type: boolean

If set to true, the comments will only show for users or groups specified in moderatorGroupIDorUserID and the author until they have been approved. Default value: false.

approverEmail

type: array of strings

Array of approver email addresses / login names / SharePoint group display name – you need at least one item here to notify an approver of a new comment.

approvalEmail

type: object

If allCommentsMustBeApproved is set to true, this is the text in the emails sent to the approver to notify about a new comment that needs approval,  and to the author when the comment is approved or rejected.
You find the default setup in the setting in the spjs-cBox_CEWP.htm file.
See separate section below to find the variables you can use to built the email.

authorCanEdit

type: boolean

Author can edit his own comments. Default value: true.

autoSubscribeToRootComments

type: boolean

Should the author of new comments automatically be subscribe to follow-up comments. Default value: false.

categoryEnabled

type: boolean

Show Category field in comments. Default value: true

categoryFIN

type: string

FieldInternalName in the comments list where the category is stored. Only change this if you have an existing list of comments and use another field to store the category. Default value: “Category”.

categories

type: array of strings

If you want to start with a set of predefined categories, add them as strings to this array. Default value: empty array.

categoriesUserDefined

type: boolean

Should the users be able to add new categories? Default value: true.

categoryMandatory

type: boolean

Should the category field be mandatory to fill in? Default value: false.

colorMyComments

type: boolean

Shows a yellow left border on all comments by the logged in user. Default value: false.

commentFIN

type: string

FieldInternalName in the comments list where the comment is stored.  Default value: “Comment”. Only change this if you have an existing list of comments and use another field to store the comment.

configListName

type: string

Name of the list where the comments are stored. You can create new list for comments for each instance of cBox to keep comments separated. Default value: “SPJSCommentBox_v3”.

configListBaseUrl

type: string

Base URL of the site where the comments list should be created. Default value: _spPageContextInfo.webServerRelativeUrl
The default value is a variable provided by SharePoint.

configListHidden

type: boolean

Should the comments list be hidden from browsers when it is initially created? Default value: false. You can toggle the list visible by clicking the cog wheel in the top right corner of the cBox page.

containerWidth

type: string

Width of the comment box. Use px or %. Default value: “100%”.

dateFormat

type: string

New in v3.0.0.7.

Date format for all date values in cBox. Use it like this for 24 hour clock:

"MM/dd/yyyy HH:mm:ss"

or this for 12 hour clock:

"MM/dd/yyyy hh:mm:ss am/pm"

Possible values are:

MMMM = Long month
MMM = Short month
MM = Always two digits in month
M =  Numeric month
dddd = Long day
ddd = Short day
dd = Always two digits in day
d = Numeric day
yyyy = 4 digit year
yy = 2 digit year
mm = minutes
hh = Hour in 12 hour format
HH = Hour in 24 hour format
ss = Second
am/pm = AM or PM indicator

Please note that you must  update spjs-cBox-i18n.js to use MMMM, MMM, dddd and ddd.

Leave empty to use default browser date format

footerRowTemplateOverride

type: string

Possible variables to use:  {id}, {topic}, {category}, {author}, {authorEmail}, {editor}, {editorEmail}, {date}, {time}. You can use HTML code in combination with the variables. Leave empty to use default format. Default value: “”.

footerRowVisible

type: boolean

Should the footer row be visible? Default value: true.

headerRowTemplateOverride

type: string

Possible variables to use:  {id}, {topic}, {category}, {author}, {authorEmail}, {editor}, {editorEmail}, {date}, {time}. You can use HTML code in combination with the variables. Leave empty to use default format. Default value: “”.

iconsHorizontal

type: boolean

The default orientation for the hover-icons on each comment is vertical. Set this to true to show them horizontally. Default value: false.

moderatorGroupIDorUserID

type: array of strings

ID of groups or users with admin / moderator rights. The Site collection admin is automatically moderator and don’t have to be added here. Default value: [].

moveCommentGroupName

type: array of strings

Members in these groups can move a topic – use group id or display name. You must also fill in moveCommentThreadIdArr below.

moveCommentThreadIdArr

type: array of objects

List of possible threadID to move to – example:
[{"disp":"Pending ideas", "threadID":"cBox:/Ideas/SitePages/PendingIdeas.aspx"}, {"disp":"Approved ideas", "threadID":"cBox:/Ideas/SitePages/ApprovedIdeas.aspx"}]

multiInstanceMode

type: boolean

Compatibility setting for old v2 instances of CommentBox where the thread ID used another format. Default value: true.

newTopicButtonPosition

type: string

Show new topic button. Use “top”, “bottom” or “both”. Default value: “top”.

pageSize

type: number

How many topics should be shown in each page?

placeholderID

type: string

Placeholder for this instance of cBox. You must have a HTML tag with this ID in the same page as a placeholder for the commentbox. Default value: “cBox”.

replyLevels

type: number

How many levels deep can the user reply? Default value: 3.

restrictWriteAccessToGroups

type: array of strings

Only let members in these groups comment. Leave empty to let all logged in users comment. Default value: [].

richTextInputUsingTinyMCE

type: boolean

Use rich text comments? If set to true, it will use the TinyMCE rich text editor. This is included in the cBox package and currently use v4.7.6.

searchEnabled

type: boolean

Let the uses search all comments. Default value: true.

searchStringMinLength

type: number

How many characters must be typed in before the search can be performed? Default value: 3

showCategoryInComment

type: boolean

Show the category in the second line of the comment. Set this to false if you for example use a custom first line that includes the category. Default value: true.

showCommentLink

type: boolean

Show link to comment in each comment? Default value: false.

showCatagoryFilter

type: boolean

Show filter select to let the user filer the comments by category. Default value: true.

showLikeButton

type: boolean

Show like button. Default value: true.

showDislikeButton

type: boolean

Show dislike button – you cannot show only the dislike button so the setting showLikeButton must be set to true. Default value: true.

showProfileImage

type: boolean

Show profile image. If this is set to true, clicking the image will open “delve”. Default value: true.

showTopicCount

type: boolean

Show count of topics? Default value: true.

showTopicInComment

type: boolean

Show the topic in the second line of the comment. Set this to false if you for example use a custom first line that includes the topic. Default value: true.

showUserEmail

type: boolean

Show user email in the comment? Default value: true.

sortAscending

type: boolean

Sort comments ascending? Default value: false.

subscriptionEnabled

type: boolean

Enable subscriptions by e-mail? Default value: true.

subscriptionEmail

type: object

If subscriptionEnabled is set to true, this is the e-mail sent out to subscribers.
See separate section below to find the variables you can use to built the email.

textareaHeight

type: number

Height of new comment textarea in pixels. Default value: 100.

textareaVisible

type: boolean

Should the textarea for adding comment show initially, or should the user click a button to show it. Default value: false.

threadID

type: string

Identifier for this instance of CommentBox. The threadID is used to identify the comments based on the page your have added the Commentbox in so that comments added in one page does not appear in other pages using the CommentBox feature.
Leave this empty to use the default identifier: page relative URL and the item ID if it’s a list item.
If you however want to have one commentBox instance shared between multiple pages in your site, change the threadID to a static text string like for example “siteComments”.

threadIDTrimmed

type: boolean

Set this to true to remove some special characters from the threadID. This is necessary in cases where the user can add pages with special characters that are not handled correctly in the REST query used to pull in all comments based on this threadID. When set to true, only the characters matching A-Z, a-z, 0-9, “_”, “:”, ” ” and “/” will be used to identify the comments.

threadIDFIN

type: string

This is the field where the threadID is stored for all comments. Default value is “cBoxID”, but if you upgrade an existing instance of CommentBox you might need to change this to “Title”.

threadInitiallyCollapsed

type: boolean

Collapse nested comments by default? Default value: true

timeZoneCorrection

type: string

Time zone correction in minutes if the created and modified does not show the correct date – leave empty if date is correct. Default value: “”

Get timeZoneCorrection in SharePoint Online using this format:
 "timeZoneCorrection": _spPageContextInfo.webTimeZoneData.Bias + _spPageContextInfo.webTimeZoneData.DaylightBias
Get timeZoneCorrection in SharePoint 2013 using this format:
"timeZoneCorrection": new Date().getTimezoneOffset()

tinyMCE_Language

type: string

TinyMCE language – add more languages to folder /tinymce/js/langs or /tinymce_ie /js/langs. Already in package is “nl”, “de” and “nb_NO” – and the default “en”.

topicEnabled

type: boolean

Show Topic field in comments? Default value: true.

topicFIN

type: string

FieldInternalName in the comments list where the topic is stored.  Default value: “Topic”. Only change this if you have an existing list of comments and use another field to store the topic.

topicMandatory

type: boolean

Should the topic field be mandatory to fill in? Default value: false.

Intercepting adding or updating of comments

New in v3.0.0.6.

This lets you add or update metadata for the comments directly when they are added or updated, or trigger a custom function after a comment has been saved. To use this functionality you must add the functions you like to use to the page where the cBox is located.

cBoxItemAdding

Use this function to intercept the adding of a new comment:

function cBoxItemAdding(placeholderID,item){
// Add or update item attributes for example like this
item.YouCustomColumn = "Your custom value";
// Return the changed item
return item;
}

cBoxItemAdded

Use this function to do something after a comment has been added:

function cBoxItemAdded(placeholderID,data){
// add your custom code here
}

cBoxItemUpdating

Use this function to intercept the updating of a comment:

function cBoxItemUpdating(placeholderID,item){
// Add or update item attributes for example like this
item.YouCustomColumn = "Your custom value";
// Return the changed item
return item;
}

cBoxItemUpdated

Use this function to do something after a comment has been updated:

function cBoxItemUpdated(placeholderID,data){
// add your custom code here
}

Email construction variables

You can use these variables to built the email subject and body.

  • {currentUser} = current user title
  • {currentUserEmail} = current user email
  • {author} = author of comment
  • {authorEmail} = email address of author
  • {editor} = the current editor of the comment
  • {editorEmail} = email address of editor
  • {commentLink} = link to comment
  • {pageLink} = link to page
  • {unsubscribeLink} = link to unsubscribe
  • {topic} = comment topic
  • {category} = comment category
  • {comment} = comment text

These can only be used with the approval functionality:

  • {approveComment} or {rejectComment} = link to approve or reject comment
  • {rejectionReason} = text from textarea in reject comment dialog

Questions and feedback

If you have trouble setting it up, or you have other questions or feedback, you can use the forum.