Comments

Comment Service Overview

A comment service was added in Telligent Evolution 7.0. This service adds support for third-party developers to add comment functionality to content or web pages. It includes an approval state to allow moderation. The comment service is available through the API, REST, and widgets.

Comments for blog posts, media, and wiki pages take advantage of this new service and are still made available through their individual APIs and endpoints.

Commentable content

Comments can be made on most content types within the Telligent Evolution Platform. External, Url-based content can be commented on without any extra support required by the developer. For local content (where a ContentId and ContentTypeId is used) to be commented on, a plugin supporting that content type must be enabled and must implement the ICommentableContentType interface. The interface simply defines permission checks for commenting.

public interface ICommentableContentType : IContentType
{
	bool CanCreateComment(Guid contentId, int userId);
	bool CanReadComment(Guid commentId, int userId);
	bool CanModifyComment(Guid commentId, int userId);
	bool CanDeleteComment(Guid commentId, int userId);
}

The IContentType interface defines additional methods and properties required to support content. See the ContentType documentation for further information.

How to

In-Process API

The comment service is available to the API through the Telligent.Evolution.Extensibility.Api.Version1.PublicApi.Comments interface. More information can be found here.

Along with the standard create, retrieve, update, and delete methods, an event interface is exposed. Events include before and after events for creates, updates, and deletes as well as a render event. Permission checks are also exposed to test if a user has permission to interact with comments.

REST

The comment service exposes several REST endpoints to work with. Create, show, list, update, and delete for comments are all supported through REST. Find the full details for the REST endpoints, parameters, and responses on the REST documentation.

Important Note: Developers need to be aware of a security risk with comments. Sometimes, business logic is done procedurally during the create or update process. This should be avoided for comments, since there is a generic API that can be used to create a comment for your application which could bypass your business logic. For example, if your application needs to perform a check to approve a comment, that check should not be done procedurally during the comment creation code because a comment REST request could be made that includes IsApproved=true. To avoid this issue, perform the business logic in an event handler that subscribes to the appropriate comment event and works on your specific ContentTypeId. This way users cannot bypass your logic by using the generic APIs.
Permission checks are also available through REST.

Widget extensions

The comment service is exposed to widgets and email templates via the $core_v2_comments extension. More information is available through the Widget and Email API documentation.

Advanced Concepts

There are several additional ways to use comments beyond creating, updating, listing, and deleting them. The follow explains some of the more advanced ways of using comments.

Replying to a comment

Comments can not only be made on content but users can also reply to comments and the replies are also comments. A comment can have multiple replies but users cannot reply to replies; this is illustrated in the table below.

Supported	Not Supported
Content Comment Reply Reply	Content Comment Reply Reply

Adding replies to comments is done by creating another comment on the content but settings the ParentCommentId to the CommentId of the comment being replied to. For example:

PublicApi.Comments.Create(Content.ContentId, Content.ContentTypeId, "reply body",
	new CommentCreateOptions {ParentCommentId = ParentComment.CommentId});

Types of Comments

Comments can have a CommentTypeId designation that can be used to differentiate a type of comments on a piece of content from other types. For example, if for a blog post comments made via the activity stream wanted to be differentiated from comments made on the post itself, the activity stream could specify one CommentTypeId when creating comments while the blog post page could specified a different CommentTypeId for comments made from it. Then, when getting the list of comments on the blog post, each location would request only comments with its CommentTypeId. The following code uses the In-Process API to create a new comment with a CommentTypeId (the one used in the example isn't special, any GUID will work) on a blog post and also retrieve comments on the blog post matching the CommentTypeId.

Guid hypotheticalActivityStreamTypeId = new Guid("0ADC5E17-5237-4341-B3CA-952A54449F69");

Comment newComment = PublicApi.Comments.Create(BlogPost.ContentId, 
	PublicApi.BlogPosts.ContentTypeId, 
	"Comment via activity stream.",
	new CommentCreateOptions { CommentTypeId =  hypotheticalActivityStreamTypeId});

PagedList<Comment> comments = PublicApi.Comments.Get(new CommentGetOptions
	{
		ContentId = BlogPost.ContentId,
		ContentTypeId = PublicApi.BlogPosts.ContentTypeId,
		CommentTypeId = hypotheticalActivityStreamTypeId
	});

Ordering Comments

Comments support ordering to move certain comments up or down in relation to each other. This is done using the SortOrder property on the comment. Comments are sorted first by SortOrder, and then by date. SortOrder defaults to 0 for all comments. Comments with a higher SortOrder will be returned before comments with a lower SortOrder. When the SortOrders are equal between two comments, the date is used to determine order, oldest first.

PublicApi.Comments.Create(Content.ContentId, Content.ContentTypeId, "Comment body.",
	new CommentCreateOptions {SortOrder = 10});

Featured Comments

Similarly to ordering, comments can be marked as Featured. Featured comments can be used to distinguish certain comments from others. One possible use is to distinguish comments made by the content author. Any comments made on a blog post by the post author, for example, could be marked as featured and then the comment list widget could add a special border around those comments when displaying them. Comments cannot be featured when they are created but can be updated to be featured. The below code uses the In-Process API to create a comment and set it as featured. It also gets a list of featured comments on a piece of content.

Comment comment = PublicApi.Comments.Create(Content.ContentId, Content.ContentTypeId, "Comment body.");
PublicApi.Comments.Update(comment.CommentId, null, new CommentUpdateOptions {IsFeatured = true});

// This will only return featured comments
PagedList<Comment> featuredComments = 
	PublicApi.Comments.Get(new CommentGetOptions {ContentId = Content.ContentId, IsFeatured = true});

Developer Space