How To

Ratings / Reviews

15min

﻿
This guide will cover the options for Rating/Review indexing as well as where to locate the elements necessary for display customization within Template JS
 Ratings and Review data can can be used by Klevu to:
Display Rating “stars” and Review “count” in the result set display
Allow the visitor to refine/filter results by the number of Rating “stars” 
Allow the visitor to SortBy Rating “stars”
Enable Klevu Machine Learning to consider the Ratings in relevancy ranking
See : This Knowledge Base Guide on how to enable each of the above.  
 
In order to allow Klevu the Rating and Review count data must first be indexed to Klevu in one of the following ways:
Within the Feed XML file
Within the Klevu Indexing API
Using one of the supported 3rd party connectors
Custom field mapping using one of Klevu's supported platform Apps/plugins
Please contact Klevu support  for further details on this option
﻿
Indexing
The Rating and Review Count data must be supplied at the product level during catalog indexing.
XML FEED example
XML
|
    <item>
   . . .
        <rating>4.5</rating>
        <rating_count>10</rating_count>
   . . .
    </item>
    <item>
   . . .
        <rating>4.5</rating>
        <rating_count>10</rating_count>
   . . .
    </item>
﻿
See : XML FEED Example for Ratings  
﻿
API Reference
Indexing Attribute 
Description
Format
rating
The rating of your product, between 0 and 5.
decimal
rating_count
The number of ratings given by customers for your product.
integer
See : Klevu API Documentation for Data Indexing﻿  
﻿
﻿
Customizing
CSS
The “star” images used in the default Template JS layout are 2 different images. They are overlapped and displayed at a width percentage that is appropriate for the rating value of the record
Gray Star : https://js.klevu.com/klevu-js-v1/img-1-1/star-gray.png
Yellow Star : https://js.klevu.com/klevu-js-v1/img-1-1/star-yellow.png
The following class selectors can be overridden to consider different images or other desired effects:
CSS
|
.kuFilterTagsContainer .klevuFacetStars {
  height: 15px;
  display: inline-block;
  vertical-align: bottom;
  background: transparent url(https://js.klevu.com/klevu-js-v1/img-1-1/star-gray.png) top left repeat-x;
  width: 65px;
}
.kuFilterTagsContainer .klevuFacetStars .klevuFacetRating {
  background: transparent url(https://js.klevu.com/klevu-js-v1/img-1-1/star-yellow.png) top left repeat-x;
  height: 15px;
}

.kuFilterTagsContainer .klevuFacetStars {
  height: 15px;
  display: inline-block;
  vertical-align: bottom;
  background: transparent url(https://js.klevu.com/klevu-js-v1/img-1-1/star-gray.png) top left repeat-x;
  width: 65px;
}
.kuFilterTagsContainer .klevuFacetStars .klevuFacetRating {
  background: transparent url(https://js.klevu.com/klevu-js-v1/img-1-1/star-yellow.png) top left repeat-x;
  height: 15px;
}
﻿
See :  Styling CSS﻿ for further details on overriding Template JS default CSS
 
Sorting
The Template JS SortBy feature can be modified to include Rating Ascending/Descending order.
Sort Parameter Value
Description
RATING_ASC, RATING_DESC
Sort the results by each record's average rating, if this data has been indexed in your store
See : SortBy Options﻿ guide for examples of modifying Template JS default Sorting options
﻿
Filtering
Filtering by Rating “stars” is accommodated like all Template JS facets. 
The key value pairs are as follows:

Description
key
value
one star
rating
0 - 1.5
two stars
rating
1.51 - 2.5
three stars
rating
2.51 - 3.5
four stars
rating
3.51 - 4.5
five stars
rating
4.51 - 5.5
See : Klevu API Documentation for Applying Facets﻿



Template JS Override
Be advised the calculations within the default Template JS are carefully constructed to accommodate the existing CSS and “star” graphics. Please take caution when modifying these aspects of the template(s)
 
There are three default templates that can be accessed should you choose to override for Ratings customizations
klevuLandingProductRating  - used for product block display
klevuLandingTemplateFilters   - used for filter section
kuFilterTagsTemplate   - used for active filter tags
See : Set Template﻿ for details on preparing for Klevu JS overriding
 
Within the JSON response object the Ratings are defined with a type value of "RATING". This value is used during template display logic to render specific elements for Ratings and Review Count.
JSON response example
JSON
|
  "filters": [
 . . .
        {
            "key": "rating",
            "label": "Customer Reviews",
            "type": "RATING",
            "options": [
                {
                    "count": 28,
                    "name": "5",
                    "value": "4.51 - 5.5",
                    "selected": true
                }
            ]
        },
  . . .
  "filters": [
 . . .
        {
            "key": "rating",
            "label": "Customer Reviews",
            "type": "RATING",
            "options": [
                {
                    "count": 28,
                    "name": "5",
                    "value": "4.51 - 5.5",
                    "selected": true
                }
            ]
        },
  . . .
﻿
﻿
Template Override Example
This example overrides the klevuLandingProductRating template to display some custom text based on the item's rating value.
See : Set Template﻿ for details on preparing for Klevu JS Templates for overriding
JavaScript
|
<script type="text/javascript">
/* Assign new templates to Klevu Options */
klevu({
	theme: {
		setTemplates: [
		{
		  scope: "landing", // impacted scope
		  selector: "#myCustom_klevuLandingProductRating", // new block ID
		  name: "klevuLandingProductRating" // template placement name
		  }
	    ]
	}
});
</script>
    
<script type="klevu/template" id="myCustom_klevuLandingProductRating">
<%  if(
      typeof dataLocal.rating != "undefined" && 
             dataLocal.rating !== "" &&
             dataLocal.rating > 0
    ) { %>""
    
// CUSTOM text based on Rating value  
<% if (dataLocal.rating >= 5) { %>
      <span class="topRated">TOP RATED!</span>
<% } %>
    
  <div class="klevu-stars-small-l2">
     <div class="klevu-rating-l2" style="width:<%=(20*Number(dataLocal.rating))%>%;"></div>
   </div>
        
  <%=helper.render('klevuLandingProductRatingCount',scope,data,dataLocal) %>
<% } %>
</script>
<script type="text/javascript">
/* Assign new templates to Klevu Options */
klevu({
	theme: {
		setTemplates: [
		{
		  scope: "landing", // impacted scope
		  selector: "#myCustom_klevuLandingProductRating", // new block ID
		  name: "klevuLandingProductRating" // template placement name
		  }
	    ]
	}
});
</script>
    
<script type="klevu/template" id="myCustom_klevuLandingProductRating">
<%  if(
      typeof dataLocal.rating != "undefined" && 
             dataLocal.rating !== "" &&
             dataLocal.rating > 0
    ) { %>""
    
// CUSTOM text based on Rating value  
<% if (dataLocal.rating >= 5) { %>
      <span class="topRated">TOP RATED!</span>
<% } %>
    
  <div class="klevu-stars-small-l2">
     <div class="klevu-rating-l2" style="width:<%=(20*Number(dataLocal.rating))%>%;"></div>
   </div>
        
  <%=helper.render('klevuLandingProductRatingCount',scope,data,dataLocal) %>
<% } %>
</script>
﻿
﻿

Updated 11 Jul 2023

Did this page help you?

TABLE OF CONTENTS

Template Override Example

Indexing Attribute	Description	Format
rating	The rating of your product, between 0 and 5.	decimal
rating_count	The number of ratings given by customers for your product.	integer

Sort Parameter Value	Description
RATING_ASC, RATING_DESC	Sort the results by each record's average rating, if this data has been indexed in your store

Description	key	value
one star	rating	0 - 1.5
two stars	rating	1.51 - 2.5
three stars	rating	2.51 - 3.5
four stars	rating	3.51 - 4.5
five stars	rating	4.51 - 5.5