comments.showCommentsUI JS

Skip to end of metadata
Go to start of metadata

Description

Displays a commenting stream plugin. The plugin enables site users to post comments and have discussions about published content on the site.

Notes:

  • All implementations of the comments plugin use version 2 by default.
  • If you plan on integrating the Comments plugin, we highly recommend reading the Comments Plugin page, which is a step-by-step guide for integrating the Comments plugin and also provides a reference and guide for the various customization options.
  • If you wish to use the plugin for Rating & Reviews please follow the designated guide.
  • We also provide an explanation on  how to make the comments in your Comments plugin searchable using Search Engine Optimization (SEO) Support.

The plugin presents:

  • User login panel or user's profile picture and name for logged in user.
  • Commenting input box.
  • Sharing panel - provides an option to share a posted comment to social networks.
  • Comments stream.

In the  Comments Plugin demo you will find a complete working example that uses the comments.showCommentsUI method. You may view the code, run it and view the outcome.

Plugin's Default Design

The following screen shot presents a Comments plugin in a state of logged in user:

 

UI Customizations

We provide several levels of customization for the Comments plugin's UI:

Please refer to the UI Customizations guide for additional information.

Syntax

 

 

Parameters

The following table lists the available parameters:

 

RequiredNameTypeDescription
containerIDstringAn ID of a <div> element on the page in which you want to display the plugin.
categoryIDstringThe identifier of the Comments Category with which this plugin is associated.
Before embedding a Comments plugin in your site, you are required to create at least one comment category in the Comments Setup page on Gigya's website. When creating a new comment category, a unique categoryID is created. The generated 'Embed code' includes the categoryID. You can use this code to embed the plugin in your site.
streamIDstringIn each category you may define multiple comments streams. Set this parameter with a unique ID of your choice to identify a stream. Note: blank or missing streamIDs will prevent the plugin from loading.
versioninteger

Gigya uses Comments v2 by default.

actionAttributesJSON objectIn Gamification your users receive points for actions they perform on your site, in this case commenting grants the user points. Action Attributes may be used to annotate actions with additional information, such as the section of the web site that generated the action. If you set here the actionAttributes, each time a user adds a comment, the action also receives an attribute, for example "tv-show":"glee", which can mean that the action was performed on the "Glee" page of the site. 
actionAttributes contain a JSON object comprised of a series of attribute keys (categories) with associated values. You can also use a generic "tags" key.

No more than three values can be given, they can be with a single key or each have their own key.

For more information see Variants and Action Attributes. Action attributes are later used to filter GM Plugins by a certain attribute.
Example:  {"<attribute key1>": ["<attribute value1>", "<attribute value2>"],  "<attribute key2>": "<attribute value3>" }

commentTagsarray or stringEither a comma separated list or a JSON array of tags (strings). Each tag in the array (or string) is assigned to the posted comment. Tags can be used to filter comments when calling  comments.getComments, to get only comments that match the tag.
contextobjectA reference to a developer created object that will be passed back unchanged to the event handlers as one of the fields of the eventObj (see extended explanation in the "Plugin Events" section below).
customLangJSON objectThis parameter allows you to set custom texts in the comments plugin. The object is made up of pairs - the key that represents a text element in the UI, with the text to which you want to change:
customLang = {textKey1: text1,textKey2: text2,[...]}
For example:
        params.customLang = {
            num_comments: '%num talkbacks',
            write_a_comment: 'Write a talkback'
        }
The full list of existing keys is available here
deviceTypestringDetermines the type of the device on which the Comments UI is displayed. The parameter supports the following values:
  • desktop (default) - render the Comments UI in regular mode
  • auto - identify the device (user-agent) and if it is a mobile device, render in the mobile view mode
