Comments Version 1

Skip to end of metadata
Go to start of metadata

Comments Version 1 is Deprecated.

You will be transferred to the main Comments documentation shortly. Click here to redirect manually.

 

Introduction

Gigya's Comments plugin enables site users to post comments and have discussions about published content on the site.

This guide walks through the Comments plugin setup and integration and serves as a reference document for the configuration and customization options.
 

Note: If you wish to use the plugin for Ratings & Reviews please follow the designated guide.

This plugin is deprecated. A new and improved version of the Comments plugin is available - please refer to Comments Version 2.

 

How it Works

The plugin presents:

  • A "Post a new comment" canvas. The "Post a new comment" canvas has two states: when the current user is logged-in and when he is logged-out.
  • Comments stream

The default look of the Comments plugin (logged-out state):

In the logged-out state, the "Post a new comment" canvas includes a User Login panel.

If a user tries to post a comment when not logged in, he is prompted to login, and once he logs in, the comment is posted:

 

The default look of the Comments plugin (logged-in state):


 

In the logged-in state, the "Post a new comment" canvas includes

  • User's profile picture and name of the logged in user.
  • A "Follow replies to my comments" link that once clicked notifies the user when someone replies to his comments. 
  • Commenting input box.
  • Sharing panel (checkboxes with social network icons) - provides an option to share a posted comment to social networks.
  • A "More" link that once clicked offers more options of sharing destinations.

Major Features

  • The plugin provides an integrated social login:
    • Through a social network account. Such case may initiate a user sign-up to your site.
    • Using the site credentials.
    • As a guest user.
  • Supports publishing a posted comment to one or more social network destinations. This enables users to share their comments with their social networks friends.
  • Server side administration: use the Comments Setup page on Gigya's website to define categories for comments and customize each comment category settings.
  • Support multiple comments streams per category .
  • The Comments plugin graphic design is highly customizable (read more in the UI Customizations section below).
  • Comment threads - replies to a comment.
  • Export current comments through RSS/XML format.
  • Importing 3rd party commenting systems.
  • Moderation.
  • Subscribing to comments streams by email.

Quick Start - Setup and Integration

This section is a quick integration guide. Follow the step below to integrate the Comments plugin with its default settings into your site.
The integration process includes broadly two stages:

  1. Setting up a New Comment Category on Gigya's website
    Note: This step is necessary only when integrating the first instance of the Comments plugin in your site. When integrating more instances, you can reuse the same settings and jump to stage 2.
  2. Copying the generated code from Gigya's website and integrating the code into your site  

Setting up a New Comment Category

Every Comments plugin instance belongs to a Comments category. The Comments category provides the option to define a group of Comments plugin instances that share the same settings. You may define one or more Comments categories for your domain. Each category may be configured to have different settings. The settings are defined on the server side and may be administrated using the Comments Setup section of Gigya's website. Follow the steps below to create a new Comments category:

  1. Go to the Comments Setup section of Gigya's website. Please make sure your are signed in. The Comments Setup page may also be accessed by clicking "Settings" in the upper menu and then "Comments" in the left menu.
     
  2. Click the 'Add new comment category' button:

     
  3. Fill in a new category name and select the 'Comments' radio button:
        
     
  4. Click "OK". A new Comments Category instance is created. Notice the newly created row in the Comments categories table:

    The JavaScript code under "Embed code" column is the generated code that you will integrate in your site (next step). The code includes a generated unique categoryID that identifies the newly created category.
    The "Comments Settings" button leads to an administration screen that lets you change the default settings of the Comments category. This subject is broadly explained in the Advanced Setup and Administration section below.

Integrating the Plugin Code into Your Site

The simplest and fasted way to integrate the Comments plugin in your site is to copy the "Embed code" from the category row and paste it into the spot in the part of your web page in which you want the plugin to appear.

<script src="http://cdn.gigya.com/JS/gigya.js?apiKey=2_Y82PzwJ_chSFImHXaIDJClnLyJzmk-VFOavSsaNTzl6m901s_NNxRAS0xJ3bd3_N" 
type="text/javascript"></script>
<div id="commentsDiv"></div>
<script type="text/javascript">
    var params =
    {
        categoryID: 7623701,
        streamID: '',
        containerID: 'commentsDiv',
        cid:'',
        enabledShareProviders: 'facebook,twitter,linkedin'
    }
    gigya.comments.showCommentsUI(params);
</script> 

Notes:

