In this article I will cover some of the more advanced features of the Ajax Rating plugin. Ajax Rating is rating plugin for Movable Type that makes it easy for readers to rate entries, comments, and more. If you haven't read about Ajax Rating yet, you should read this first, and then come back to read this article afterwards.

Covered in this article:

Custom images for star and thumb raters
Using custom raters
Dynamically updating numeric ratings and vote counts
Setting up comment raters
Rating non-MT objects

Custom images for star and thumb raters

Whether you are using Ajax Rating or Ajax Rating Pro, you can use alternative images for rating items. For star/point raters, the image must be named "starrating.gif". The image should be a "three state" image. For example, here is the default image that comes with Ajax Rating (design credit to Ryan Masuga):

Note that the image has 3 stars, appearing one on top of the other. As such, the height of the image should be 3 times as long as the width. The default image, above, is 30 pixels wide by 90 pixels high. The star at the top is the "empty star", the star in the middle is the "hover star" (the color of the star when you hover your mouse over it), and the bottom star is the "current rating star". Of course, the images don't have to be "stars" at all -- you could use images of hearts, checkmarks, boxes, or bananas. As an example, Ajax Rating comes with an alternative star image called 'starrating16x16.gif' that looks like this:

Note that this image is 16 pixels wide and (16 times 3 equals) 48 pixels high. if you want to use this image, you can rename it 'starrating.gif'.

After you have the image you want, make sure it is named starrating.gif and then upload into the /mt-static/plugins/AjaxRating/images/ directory on your server.

The final (but important) step is to browse to the Ajax Rating settings for your blog and enter the width on your new image into the "Star Icon Width" field. Save your settings and then rebuild the Ajax Rating javascript and styles index templates. Finally rebuild all your pages with star raters.

To use custom image with Thumb Raters (Pro feature), the process is much easier. The only rule is that you have to name your images "up.gif" (+1 point) and "down.gif" (-1 point). You make them any size that suits your needs. Upload the new images to the /mt-static/plugins/AjaxRating/images/ directory and you are done (no need to rebuild any pages).

Creating Custom Raters

The previous section explains how to customize the look of the raters that appear when you use the convenient <MTAjaxStarRater> and <MTAjaxThumbRater> tags. You are not limited to those raters, however. You can create your own custom raters.

For example, here is a simple rater that consists of a "Vote For This Entry!" text link:

<a href="#" onclick="<$MTAjaxRaterOnclickJS points="1" type="entry"$>">Vote For This Entry!</a>

The above example illustrates the key elements of rating link. Set the href equal to "#" and include an onclick= argument. The special MTAjaxRaterOnclickJS tag helps you fill the javascript required to capture the vote. They key argument here is the "points" argument -- use this to specify how many points get assigned when someone clicks that link.

To expand the above example, here is a 5 point rater using text links instead of images:

<a href="#" onclick="<$MTAjaxRaterOnclickJS points="1" type="entry"$>">1</a> <a href="#" onclick="<$MTAjaxRaterOnclickJS points="2" type="entry"$>">2</a> <a href="#" onclick="<$MTAjaxRaterOnclickJS points="3" type="entry"$>">3</a> <a href="#" onclick="<$MTAjaxRaterOnclickJS points="4" type="entry"$>">4</a> <a href="#" onclick="<$MTAjaxRaterOnclickJS points="5" type="entry"$>">5</a>

Tip: if you want your customer rater to disappear after a vote, surround in a div or span element with an "id" in the following format "thumb{type}{id}", replacing {type} and {id} with the type and id of the object being rated. For example:

<span id="thumbentry105"> ...rater goes here </span>

Dynamically updating numeric ratings and vote counts

Often you will want to display numeric representations of ratings and vote counts on your pages. Consider the following example, which shows box a star rating and the average rating and vote count:

<$MTAjaxStarRater type="entry"$>
Rating: <$MTAjaxRatingAverageScore type="entry"$>/<$MTAjaxRatingEntryMax$> (<$MTAjaxRatingVoteCount type="entry"$> votes cast)

Notice when you make a rating with the above rater, the average rating and vote count numbers get updated dynamically. The trick to doing that is to surround those numbers in "span" tags. Here the template code for the above example:

<$MTAjaxStarRater type="entry"$>
Rating: <strong><span id="ajaxrating_entry_<$MTEntryID$>_avg"><$MTAjaxRatingAverageScore type="entry"$></span></strong>/<$MTAjaxRatingEntryMax$> (<span id="ajaxrating_entry_<$MTEntryID$>_cnt"><$MTAjaxRatingVoteCount type="entry"$></span> votes cast)

First looking at MTAjaxRatingAverageScore, the "id" of the span must be in the format id="ajaxrating_{type}_{id}_avg". For an entry with an id of 105, that would be id="ajaxrating_entry_105_avg". Using MT template tags in this example, you can do it as follows:

<span id="ajaxrating_entry_<$MTEntryID$>_avg"><$MTAjaxRatingAverageScore type="entry"$></span>

For MTAjaxratingVoteCount, the process is the same, but the id ends in "_cnt" instead of "_avg". So the template code becomes:

<span id="ajaxrating_entry_<$MTEntryID$>_cnt"><$MTAjaxRatingVoteCount type="entry"$></span>

If you wanted to dynamically update MTAjaxRatingTotalScore (not shown in above example), the id should end in "_ttl":

<span id="ajaxrating_entry_<$MTEntryID$>_ttl"><$MTAjaxRatingTotalScore type="entry"$></span>

Setting up comment raters

With Ajax Rating Pro you can rate comments and other objects. Setting up comment raters is similar to entry raters. While you can use star raters or thumb raters, many people will prefer to thumb raters for rating comments, so my example will focus on these.

To add a thumb comment rater, place the following in suitable place in a <MTComments> container:

<MTAjaxThumbRater type="comment">

(Optionally, you could include a report_icon="1" argument to display a third button, that will enable readers to report comments to entry authors)

Rating non-MT objects

With Ajax Rating Pro, you can even create raters for non-MT objects. For example, suppose I have five photos in my sidebar, and I want people to be able to rate them. The rules for rating non-MT objects are as follows:

  • choose a unique "type" of object (don't use the reserved names like 'entry', 'comment', etc.)
  • create a unique numeric id for each specific object you want to rate.

In the sidebar photo example, let's choose the type "sidebarphoto" and give each photo a numberic id from 1 to 5. For the first photo, I would use the following code to display a star rater:

<$MTAjaxStarRater type="sidebarphoto" id="1" max_points="5"$>

...and the second photo would be:

<$MTAjaxStarRater type="sidebarphoto" id="2" max_points="5"$>

... and so on.

Also note that the discussion above about dynamically updating ratings and vote counts also applies to non MT objects -- just be sure to use your chose "type" and "id" values in the span ids.

The features above are just a few advanced ways to use Ajax Rating. To get Ajax Rating, or to learn more, click here.

Look forward to the next article (soon) on Ajax Rating: Setting Comment Threshold Viewing.