Adding ratings to articles

Enable Ratings module and hook it to articles

Simple enough, you'd think. Well, I already had Ratings enabled, I guess I had played with it before, and had toyed with various configurations like should it be 5-stars, or x-out-of-ten, or x%, so when I settled on 5-stars, some existing rated articles should have been 100 but were actually 10's. I dont know, but deactivating/uninstalling, then re-installing the module cleared the db table and took care of that anomoly.

Then I hooked Ratings to just specific pubtypes in the Ariticles module. Well, that seemed to work fine for a while. Eventually though I had to change it to hook to all pubtypes. Why? I wanted a mix of any rated pubtypes in a topitems block. Xaraya apparently wont let you do that, either hook it to all pubtypes and enable all pubtypes in the block, or you're limited to one pubtype in the block. I opted for the former and just made sure the display template for each pubtype that does not support ratings skips that hook. See the xaraya bug i filed.

I configured it for medium security- users can vote once per session. Actually I dont really care, but while testing I noticed that after someone votes, it may not be obvious that the vote was recorded so they might click it multiple times. But with the security, the voting widget disappears once the vote is recorded. Cool!

Setup Ratings Config and Template

For this I configured it as 5 star.

The default template handles all the options. One thing that bothered me about the star display is it's not necessarily obvious that the value is "x out of 5" when you only display x stars. Also the star icons that come with the module are the wrong color, so I created 3 new icons:

• star.gif
• starhalf.gif
• starnone.gif

I also thought the default icons (16 x 16) were too big for my site, so I made these 12 x 12 pixels.

So the next step was modifying the ratings user display template so it shows the extra empty stars. Here's the template, stripped of the styles I know I'm not using:

<xar:comment> License: GPL <a href="http://www.gnu.org/copyleft/gpl.html" target="_blank">http://www.gnu.org/copyleft/gpl.html</a> </xar:comment> <xar:comment> try to eliminate spaces between star bitmaps </xar:comment> <xar:if condition="!($intrating eq 0 and $fracrating eq 0)"> <xar:mlstring>Visitor rating:</xar:mlstring> <xar:for start="$i = 0" test="$i lt $intrating" iter="$i++"><img src="themes/twindaction2/images/star.gif" alt="star" /></xar:for><xar:if condition="$fracrating ge 5"><img src="themes/twindaction2/images/starhalf.gif" alt="half star" /><xar:if condition="$i++"></xar:if></xar:if><xar:for start="$i" test="$i lt 5" iter="$i++"><img src="themes/twindaction2/images/starnone.gif" alt="no star" /></xar:for> </xar:if> <xar:if condition="empty($rated)"> <xar:if condition="xarSecurityCheck('CommentRatings',0)"> <form method="post" action="&xar-modurl-ratings-user-rate;" id="post" name="formrating" enctype="application/x-www-form-urlencoded" > <span style="font-style:italic">Rate this item: </span> <select name="rating" id="rating" size="1" onchange="submit()"> <option value="0" selected="selected">Select...</option> <option value="20">1 star (worst)</option> <option value="40">2 stars</option> <option value="60">3 stars</option> <option value="80">4 stars</option> <option value="100">5 stars (best)</option> </select> <input type="hidden" name="returnurl" id="returnurl" value="#$returnurl#" /> <input type="hidden" name="modname" id="modname" value="#$modname#" /> <input type="hidden" name="itemtype" id="itemtype" value="#$itemtype#" /> <input type="hidden" name="objectid" id="objectid" value="#$objectid#" /> <input type="hidden" name="authid" id="authid" value="#$authid#" /> </form> </xar:if> </xar:if>

Notice I had to eliminate nice formatting in the loop with the <img> tag so no extra spaces were placed between images.

I also don't display any stars if the item is not rated (actually if the rating is zero, which is good enough). That's what's going on in the first if-statements.

As a result, i get something like this:

For the form to vote a new rating, the default template has the user pick a value from the dropdown list and then click a submit button. I thought many users would not realize they need to click the button so their vote would not get recorded. Also, the dropdown shows a default value of "3", not sure why but some users might confuse that with the current total ratings value. So I eliminated the zero choice and the submit button, and added onchange="submit()" to the <select>. That works very nicely :)

Articles Templates

The next step is to update the Articles templates to show the current ratings and allow visitors to rate items.

For each pubtype which I wanted to allow rating, i edited its user-display-xxx.xt template. The current rating should be after the title, on the line where I show the date, author, and publication information. It turned out to look best if I floated it to the right, thus,

<div class="xar-sub" style="float:right; font-style:italic; padding:0 0 1em 1em" > #$hooks['ratings']# </div>