In order to make the above code work in your environment, please note:

  • The API key in the sample will only work on http://localhost/...
  • To load the page from your domain, modify the value of the "APIKey" field in the code to your own Gigya API Key. A Gigya API Key can be obtained from 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.
  • If you are using https, be sure to further adjust the JS API url to: https://cdns.gigya.com/js/gigya.js?apikey=<Your_API_Key>.

The best practice though, is to cut the first line of code and move it to the section of your page. This line loads Gigya's JS library file.

The outcome is:

<html>
<head>
    <script src="http://cdn.gigya.com/JS/gigya.js?apiKey=2_Y82PzwJ_chSFImHXaIDJClnLyJzmk-VFOavSsaNTzl6m901s_NNxRAS0xJ3bd3_N" 
        type="text/javascript"></script>
</head>
<body>
    <div id="commentsDiv"></div>
    <script type="text/javascript">
        var params =
        {
            categoryID: 7623701,
            streamID: '',
            containerID: 'commentsDiv',
            cid:'',
            enabledShareProviders: 'facebook,twitter,linkedin'
        }
        gigya.comments.showCommentsUI(params);
    </script>
</body>
</html>

Notes:

In order to make the above code work in your environment, please note:

  • The API key in the sample will only work on http://localhost/...
  • To load the page from your domain, modify the value of the "APIKey" field in the code to your own Gigya API Key. A Gigya API Key can be obtained from 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.
  • If you are using https, be sure to further adjust the JS API url to: https://cdns.gigya.com/js/gigya.js?apikey=<Your_API_Key>.

The above code is of a basic web page that includes only the Comments plugin. See this code in action in the Running Example below.

Category ID

Notice the categoryID in line 12. This ID was generated by Gigya and is a unique identifier for the Comments category that you have defined in the previous step.

Stream ID

Notice the streamID in line 13. The streamID identifies a stream of comments within a Comments category. The ID is now empty, meaning that we have a single stream with an empty identifier. Two Comments plugin instances that share the same categoryID and streamID will show the same comments.
To create several instances of Comments plugins that belong to the same category, copy the same code to different spots in your site where you wish to insert the plugin. In each spot, assign a different identifier (string) to the streamID. We suggest using the permalink as the streamID. Note: streamID is limited to 150 characters and is case-sensitive.

Running Example

 

 

Configuration and Administration

If you go back to the Comments Setup page, in the Comments category row that you have created, you will see a "Comments Settings" button. Clicking this button leads to the Comments Settings page. This page is an administration screen that lets you change the default settings of the Comments category.

You may change the settings as you choose and then save them by clicking the "Save changes" button at the bottom of the page. The changes are saved in Gigya's database (server side). No coding changes are required. The change will take effect immediately. For a page that is already loaded, refresh the page and you will see the change.

The available configuration options in this page:

Changing to 'Read Only'

The 'Status' property is 'Enabled' by default, meaning that users are able to submit comments.
If you change the Status to 'Read only', users will only be able to read comments. Graphically, the 'Post a new comment' canvas is not displayed.

Moderation

Gigya's commenting service supports moderation administration. This section of the Comments Settings page includes moderation settings, including notification email, moderation mode, and more. Read more  in the  Comments Moderation dedicated guide .

User Login

This section controls the login canvas, which is contained in the "Post a new comment" canvas. By default the login canvas includes Gigya's Add Connections plugin and looks like this:


 

You may add two user login options:

  • Guest login
  • Site login

In addition, you may upgrade the inner Gigya Add Connections plugin to initiate login. Please read the Using Plugins to Initiate Site Login guide to learn how to integrate the Comments plugin with the Social Login Process and leverage the plugin to acquire new site users.

Adding Guest Login

Adding guest login is simple: Change the "Allowing Guest comments" radio button to "Yes" and click the "Save changes" button at the bottom of the page. Refresh your comments page and see the additional "Guest Login":

You can also decide that an email address is required for guest users:

If both check boxes are checked, providing a valid email address is required.

Adding Site Login

Adding site login is a bit more complex:

var params =  { 
    categoryID: 7623701,
    streamID: '',
    containerID: 'commentsDiv',
    useSiteLogin: true,
    cid:''
}