disabledShareProvidersstring A comma-delimited list of share providers that should not be displayed on this plugin as share options. For example, if you would like this plugin to show all providers as share options except for LinkedIn and Twitter, define: disabledShareProviders: "linkedin,twitter". The default value is empty, i.e. none of the providers. Valid provider names include: 'facebook', 'twitter', 'linkedin', 'qq', 'renren' 'sina' .
enabledShareProvidersstringA comma delimited list of share providers to be displayed as Share options when entering new comments. The number of providers that are displayed is set in minShareOptions. The rest of the providers set here are displayed when you click the "More" link. For example, if you would like this plugin to show only the icons of Facebook and Twitter as share options, define enabledShareProviders: "facebook,twitter". The default value is "*", i.e., all the providers. Valid provider names include: facebook, twitter, linkedin, qq, renren, sina.
filterTagsarray or stringEither a comma separated list or a JSON array of tags (strings) that are used to filter comments, only comments that match the tags are to be retrieved.
hideShareButtonsBoolean Indicates whether to hide the share buttons. When set to 'true', the "Share" link under a posted comment will not be displayed. The default value is 'false'.
minShareOptionsintegerThe number of share providers to display as check-boxes in the "Share to" section of the comments UI. The default value is 2.
moreDisabledProviders,
moreEnabledProviders
stringUse these parameters to define which providers are displayed when a user presses the Share button on a published comment (next to "reply"), and also to determine the provider order.  Each parameter is set with a comma separated string of destination names. For example, if you would like the Share to show only the icons of Facebook and Twitter, define: moreEnabledProviders: "facebook,twitter". Email will also be displayed by default. Valid providers include:
delicious, friendfeed, googlebookmarks, microsoft, myaol, stumbleupon, qq, sina, renren, vkontakte, spiceworks, viadeo, nkpl, xing, tuenti, technorati, plaxo, reddit, formspring, tumblr, faves, newsvine, fark, mixx, bit.ly, hatena, ask, amazon, gmail, baidu, box.net, netlog, evernote, aolmail, currenttv, yardbarker, blinklist, diigo, dropjack, segnalo, linkagogo, kaboodle, skimbit, facebook, twitter, googleplus, linkedin, pinterest, mixi, odnoklassniki, douban. (Note: messenger has been replaced by microsoft, however, for backward compatibility, either can be used).
replyUserActionUserAction objectWhen a user posts a reply to a comment, the post may be published to one or more social networks. Also when a user writes a review in Comments in Review mode, the post may be published to one or more social networks. Using this parameter you may customize the feed published to the social networks. The default values of the replyUserAction fields (if not overridden) are:
  • User Message - the reply/review text as posted by the user.
  • Title - "Commented on: " page title.
  • Link Back - the URL of page where the commenting stream is located.
  • Description - no default.
shareUserActionUserAction objectThe user action to publish.
For comments, the userAction fields are mapped as follows: 
  • description - the description field receives the comment text.
  • title - the title field receives the following text: "%userName commented on %pageTitle", when %userName and %pageTitle are placeholders.
  • linkBack - the linkBack field receives the URL of the page where the commenting stream is located.

For ratings&reviews, the userAction fields are mapped as follows: 

  • description - the description field receives the following text: "%username rated %pageTitle as %rating/5
    %commentTitle", when %username, %pageTitle, %rating and %commentTitle are placeholders.
  • title - the title field receives the following text: "%userName posted a review on %pageTitle", when %userName and %pageTitle are placeholders.
  • linkBack - the linkBack field receives the URL of the page where the commenting stream is located.
showLoginBarBooleanIndicates whether to display the login bar above the comments textbox.
streamTitlestringThis title will be assigned for each comment posted to be used for RSS & HTML outputs. The default value of this parameter is the title of the page where the commenting stream is located.
streamTagsarray or stringEither a comma separated list or a JSON array of tags (strings) that should be associated with the stream.
streamURLURLThis URL will be assigned for each comment posted to be used for RSS & HTML outputs. This url will link back from the RSS or HTML page to the original post where the comment was added. The default value of this parameter is the URL of page where the commenting stream is located.
templatesobjectA template is a layout definition for a group of related graphics elements in the plugin. Use this parameter to override the default design of the Comments plugin.
The Comments plugin is divided into template classes, each representing a different graphic element in the Comments plugin. By referencing the classes within each template you can control the order in which classes appear. Once a template is activated, classes within that template which are not referenced will not be displayed.  You can apply CSS to those classes which are displayed. For more information on the templates and a code example see here.
  • commentsPlugin: gig-comments-composebox, gig-comments-header, gig-comments-updates, gig-comments-comments, gig-comments-more
  • header: gig-comments-header-left, gig-comments-count, gig-comments-sort, gig-comments-subscribe, gig-comments-rss,
  • updates: gig-comments-updates-text, gig-comments-updates-link,
  • comment: gig-comment-editbox, gig-comment-edited, gig-comment-editLink, gig-comment-title, gig-comment-photo, gig-comment-username, gig-comment-viaProvider, gig-comment-time, gig-comment-status, gig-comment-body, gig-comment-replyLink, gig-comment-deleteLink, gig-comment-shareLink, gig-comment-repliesArrow, gig-comment-repliesArrow-text, gig-comment-flag, gig-comment-vote-total, gig-comment-vote-pos, gig-comment-vote-neg, gig-comment-replybox, gig-comment-replies, gig-comment-mediaItem
  • composebox: gig-composebox-cancel, gig-composebox-social-login, gig-composebox-site-login, gig-composebox-guest-login, gig-composebox-follow, gig-composebox-close, gig-composebox-title, gig-composebox-logout, gig-composebox-ratings, gig-composebox-photo, gig-composebox-summary-input, gig-composebox-editor, gig-composebox-post, gig-composebox-share-providers, gig-composebox-media-preview
  • myReview: gig-selfreview-nameAndLogout, gig-selfreview-ratings, gig-selfreview-summary-container, gig-selfreview-summary, gig-selfreview-body-container, gig-selfreview-body