and then at the bottom of the template, skip the default location for this hook:

<xar:foreach in="$hooks" key="$hookmodule"> <xar:if condition="$hookmodule eq 'ratings'"><xar:continue /></xar:if> #$hooks[$hookmodule]# </xar:foreach>

Be sure the Articles Config for each pubtype has Show Ratings checked.

Enable for Anon Visitors

By default anonymous visitors don't have permission to rate articles. I added a priv as follows to my priv group named "CasualAccess":

name: RatingsVote
module: Ratings
Component: Item
Level: Comment

That should do it so users can rate the articles and see the ratings on article display.

Ratings in the Article Summary Template

Well, I also want the ratings to show in the articles view / summary page. This wasn't as obvious. It seems the ratings user-display template is not called for item summaries (only item display). However, fortunately, the rating value is available.

So, to format the value, I created a new template in mytheme/modules/ratings/includes/displayratings.xt that shows the stars like the ratings/user-display.xt template, without the input form:

<xar:comment> basically dups whats in ratings/user-display.xt, without the input form, for articles view/summary and blocks </xar:comment> <xar:if condition="!empty($rating)"> <xar:set name='rating'>(int)($rating/2)</xar:set> <xar:set name="intrating">(int)($rating/10)</xar:set> <xar:set name="fracrating">$rating - (10*$intrating)</xar:set> <xar:for start="$i = 0" test="$i lt $intrating" iter="$i++"><img src="themes/twindaction2/images/star.gif" alt="star" /></xar:for><xar:if condition="$fracrating ge 5"><img src="themes/twindaction2/images/starhalf.gif" alt="half star" /><xar:if condition="$i++"></xar:if></xar:if><xar:for start="$i" test="$i lt 5" iter="$i++"><img src="themes/twindaction2/images/starnone.gif" alt="no star" /></xar:for> </xar:if>

Then in each pubtype's summary template, I insert the following line where I want it to go:

<xar:template type="module" module="ratings" file="displayrating" />

Top Rated Items Block

The last step is to create a topitems block with the top rated items.

I created a block, type articles/topitems, as follows:

name: toprated
title: Top Rated
number of items: 30
all publication types: checked
link to publication type: checked
all categories: checked
dynamic block title: unchecked (doesnt matter)
sort by: Rating
show sort value: checked
show summary: (doesnt matter)
status: All pubished

and

Instance Template: ;ratings

Then, I modified the default topitems.xd template, saved as mytheme/modules/articles/blocks/topitems-ratings.xt as follows:

<xar:if condition="!empty($items)"> <xar:foreach in="$items" value="$item"> <xar:comment><pre><xar:set name="asdf">print_r($item)</xar:set></pre></xar:comment> <xar:set name="rating">$item['rating']</xar:set> <xar:if condition="$rating eq 0"><xar:continue /></xar:if> <div style="padding:1em"> <xar:template type="module" module="ratings" file="displayrating" /> <xar:if condition="empty($item['link'])"> #$item['title']# <xar:else /> <a href="http://www.vaporbase.com/index.php#$item['link']#">#$item['title']#</a> </xar:if> <span style="font-size:90%; color: #888"> <xar:set name="datestr">xarModApiFunc('misctools','user','shortdate',array('date'=>$item['pubdate']))</xar:set> (#$datestr#) <xar:foreach in="$item['cids']" value="$cid"> <xar:set name="isloc">xarModAPIFunc('categories','user','isdescendant',array('cid'=>$cid, 'branch'=>'53'))</xar:set> <xar:if condition="$isloc"> <xar:set name="locname">urldecode(xarModAPIFunc('categories','user','cid2name',array('cid'=>$cid)))</xar:set> [#$locname#] </xar:if> </xar:foreach> <span style="font-style:italic">in <a href="http://www.vaporbase.com/index.php#$item['pubtypename']#?sort=rating">#$item['pubtypedescr']#</a></span> </span> <xar:if condition="!empty($item['summary'])"> #xarModAPIFunc('misctools','user','truncate_string', array('string' => $item['summary'], 'length' => '50', 'type' => '1', 'alt_text' => '...'))# </xar:if> </div> </xar:foreach> </xar:if>

This is probably more detail than anyone cares about but briefly, walking through the code,

• dont do anything if there's no items
• loop through each item
• commented out the dump item data
• define a variable $rating from the current item
• if the rating is 0, then skip it (we only want to show rated items in this block)
• display the rating stars, using <xar:template > tag
• the rest is not related to this article but is (will be) discussed in another posting

See the results at http://www.windaction.org