You will now see the site login button instead of the Gigya Login button. When you set the comment with useSiteLogin=true , clicking the Post button will be the same as clicking the Login button except the comment won't be automatically posted. 

 
  • Clicking site login button at the bottom of the page fires an onSiteLoginClicked event. To register to this event, set the onSiteLoginClicked parameter of the  comments .showCommentsUI method with a reference to an event handler function. This function should open a popup or redirect the user for the site login page. The following sample code illustrates this:

    // onSiteLoginHandler event handler
    function onSiteLoginHandler(event) {
    
        // Site Login button clicked
        // open a popup or redirect the user for the site login page}
    var params =  { 
        categoryID: 7623701,
        streamID: '',
        containerID: 'commentsDiv',
        useSiteLogin: true,
        onSiteLoginClicked: onSiteLoginHandler,   // registering to the onSiteLoginClicked event
        cid:''
    }
    
    gigya.comments.showCommentsUI(params);  
    

    Note: the popup or site login page should include Gigya's Login Plugin.  

Social Network Publishing

The 'Share to social network' check box is checked by default, meaning that the comments submitted by the users are shared to the selected social network or networks.
If you change the check box to unchecked, the users will be able to submit comments, but the comments will not be shared to social networks.

Layout Customization

This section allows you to change a few aspects of the Comments plugin layout settings:

Pagination

Pagination refers to dividing the comments into pages. The default is a display of 25 comments per page, but you may choose to change the number of comments per page using the drop-down menu.

Comment Box Location

The Comment box refers to the 'Post your review ' canvas. By default it is located above the  comments stream, at the top of the plugin. You may change this by checking the 'Bottom' radio button. As a result the canvas will appear below the comments stream, at the bottom of the plugin.

Show Newly Added Comments

This section allows you to specify whether the plugin should be refreshed in real-time and show newly added comments that were posted after the user has entered the page where the plugin is displayed.
T his drop-down menu allows you to select one of the following three options:

  • Off - when selected, do not show notifications for new comments. This is the default option. This means that the comments plugin will not show the new comments that were posted after entering the page where the plugin is displayed.
  • Show only new comments count - when selected, display the number of new comments. When this option is selected, the comments plugin will display the counter of the new comments and a link. The user will be able to click the "Click to show" link in order to display the new comments.

  • Automatically show new comments - when selected, all new comments will be displayed automatically.

Displaying Number of Comments

The checkbox allows you to display or hide the number of comments in the stream.

You can choose whether to display an RSS button and a Subscribe button. This allows users to subscribe to comments streams by email. Read more in the Subscribing to Comments section.

Other Settings

This section allows you to change the default settings of:

  • Comments threading
  • Replies default view
  • Enabling Google Analytics Social Data Hub integration
  • Maximum comment length
  • Displaying Facebook comments
  • Allowing users to delete their own comments
  • Enabling voting on comments, including allowing negative voting and showing separate counter for negative voting
  • Comment sorting, including different sorting options. 


 

Comments Threading

By default comments threading is allowed, meaning that replies to comments are allowed and displayed in a nested manner. If you prefer not to allow comments threading, select the 'No' radio button.

You may choose the depth of the threading, from 1 to 5, using the drop-down menu. The default threading depth is 5.

Replies Default View

You can decide whether the replies to the comments will be displayed in expanded or collapsed view.

Google Analytics Social Data Hub Integration

Gigya supports integration with Google Analytics Social Data Hub. By selecting the 'Yes' radio button, you allow Gigya to publish your comments streams to Google Analytics via the PubSubHubbub (PSHB) protocol.

Maximum Comment Length

You may select the maximum length of the comments. If you do not set this value, the default maximum length of the comments is 5000 characters.

Displaying Facebook Comments

You can choose to display the Facebook comments stream as part of the Comments plugin. The comments from Facebook are marked 'Via Facebook':

Note: In order to be able to view Facebook comments, the Facebook privacy settings regarding posts should be set to 'Everyone'.

Allow Users to Delete their own Comments

When you check the checkbox, an "X" will appear in the top right-hand corner of comments of the logged-in user, allowing the user to delete his own comments:

 

Enabling Voting on Comments

The "Enabling voting on comments" checkbox determines whether to make voting on comments available for users. 

  • "Allow negative voting" determines whether users will be able to vote negatively (thumbs down) on comments. If these two check-boxes are checked, the Comments Plugin shows a set voting icons next to each comment:  
  • "Showing separate counter for negative voting" determines whether to place a separate counter for negative votes (thumbs down) on comments.  If these two check-boxes are checked, the  Comments Plugin  shows a set voting icons next to each comment, with separate counters: 

Sorting Comments

The comments can be displayed in one of the following orders:

  • Most recent on top (default) - the comments are sorted by the timestamp of the post. The first comment is the latest one.
  • Most recent on bottom - the comments are sorted by the timestamp of the post. The first comment is the first created (oldest).
  • Most relevant on top - the thread with the most recent reply is displayed first.
  • Most voted on top - the comments are sorted by the overall votes value (positive votes minus negative votes) of the root comment in each thread. The first comment is the one that has the highest votes.
  • Most voted on bottom - the comments are sorted by the overall votes value (positive votes minus negative votes) of the root comment in each thread. The first comment is the one that has the lowest votes.

Site Restrictions

Gigya offers you the option to manage a custom black list of words and phrases to be filtered in comments, and to block IP addresses. You can read more in the Site Restrictions section, or go directly to the Site Restrictions on Gigya's site.

Commenting Rate Limit

Gigya supports rate limits on commenting in order to prevent spamming and abuse. This includes limiting the number of root comments and replies a user may post per stream in a day, and limiting the number of root comments and replies a user may post per site in a day.

Importing Commenting Systems

Gigya supports importing third-party commenting systems. If you wish to migrate to Gigya's commenting system, you can import your existing comments to Gigya and display them on your site. For this operation, please contact your Customer Services manager. 

UI Customizations

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

You are welcome to consult Gigya's support team to guide you through advanced UI customizations. You can contact us by filling in a support form on our site. You can also access the support page by clicking "Support" on the upper menu of Gigya's site.

HTML Elements Style (CSS)

Any elements on the plugin that has an ID can be overridden with supported style attributes. There are dozens of elements on the plugin. You may use Firebug to identify an HTML element on the plugin and assign a new style to it. Please make sure to use the plugin's container

ID when assigning style, so it will not affect other elements on the page.

 

For example:
<style> #commentsDiv .gig-button-post-text {color:Yellow;background-color:black} </style>

Templates

A template is a layout definition for a group of related graphics elements in the plugin. The plugin includes six customizable templates. You may assign each template with an HTML string that redefines its graphic layout.
The 'templates' parameter of the comments .showCommentsUI method receives an object with the following fields:

  • comment
  • commentBox
  • loginCanvas_loggedIn
  • loginCanvas_loggedIn_guest
  • loginCanvas_loggedOut
  • rating

Each of the fields is a customizable template. Each field has a default value that you may override.
In the following running example we override the first five templates:

Running Example

In the following example the Comments plugin is presented, with all the graphic elements laid out in a different way than the default:

 

 

Example Code

<html>
<head>
<script src="http://cdn.gigya.com/JS/gigya.js?apiKey=2_Y82PzwJ_chSFImHXaIDJClnLyJzmk-VFOavSsaNTzl6m901s_NNxRAS0xJ3bd3_N" 
	type="text/javascript"></script>
</head>
<body>
<div id="commentsDiv"></div>
<script type="text/javascript">

    // Optional - define templates to changes structures in the Comments Plugin
    var templates = {
        commentBox: '<span style="color:blue;">This is the Login Canvas: </span><br>$loginCanvas<br><br>' +
                    '<span style="color:blue;">This is the Close Icon: </span>$closeIcon<br>' +
                    '<span style="color:blue;">This is the Add Comment text box: </span>$addComment',
        comment:'Hello!<br>' +
                '<span style="color:blue;">This is the username: </span>$username<br>' +
                '<span style="color:blue;">This is the Photo Div: </span>$photoDiv<br><br><br>' +
				'<span style="color:blue;">This is the Date String: </span>$dateString<br>' +
                '<span style="color:blue;">This is the Comment Body: </span>$body<br>' +
				'<span style="color:blue;">This is the Replies Count: </span>$repliesCountPlaceholder<br>' +
                '<span style="color:blue;">This is the Reply Button: </span>$replyButton<br><br>' +
                '<span style="color:blue;">This is the Flagging option: </span>$flag<br>' +
                '<span style="color:blue;">This is the Voting option: </span>$vote<br><br>',
        loginCanvas_loggedIn: '<span style="color:blue;">Login Canvas - Logged in state! </span><br>$photoDiv<br>$username<br>$logoutLink',
        loginCanvas_loggedIn_guest: '<span style="color:blue;">Login Canvas - Guest user state! </span><br>$photoDiv<br>$username<br>$logoutLink',
        loginCanvas_loggedOut: '<span style="color:blue;">Login Canvas - Logged Out state!<br></span>$photoDiv<br>$loginDropdown<br>$guestDropdown'
    }
    var params =
    {
        // Required parameters:
        categoryID: 7623701,
        containerID: 'commentsDiv',

        // Optional parameters:
        templates: templates,
        streamID: 'foo6',
        cid: ''
    }

    // Load the Comments Plugin
    gigya.comments.showCommentsUI(params);
</script>
</body>
</html>

Notes:

In order to make the above code work in your environment, please note:

  • The API key in the sample will only work on http://localhost/...
  • To load the page from your domain, modify the value of the "APIKey" field in the code to your own Gigya API Key. A Gigya API Key can be obtained from 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.
  • If you are using https, be sure to further adjust the JS API url to: https://cdns.gigya.com/js/gigya.js?apikey=<Your_API_Key>.

Explanation

You can see in the example above that we set the 'templates' parameter of the comments .showCommentsUI method with a 'templates' object that includes five fields. Each field is assigned with an HTML string that redefines the layout of the compatible graphic element in the Comments plugin. The HTML strings include replacement strings (the strings that begin with the $ sign). These strings are replaced with predefined Comments plugin's basic graphic elements. For example:

  • $username is replaced with a label with the current user's username.
  • $photoDiv is replaced with the the current user's photo.
  • $loginCanvas is replaced with the Login Canvas. Note that you may redefine the Login Canvas layout (see explanation below).
  • etc.

The Login Canvas:
The Login Canvas has three different states: Logged-in, Logged-in as guest, Logged-out. You may redefine each state's layout using the corresponding templates: loginCanvas_loggedIn, loginCanvas_loggedIn_guest, loginCanvas_loggedOut.

Comments UI in Mobile View

When the comments .showCommentsUI deviceType parameter is set to mobile, the comments UI is displayed in the mobile mode:

 

In this mobile mode some of the Comments UI functionality is not supported:

  • Flagging comments
  • Display of the number of replies per comment
  • Guest login
  • Subscribe (RSS or email)
  • Sharing options - only shows one provider checkbox (the last login provider) 
  • Comments threads - the mobile view supports the display of one level of threads. While you can reply to a reply (per the comment settings), the display will show all 2nd level replies under the 1st reply level.
  • Reply box - changes from default design:
    • Does not show the user avatar in the reply box.
    • There is no X (close) button.

Notification on Comments Replies

You can allow your logged-in users to get notifications on other users replying to their comments, by clicking the "Follow replies to my comments" link. Once clicked,  the user will receive notifications via email when someone replies to their comments.

 

Subscribing to Comments

You can allow your users to subscribe to a comments stream by email. First make sure that in the  Comments Settings  page, the radio button of Display subscribe links is set to Display. This will display the RSS and Subscribe links in the Comments plugin:

 

When a user clicks the RSS button, an RSS feed reader is opened, showing the RSS feed.

When a user clicks the Subscribe button, the following dialog opens:

 

The user will then have to enter a valid email address to get notifications on the updates on the current stream. Once the email address is entered, the Subscribe button changes to Unsubscribe , so that the user can decide to no longer receive notifications. The subscription is not immediate, Gigya checks for comment updates every few hours and notifies the user via email that comments have been added to the stream to which they have subscribed.

Note: Any user can subscribe to comments updates via email, either a logged in or a guest user. Users can unsubscribe by clicking the Unsubscribe button in the Comments plugin, or through the link in the update email. 

Comments Counter in Share Bar

Gigya's Share Bar plugin is built out of one or more buttons, arranged horizontally in a bar. You can add a Comments button to your Share Bar, with a counter indicating the number of comments made in that specific comments stream. The comments stream is identified by its unique categoryID and streamID. To learn how to embed a Share Bar with Comments button, read the Adding a Comments Counter section of the Share Bar plugin.

Search Engine Optimization (SEO) Support

This section provides instructions how to make the comments in your Comments plugin searchable by the main search engines, and by that adding SEO value to users. As you know search engines index only static data in your site. It is difficult to make them index dynamic data. This includes the comments data. The comments data is kept on Gigya's server and is requested dynamically. The search engines do not see and do not index the comments data. To solve this issue Gigya provides a static HTML format of the comments with an up-to-date content that is readable by search engines and can be indexed.

To take advantage of this, please follow the steps below:

  1. Detect the Search Engine Crawlers: Find out whether the page is viewed by a search engine spider (bot). Identify the search engine using the HTTP_USER_AGENT field. You may find a PHP example here. Customers using this code should note that customizing pages for search bots can be a violation of search engine guidelines; for more information see https://support.google.com/webmasters/answer/66355.
  2. Inject HTML Comments data: If a search engine is identified, load the HTML content of the comments instance by setting the dataFormat parameter of comments.getComments to 'html':