includeUIDBooleanIf set to true, the user's UID will be added to the code of the comment div element (see comment templates) as a data-gig-uid attribute.
userActionUserAction objectWhen a user posts a comment, the post may be published to one or more social networks. Using this parameter you may customize the feed published to the social networks. The default values of the userAction fields (if not overridden) are:
  • User Message - the comment text as posted by the user.
  • Title - the title of the page where the commenting stream is located.
  • Link Back - the URL of the page where the commenting stream is located.
  • Description - no default.
  • Media Item - no default.
useHiResIconsBooleanDefault: 'false', uses standard icons. When 'true' icon resolution will be set by the device's pixel ratio. Recommended for mobile displays, for example iPhones with retina display. 
Note: If Gigya's icons are overridden by custom icons and this parameter is set to 'true', it may cause display problems.
useSiteLoginBooleanDetermines whether to use the Gigya default login plugin or the site login. The default value is 'false', meaning the the Gigya default login plugin is used. Read more about adding site login.
widthintegerDetermines the width in pixels of the plugin. The default width is 500 pixels.
Note: 500 pixels is the minimal width for displaying up to 5 thread replies. If you define a less pixels, we advise to limit the number of thread replies and make sure it fits.
Inner Login Plugins' Configuration
enabledProvidersstringA comma delimited list of login providers that should be displayed on this plugin. Valid provider names include: 'facebook', 'twitter', 'microsoft', 'linkedin', 'foursquare', 'renren', 'qq', 'sina', 'vkontakte'.
For example, if you would like this plugin to show only the icons of Facebook and Twitter, define: enabledProviders="facebook,twitter". (Note: messenger has been replaced by microsoft, however, for backward compatibility, either can be used).

Note: This parameter overrides the value of the identical parameter in Global Conf (the global configuration object). If the parameter is not set for the method, the value from Global Conf is used.

disabledProvidersstringA comma delimited list of login providers that should not be displayed on this plugin. Valid provider names include: 'facebook', 'twitter', 'microsoft', 'linkedin', 'foursquare', 'renren', 'qq', 'sina', 'vkontakte'.
For example, if you would like this plugin to show all providers icons but LinkedIn and Twitter, define: disabledProviders="linkedin,twitter". (Note: messenger has been replaced by microsoft, however, for backward compatibility, either can be used).

Note: This parameter overrides the value of the identical parameter in Global Conf (the global configuration object). If the parameter is not set for the method, the value from Global Conf is used.

loginUIConfigstring (XML)An XML string describing changes to the default design of the inner Login plugin. You may change the design with the help of the Login Plugin Wizard. The Wizard lets you modify some settings, while previewing the changes as you make them. Based on your modifications, the Wizard generates code that you can insert into your own application. From the generated code, all you need is the XML string defined after the 'UIConfig' parameter.
sessionExpirationintegerThis parameter defines the time in seconds that Gigya should keep the login session valid for the user. To end the session when the browser closes, please assign the value '0'. If this parameter is not specified, the session will be valid forever.
cidstring
A string of maximum 100 characters length. The CID sets categories for transactions that can be used later for filtering reports generated by Gigya in the "Context ID" combo box. The CID allows you to associate the report information with your own internal data. For example, to identify a specific widget or page on your site/application. You should not define more than 100 different context IDs.

Note: This parameter overrides the value of the identical parameter in Global Conf (the global configuration object). If the parameter is not set for the method, the value from Global Conf is used.

 
 Events Registration Parameters 
onLoadfunction refA reference to an event handler function that will be called when the plugin has finished drawing itself.
onErrorfunction refA reference to an event handler function that will be called when an error occurs.
onBeforeCommentSubmittedfunction refA reference to an event handler function that will be called when the user writes a comment, and just before the onCommentSubmitted  event is fired. This allows the moderator to modify the content of comments before they are submitted to the system by modifying the content of the fields in the event. This also allows the moderator to cancel the comment submission by returning false.
onCommentSubmitted   function refA reference to an event handler function that will be called when the user has submitted a comment.
onComment Votedfunction refA reference to an event handler function that will be called when the user has voted on a comment.
onSiteLoginClickedfunction refA reference to an event handler function that will be called when the user has clicked the site login button. This will enable your site to open a popup or redirect the user for the site login page.
 

 

Plugin Events

An Event Handler is a JavaScript function with the following signature:

functionName(eventObj)

The single argument, eventObj, contains information about the event and has different fields for different events.

