HTML Page Layout Using Rating-Widget

Your HTML page layout should look something like this:

Asynchronous Initiation Function of the Rating-Widget Library

The Rating-Widget library supports and uses async loading for optimization reasons. When the Rating-Widget JavaScript external file is fully loaded, it automatically invokes the RW_Async_Init() function. Because of that, the rendering must be done inside the function (or after it's invoked).

The RW Object

Constants of the RW Object

The RW JavaScript object has various types that may be helpful. Only types documented in this section should be relied upon. Specifically, any types beginning with an underscore are subject to change and should not be used.

Name Value Description
MIN 1 Maximal rate value.
MAX 5 Maximal rate value.
MIN_STARS 1 Minimal stars number (for star rating).
MAX_STARS 20 Maximal stars number (for star rating).
CALL_RATINGS_MAX_LEN 1000 HTTP GET request query string max length.
PREFIX "rw" Rating-Widget prefix.
CUSTOM "custom" Custom thumb and star rating style.

Usage

if (i == RW.MAX) { ... }

Available variables when customizing labels

Variable Description Default
{{text.rateThis}} "Rate this" text. Rate this
{{text.outOf}}
 "out of" text. out of
{{text.votes}}
 "Votes" text. Votes
{{rating.votes}}
 Number of votes
{{rating.likes}}
 (For thumb rating only) Number of likes
{{rating.dislikes}}
 (For thumb rating only) Number of dislikes
{{rating.max_rate}}
 Highest possible rating
{{rating.avg_rate}}
 Average rating
{{rating.rate_percent}}
 Average rating (%)

Enumerable Types of the RW Object

The RW JavaScript object has various constants that may be helpful. Only constants documented in this section should be relied upon. Specifically, any constants beginning with an underscore are subject to change and should not be used.

Type Description 
TYPE: {
STAR: "star",
NERO: "nero"
}
 Optional Rating-Widget types.
STAR: Stars rating
NERO: Thumbs rating (like or dislike) 
SIZE: {
SMALL: "small",
MEDIUM: "medium",
LARGE: "large"
}
 Optional sizes.
SMALL: 16px x 16px star icon size
MEDIUM: 20px x 20px star icon size
LARGE: 30px x 30px star icon size 
COLOR: {
YELLOW: "yellow",
RED: "red",
GREEN: "green",
BLUE: "blue",
CUSTOM: "custom"
}
 Optional colors.
(*) Deprecated 
DIR: {
LTR : "ltr",
RTL : "rtl"
}
 Optional directions. 
ALIGN.HOR: {
LEFT: "left",
CENTER: "center",
RIGHT: "right"
}
 Optional horizontal alignments. 
ALIGN.VER: {
TOP: "top",
MIDDLE: "middle",
BOTTOM: "bottom"
}
 Optional vertical alignment. 
FREQUENCY: {
ONCE: -1,
UNLIMITED: 0,
DAILY: 1
WEEKLY: 7
MONTHLY: 30
YEARLY: 365
}
 Optional voting frequencies.
ONCE: User can vote only once
UNLIMITED: User can contribute unlimited votes
WEEKLY: User can contribute one vote each week
MONTHLY: User can contribute one vote each month
YEARLY: User can contribute one vote each year

Usage

switch (c) {
   case RW.ALIGN.VER:
...

Options-Object Type of the RW Object

The RW JavaScript options-object has various members that may be helpful. Only members documented in this section should be relied upon. Specifically, any members beginning with an underscore are subject to change and should not be used.

Name Type Description Default
lng string Rating-Widget language. "en"
url string Rated element page url. ""
title string Rated element title. ""
type RW.TYPE Rating-Widget type (stars or thumbs). RW.TYPE.STAR
rclass string Rating class (e.g. "post", so latter you can initialize star rating options by rating class). ""
size RW.SIZE Rating-Widget size. RW.SIZE.SMALL
theme string Rating-Widget ratings theme name. ""
color(*) Deprecated RW.COLOR Star color. RW.COLOR.YELLOW
style string Rating-Widget thumb & star ratings style (graphics). ""
imgUrl { object Custom star rating image url.
ltr string Custom Left-To-Right rating image url. ""
rtl string Custom Right-To-Left rating image url. ""
},
mobile { object Custom mobile settings.
optimized bool If true, show mobile optimized experience with Dropdown selection. true
showTrigger bool If true and there's "primary" rating on page, show fixed mobile button which triggers the voting. true
},
label { object Custom label settings.
background string Background color "#FFFFFF"
text { object Custom Label template settings. See Supported Variables.
star { object Label template settings for star rating.
empty string Template for rating with ZERO votes. "{{text.rateThis}}"
normal string Template for rating with NON-ZERO votes. Visible only to users who didn't vote yet. "{{text.rateThis}} ({{rating.votes}} {{text.votes}})"
rated string Template for rating with NON-ZERO votes. "{{rating.votes}} {{text.votes}}"
},
nero { object Label template settings for thumb rating.
empty string Template for rating with ZERO votes. "{{text.rateThis}}"
normal string Template for rating with NON-ZERO votes. Visible only to users who didn't vote yet. "{{text.rateThis}}"
rated string Template for rating with NON-ZERO votes. "{{rating.votes}} {{text.votes}}"
}
}
},
readOnly boolean If true, then the Rating-Widget is read-only/static. false
frequency RW.FREQUENCY The frequency the user can contribute a vote to the rating. By default, user can only vote once (RW.FREQUENCY.ONCE). RW.FREQUENCY.ONCE
reVote boolean If false, then the user can NOT change his vote. true
showInfo boolean Specify whether to show info messages or just a stripped star rating system. true
showTooltip boolean Specify whether to show mouseOver tooltip or not. true
hideRecommendations boolean Specify whether to show the Top-Rated recommendations in the inline report bubble / window. false
showRecommendations boolean For paid customers: Specify whether to show the Top-Rated recommendations in the inline report bubble / window. false
showReport boolean Specify whether to show the report bubble / window after a vote, or when a user mouse over the votes label. true
showAverage boolean Specify whether to show the average rate of the rating. When false, the voter will only see his own vote. true
showLoader boolean Specify whether to show the loading-animation before the ratings appear. true
boost { object Rate boosting options. Shift the initial rating data.
votes int Votes number. 0
rate int Votes average rate. 5
},
beforeRate {bool | unsigned int} function(rating, vote) Optional handler that invokes between users click on the widget to the backend rate itself. null
afterRate void function(success, vote, rating, first, msg) Optional rating system callback. Invoked after the rating process. null
advanced { object Advanced options.
font { object Advanced font options.
color string Font color. "#000000"
type string Font type/family. "arial"
bold boolean Is bold font weight. false
italic boolean Is italic font style. false
},
layout { object Advanced layout options.
lineHeight string Widget text line height. "16px"
dir RW.DIR Layout direction. DIR.LTR
align { object Advanced alignment options.
hor RW.ALIGN.HOR Horizontal alignment. RW.ALIGN.HOR.RIGHT
ver RW.ALIGN.VER Vertical alignment. RW.ALIGN.VER.RIGHT
}
},
text { object Advanced text options.
rate array of string Various types of rates. e.g. in English,
["Awful", "Poor", "Average", "Good", "Excellent"]		 Language Dependent
vote string The word that will appear for "Vote". "Vote"
votes string The word that will appear for "Votes". "Votes"
thanks string The expression which will appear for "Thank You". "Thank you"
},
star { object Advanced star options.
stars int Specify the number of stars for the star rating system (between 1 to 20). 5
},
nero { object Advanced thumb options.
text { object Advanced text options. See Supported Variables.
like { object
empty string Custom text for rating with ZERO votes. {{rating.likes}}
rated string Custom text for rating with NON-ZERO votes. {{rating.likes}}
},
dislike { object
empty string Custom text for rating with ZERO votes. {{rating.dislikes}}
rated string Custom text for rating with NON-ZERO votes. {{rating.dislikes}}
},
css { object Advanced CSS stylesheet options.
container string Rating widget container inline style. ""
}
}

Methods of the RW Object

The RW JavaScript object has various methods that may be helpful. Only methods documented in this section should be relied upon. Specifically, any methods beginning with an underscore are subject to change and should not be used.

Method Description
init(uid, options, vid)Initialization of the RW object. This method must be invoked first and only once in a page.uid {char[32]} your Rating-Widget user-key.options {object} a set of default options for all the Rating-Widget instances in the page (Optional).vid {unsigned int} voter unique id (Optional). E.g. logged user id.
initRating(urid, options)Set specified options to selected Rating-Widget instance. If calling this method, it must be invoked before calling to render().urid {unsigned int} selected Rating-Widget id.options {object} a set of options for the Rating-Widget.
initClass(class, options)Set specified options to all ratings with the specified rating class. If calling this method, it must be invoked before calling to render().class {string} rating class.options {object} a set of options for the Rating-Widget.
render(callback, optimized)Render all Rating-Widget instances of the page.callback {function()} optional callback after render.optimized {object} optimize external CSS stylesheet, defaults to true.
getRating(urid)Get specified Rating-Widget RW.Rating class instance.urid {unsigned int} user rating id.
getDefaultFontSize(size)Return the default font size corresponding to specified widget size.
(*) Deprecatedsize {RW.SIZE} Rating-Widget size.
getDefaultLineHeight(size)Return the default line height corresponding to specified widget size.
(*) Deprecatedsize {RW.SIZE} Rating-Widget size.
optIn()Opt-in to RatingWidget cookies for visitor device identification. Non-EU visitors will be automatically opted-in to our cookies unless they opt-out. Device ID cookie will not be generated for EU visitors by default unless they opt-in.
optOut()Opt-out from RatingWidget's visitor tracking cookies. The identification method for an opted-out visitor is based on their anonymized IP by default.

Usage

RW.init("someuseruniqueidsomeuseruniqueid");
RW.initRating(36, {
   lng: "ru",
   advanced: {
      layout: {
         dir: RW.DIR.RTL
      }
   }
});

RW.render();

The RW.Rating Class

Properties of the RW.Rating Class

The RW.Rating JavaScript class has various properties that may be helpful. Only properties documented in this section should be relied upon. Specifically, any properties beginning with an underscore are subject to change and should not be used.

All properties are read-only and must not be modified directly.

Name Type Description
rid unsigned int Unique rating id.
urid unsigned int User rating id.
uid char[32] Unique user-key/id.
votes unsigned int Total votes number.
rate unsigned int Total rate - the sum of all votes together (not the average).
type RW.TYPE Rating type.
rated boolean Indicates whether the rating widget was already rated since it's loaded.
callState {"ready", "calling", "finished"} Current back-end server call state.
options object Rating system options-object.
advanced object Rating system advanced-options-object (alias of options.advanced).
beforeRate {bool | unsigned int} function(rating, vote) Optional handler that invokes between users click on the widget to the backend rate itself.
afterRate void function(success, vote, rating, first, msg) Optional rating callback. Invoked after the rating process.

Usage

var myRatingWidget = RW.getRating(36);
if (myRatingWidget.votes == 1000) {
...

Methods of the RW.Rating Class

The RW.Rating JavaScript class has various methods that may be helpful. Only methods documented in this section should be relied upon. Specifically, any methods beginning with an underscore are subject to change and should not be used.

Method Description
constructor(data, elements, options)Class constructor.data {object} widget metadata (uid, urid, rid, votes, rate).elements {array of DOMElement} array of all UI instances (<div> containers) of the specified widget.options {object} rating options-object.
render()Renders the Rating-Widget UI instances (<div> containers).
refresh()Refresh rating view - update UI rate and label.
doRate(vote)Imitates user rating/voting action.vote {unsigned int} Rate/Grade (0 < vote < 6).
toggleBold()Toggle label boldness.
toggleItalic()Toggle label italicness.
setReadOnly(readOnly)Set if the rating is active or read-only.readOnly {boolean} Is read-only.
setFontType(family)Set font family.family {string} Font-family (e.g. "verdana").
setFontColor(color)Set label color.color {string} Color (e.g. "#00ff00", "red").
setFontSize(size)Set font size.size {string} Color (e.g. "30px", "1.2em").
setDirection(dir)Set containers direction.dir {RW.DIR} Direction (e.g. RW.DIR.RTL).
setAlignment(ver, hor)Set widgets alignment.ver {RW.ALIGN.VER} Vertical alignment (e.g. RW.ALIGN.VER.TOP).hor {RW.ALIGN.HOR} Horizontal alignment (e.g. RW.ALIGN.HOR.CENTER).
setLineHeight(height)Set line height.height {string} Line height (e.g. "20px").
setSize(size)Set widget's size.
Notice that if you won't explicitly specify the optimized parameter to be false when executing RW.render, your star icons will disappear!size {RW.SIZE} Color (e.g. RW.SIZE.MEDIUM).
setStyle(style, url)Set widget's style.
Notice that if you aren't using the custom image option and if you won't explicitly specify the optimized parameter to be false when executing RW.render, your star/thumb icons will disappear!style {string} Style (e.g. "oxygen_green"). Check out all available styles list.url {object} Optional custom image url object, relevant only when style = RW.CUSTOM.
setLanguage(lng)Set widget's language.
Notice that if you won't explicitly specify the optimized parameter to be false when executing RW.render, the language won't be loaded correctly!lng {string} Language (e.g. "ru"). Check out all available languages list.
setStars(num)Set star rating stars number.num {string} Stars number.
setCSS(item, style)Set rating inline style.item {string} The item of the rating that you wish to change it's style (currently only "container" is the only supported element).style {string} Inline style.

Usage

var myRatingWidget = RW.getRating(36);
myRatingWidget.setFontSize("24px");
myRatingWidget.toggleBold();

The beforeRate() Handler Signature

{bool | uint} beforeRate(RW.Rating rating, uint vote);

Params:

Name Type Description
vote unsigned int The grade/rate of the specified rate (0 < vote < 6).
rating RW.Rating The rated Rating-Widget control class instance.

Return:

Value Type Description
false bool If you like the rating process to stop - the rate won't reach the backend server.
true bool If you like the rating process to continue to the backend server.
vid (voter-id) unsigned int Your current logged in user unique id.

The afterRate() Callback Signature

void afterRate(bool success, uint | bool vote, RW.Rating rating, bool first, string msg);

Params:

Name Type Description
success bool Is successful rate.
vote unsigned int | bool The rate of the specified rate (0 < vote < 6). If it's a thumb rating, returns true on Like, false on Dislike.
rating RW.Rating The rated Rating-Widget control class instance.
first bool Is it the first time that the user rates current Rating-Widget.
msg string Contain the error msg, on rating failure (when success = false).

Supported Languages

Code Language
"af" Afrikaans
"ar" Arabic - العربية
"bn" Bengali - বাংলা
"bg" Bulgarian - български
"ca" Catalan - Català
"ch" Chinese - 汉语/漢語
"cs" Czech - Čeština
"hr" Croatian - Hrvatski
"da" Danish - Dansk
"en" English (Default)
"et" Estonian - Eesti keel
"fi" Finnish - Suomi
"fr" French - Français
"ka" Georgian - ქართული
"de" German - Deutsch
"el" Greek - Ελληνικά
"he" Hebrew - עברית
"hi" Hindi - हिंदी
"hu" Hungarian - Magyar
"id" Indonesian - Bahasa Indonesia
"it" Italian - Italiano
"jp" Japanese - 日本語
"ko" Korean - 한국어/조선말
"lh" Lithuanian - Lietuvių
"mt" Maltese - Malti
"mn" Mongolian - Mongγol Kele
"nl" Nederlands - Dutch
"no" Norwegian - Norsk
"fa" Persian - فارسی
"pl" Polish - Polska
"pt" Portuguese - Português
"ro" Romanian - Română
"ru" Russian - Русский
"sr" Serbian - Српски
"sk" Slovak - Slovenčina
"sl" Slovenian - Slovenščina
"sv" Swedish - Svenska
"es" Spanish - Español
"ta" Tamil - தமிழ்
"tr" Turkish - Türkçe
"vi" Vietnamese - Tiếng Việt
"uk" Ukrainian - Українська Мова

Rating Styles

Star Rating Styles

Sprite Name Element Author Icon Pack
"ratingwidget" Star Stanislav Macha Rating-Widget
"oxygen" Star Oxygen Team Oxygen
"oxygen1" Star Oxygen Team Oxygen
"crystal" Star YellowIcon Crystal Project
"christmas" Star jj-maxer Merry Christmas
"darkglass" Star Alessandro Rei Dark Glass
"oxygen_green" Star Oxygen Team Oxygen
"oxygen1_green" Star Oxygen Team Oxygen
"crystal_green" Star YellowIcon Crystal Project
"christmas_green" Star jj-maxer Merry Christmas
"darkglass_green" Star Alessandro Rei Dark Glass
"oxygen_red" Star Oxygen Team Oxygen
"oxygen1_red" Star Oxygen Team Oxygen
"crystal_red" Star YellowIcon Crystal Project
"christmas_red" Star jj-maxer Merry Christmas
"darkglass_red" Star Alessandro Rei Dark Glass
"oxygen_blue" Star Oxygen Team Oxygen
"oxygen1_blue" Star Oxygen Team Oxygen
"crystal_blue" Star YellowIcon Crystal Project
"christmas_blue" Star jj-maxer Merry Christmas
"darkglass_blue" Star Alessandro Rei Dark Glass
"flat_yellow" Star Stanislav Macha Rating-Widget
"flat_green" Star Stanislav Macha Rating-Widget
"flat_red" Star Stanislav Macha Rating-Widget
"flat_blue" Star Stanislav Macha Rating-Widget
"flat_magenta" Star Stanislav Macha Rating-Widget
"flat_brown" Star Stanislav Macha Rating-Widget
"yellow" Star Vova Feldman Rating-Widget
"green" Star Vova Feldman Rating-Widget
"red" Star Vova Feldman Rating-Widget
"blue" Star Vova Feldman Rating-Widget
"gray" Star Vova Feldman Rating-Widget
"quartz" Star Andy Gongea Quartz
"quartz_green" Star Andy Gongea Quartz
"quartz_red" Star Andy Gongea Quartz
"quartz_blue" Star Andy Gongea Quartz
"flames" Flame Giuseppe Battaglia
"smiley" Smiley Daya Curley
"crystal_correct" Correct Everaldo Coelho Crystal Clear Actions
"heart" Heart Vova Feldman Rating-Widget
"lean_heart" Heart Everaldo Coelho Lin
"barrels" Barrel Mladenovic Igor Rating-Widget
"cups" Cup Josh Schneider CupO'Forex
"apple_screen" Screen Apple Leopard
"phuzion_diskonkey" DiskOnKey Asher Phuzion
"emblem_art" Art schollidesign Human-O2
"everaldo_house" House Everaldo Coelho Kids
"newyear_tree" New-Year Tree Icojoy New Year Icojoy
"payment_coin" Coin Web Icon Set Payment Icon Set
"farmfresh_football" Football FatCow Farm-Fresh Web
"sportset_soccer" Soccer Ball Kevin Andersson Sportset
"sportset_tennis" Tennis Ball Kevin Andersson Sportset
"animals_butterfly" Butterfly VisualPharm (Ivan Boyko) Animals
"phuzion_bug" Bug Asher Phuzion
"animals_elephant" Elephant VisualPharm (Ivan Boyko) Animals
"crystal_penguin" Penguin Everaldo Coelho Crystal Clear Actions
"crystal_skype" Skype Logo YellowIcon Crystal Project
"crystal_user" User Everaldo Coelho Crystal Clear Actions
"darkglass_cookie" Tennis Ball YellowIcon Crystal Project
"jelly_red" Red Jellybeans Stanislav Mácha Rating-Widget
"santa_hat" Christmas Santa Hat PelFusion + IconDock Christmas
"christmas_yellow_ball" Christmas Yellow Ball 1 Icojoy New Year
"christmas_yellow_deco_ball" Christmas Yellow Ball 2 Icojoy New Year
"christmas_red_ball" Christmas Red Ball 1 Icojoy New Year
"christmas_red_deco_ball" Christmas Red Ball 2 Icojoy New Year
"christmas_blue_ball" Christmas Blue Ball 1 Icojoy New Year
"christmas_blue_deco_ball" Christmas Blue Ball 2 Icojoy New Year

Thumb Ratings Styles

Sprite Name Element Author Icon Pack
"thumbs" Thumbs Vova Feldman Rating-Widget
"thumbs2" Thumbs Jochem van der Veer Rating-Widget
"arrows" Arrows Vova Feldman Rating-Widget
"arrows1" Arrows Vova Feldman Rating-Widget
"check" Checkboxes Trevor Hatfield Rating-Widget
"thumbs_bp" Thumbs Vova Feldman Rating-Widget
"masks" Thumbs David Shenberger Rating-Widget
"christmas" Thumbs Vova Feldman + IconDock Rating-Widget
"candles" Thumbs Yoram Zara Avelim

Examples using the RW object

Notice: All the examples must be placed in the scope of RW_Async_Init() function.

Setting All Rating-Widget Star Ratings to be Read-Only

RW.init("someuseruniqueidsomeuseruniqueid",{readOnly: true});
RW.render();

Customizing 2 Rating-Widgets Differently

RW.init("someuseruniqueidsomeuseruniqueid");

RW.initRating(36, {
   type: RW.TYPE.STAR,
   style: "oxygen",
   size: RW.SIZE.LARGE
});

RW.initRating(17, {
   type: RW.TYPE.NERO, 
   style: "thumbs", 
   advanced: {
      text: {
         thanks: "Thanks Dude!"
      }
   }
});

RW.render();

Custom Label Background

RW.init("someuseruniqueidsomeuseruniqueid");

RW.initRating(17, {
   type: RW.TYPE.STAR, 
   style: "oxygen", 
   label: {
      background: "#FF0000"
   }
});

RW.render();

Custom Label Text

Star

RW.init("someuseruniqueidsomeuseruniqueid");

/* 
 * Example text output:
 * Average Rate: 3.33 / Votes: 5
 * Average Rate: 5 / Votes: 200
 */
RW.initRating(36, {
   type: RW.TYPE.STAR, 
   style: "oxygen", 
   label: {
      text: {
         star: {
            rated: "Average Rate: {{rating.avg_rate}} / Votes: {{rating.votes}}"
         }
      }
   }
});

RW.render();

Thumb

RW.init("someuseruniqueidsomeuseruniqueid");

/* 
 * Example text output:
 * Likes: 5 / Dislikes: 3
 * Likes: 10 / Dislikes: 20
 */
RW.initRating(17, {
   type: RW.TYPE.NERO, 
   style: "thumbs", 
   label: {
      text: {
         nero: {
            rated: "Likes: {{rating.likes}} / Dislikes: {{rating.dislikes}}"
         }
      }
   }
});

RW.render();

Forcing Log-In Before Rating

RW.init("someuseruniqueidsomeuseruniqueid", {
   beforeRate: function(rating, vote) {
      if (!is_logged_in()) {
         return false;
      } else {
         return get_user_id();
      }
   }
});

RW.render();

Setting Custom Image Sprite

Notice: Click here to learn how to build your custom icons sprite.

RW.init("someuseruniqueidsomeuseruniqueid", {
   type: RW.TYPE.STAR,
   style: RW.CUSTOM,
   imgUrl: {
      ltr: "http://yourdomain.com/your.left2right.sprite.png",
      rtl: "http://yourdomain.com/your.right2left.sprite.png"
   }
});

RW.render();

Rewarding the 1,000th Rater

RW.init("someuseruniqueidsomeuseruniqueid", {
   afterRate: function(success, first, vote, rating, msg) {
      if (success && first && rating.votes == 1000) {
         alert("You are the BEST! Thanks!");
      }
   }
});

RW.render();

Setting all Posts Ratings to Star Ratings and all Comments Ratings to Thumb Ratings