The following tables specify the list of fields available in the eventObj for each event:

onLoad Event Data

FieldTypeDescription
   
eventName string The name of the event.
source string The source plugin that generated this event. The value of this field is the name of the plugin's API method, e.g., 'showLoginUI', 'showCommentsUI', etc.
contextobject The context object passed by the application as parameter to the API method, or null if no context object has been passed.

onError Event Data

FieldTypeDescription
   
eventName string The name of the event.
source string The source plugin that generated this event. The value of this field is the name of the plugin's API method, e.g., 'showLoginUI', 'showCommentsUI', etc.
contextobject The context object passed by the application as parameter to the API method, or null if no context object has been passed.
errorCodeintegerThe result code of the operation. Code '0' indicates success, any other number indicates failure. For a complete list of error codes, see the Error Codes table.
errorMessagestringA short textual description of an error, associated with the errorCode, for logging purposes.
errorDetailsstringThis field will contain the exception info, if available.

onBeforeCommentSubmitted Event Data

FieldTypeDescription
   
eventName string The name of the event.
source string The source plugin that generated this event. The value of this field is the name of the plugin's API method, e.g., 'showLoginUI', 'showCommentsUI', etc.
contextobject The context object passed by the application as parameter to the API method, or null if no context object has been passed.
commentTextstringThe content of the comment the user submitted.
commentTitlestringThe title of the comment. This field will be available only if the plugin is running in the Rating & Reviews operation mode.
categoryIDstringThe identifier of the comments category to which the comment belongs.
streamIDstringThe identifier of the comments stream to which the comment belongs.
parentIDstring The identifier of the parent comment.
guestNamestringThe name of the guest user.
guestEmailstringThe email of the guest user.

onCommentSubmitted Event Data

FieldTypeDescription
   
eventName string The name of the event.
source string The source plugin that generated this event. The value of this field is the name of the plugin's API method, e.g., 'showLoginUI', 'showCommentsUI', etc.
contextobject The context object passed by the application as parameter to the API method, or null if no context object has been passed.
commentTextstringThe content of the comment the user submitted.
commentTitlestringThe title of the comment. This field will be available only if the plugin is running in the Rating & Reviews operation mode.
providerPostIDsarrayAn array of JSON objects representing the social network's post ID. Each object has the following fields:
  • provider - the social network provider (string). The optional values are: 'facebook', 'twitter' or 'googleplus'.
  • postID - the unique ID of the post (string).
commentComment objectThe comment that the user submitted.
userUser objectIf the user is logged-in to the site (through a social network or site credentials), the event data will include a User object with updated information for the current user.
   or   
guestUserObjectIf the user has logged-in as a guest, the event data will include a 'guestUser' object that contains the following data fields: username and email.
modestringThe value may be either "comments" or "reviews". 
categoryIDstringThe identifier of the comments category to which the submitted comment belongs.
streamIDstringThe identifier of the comments stream to which the submitted comment belongs.

onCommentVoted Event Data

FieldTypeDescription
   
eventName string The name of the event.
source string The source plugin that generated this event. The value of this field is the name of the plugin's API method, e.g., 'showLoginUI', 'showCommentsUI', etc.
contextobject The context object passed by the application as parameter to the API method, or null if no context object has been passed.
commentComment objectThe comment on which the user voted.
modestringThe value may be either "comments" or "reviews". 
categoryIDstringThe identifier of the comments category to which the voted comment belongs.
streamIDstringThe identifier of the comments stream to which the voted comment belongs.
votestringCan be either "pos" for a positive vote or "neg" for a negative vote.

onSiteLoginClicked Event Data

FieldTypeDescription
   
eventName string The name of the event.
source string The source plugin that generated this event. The value of this field is the name of the plugin's API method, e.g., 'showLoginUI', 'showCommentsUI', etc.
contextobject The context object passed by the application as parameter to the API method, or null if no context object has been passed.

Global Events Triggered

By using this plugin, the following global events may be triggered: onLogin, onLogout,  onConnectionAdded and onConnectionRemoved.

To register an event handler use the socialize.addEventHandlers API method. Please refer to Events to learn more about how to handle events generated by the Gigya service.

Code Sample

var params =
{
        containerID: 'commentsDiv', 
        categoryID: 7623701, 
        streamID: 'Comments_1_stream_1',
        version: 2,
        userHiResIcons: true
};

gigya.comments.showCommentsUI(params);

 

Notes:

  • This sample is not meant to be fully functional code. For brevity's sake, only the code required for demonstrating the API call itself is presented.
  • To run the code on your own domain, add your Gigya API key to the gigya.js URL. A Gigya API key can be obtained on the Site Dashboard page on Gigya's website. Please make sure that the domain from which you are loading the page is the same domain name that you used for generating the API key.