• View
• Edit
• History
• Attach
• Print
• Backlinks

StarRater

Description

This recipe provides a 5 star rating system, showing a star image based on the average rating of an item. Multiple items are supported. Supports either 5 or 6 choices (with zero vote)

non-functional screenshot image:

color choices:

Installation

Download rater.zipΔ. Copy included rater.php to cookbook directory, and star images to a pub/rater/img directory. Inlude recipe in config.php with

include_once('cookbook/rater.php');

Usage

Add markup (:rater [id] [name] [other options...]:) to a page. This will show a stars image, rating statistics and a rating form with radio buttons for choices and submit button.

Markup Options

• id - this identifies the rater, necessary if multiple rater markup directives are used on the page. First word/number after rater. Default id if not supplied is 1.
• name - optional item name for the heading, second entry in markup; if not given the default is this item, ie. a heading of Rate this item.
• head="template string" - optional template for header. Default is !!!!!Rate {name}
• stats="template string" - optional template for rating statistics. You can use inline markup and wiki styles. A number of special replacement variables can be used to show various rating formats and number of votes:
  • {votes} - number of votes cast.
  • {ratingA} - a verbal text rating using the choices given.
  • {ratingB} - star number with one decimal place, ie. highest rating is 5.
  • {ratingC} - percent number, i.e. highest rating is 100.
  • {ratingD} - 'out of ten' number, with one decimal place, ie. higest rating is 10.
• allvotes=1 - will show vote distribution as extended statistics.
• allvotes=0 - will suppress vote distribution stats, if it was generally enabled with a variable in config.php
• 5star='Very Good' 4star='Good' 3star='Fair' 2star=Okay 1star=Poor - example of optional alternative rating choice settings, choose your own terms for individual rater markup. The defaults can also be changed via variable settings in config.php.
• label="text" - optional alternative button label.
• color=keyword - optional choice of star colors. At present you can choose from 'yellow' (default), 'orange', 'red', 'green', 'blue', 'violet' and 'gray'.
• zero=1 - will show zero star rating choice (six choices instead of five).
• reverse=0 - will show radio buttons in reverse order.

Page Text Variable {$:Rating'id'}

The rating score is accessible with a hidden page text variable {$:Ratingid} whereby id is the id used in the markup (default 1 for one rater markup in a page). It holds the average rating score as a number between 0 and 100 with 2 decimal places. When rating a PTV gets automatically created or updated. The $:Rating.. PTVs can be used to generate pagelists ordered by ratings etc.

Markup Expression {(rater ...)}

{(rater 'rating' 'fmt' 'color')}

This markup expression will be rendered either as a stars image or a number format or a verbal output.

rating

The input 'rating' can be a Rating PTV for dynamic output, or a rating number between 0 - 100 for static output. The expression can also be used in pagelist templates, to show the rating stars or values associated with a rating PTV, for instance for page ratings (1 item per page). See below for template example.

fmt

The output format. Use 'stars', '100', 10, '5' or 'verbal'. The number correspond to the rating base: out of 100, out of ten, out of five.

color

A color choice for the stars image. Choose from 'yellow' (default), 'orange', 'red', 'green', 'blue', 'violet' or 'gray'.

Config Options

There are numerous options for config settings to change default variables, messages, templates, choice texts, default star color, button order reversal, directory locations. See the rater.php script top sections with SDV variable settings. All SDV variables can be set in config.php (without using SDV) before including the rater.php script. For instance

$Rater['star_color'] = 'red';
$Rater['reverse_buttons'] = 0; 
$Rater['button_text'] = 'Vote';
$Rater['zero_choice'] = 1;
$Rater['header'] = "!!!!!Vote for {name}";
$Rater['5star'] = "Very Good";
$Rater['4star'] = "Good";
$Rater['3star'] = "Fair";
$Rater['2star'] = "Okay";
$Rater['1star'] = "Not Good";
$Rater['0star'] = "Avoid";
$Rater['ip_voting_restrictions'] = false; # if you want to allow multiple votes from the same IP
$Rater['ip_vote_qty'] = 3; # if you want to allow as many as 3 votes from the same IP

Notes

Ratings are stored in log files, one file for each rated item, by default in directory pub/rater/logs/. The log files are named by full pagename and item id. Each rating action stores the choice made, the user's ip address, and his/her authid or author name. The ip address is used to prevent multiple voting from same ip. The user name is not currently used. Perhaps it will be in a future version allowing vote weightings by user.

Page Ratings

You can add the rater markup to a GroupHeader page to appear in and function for all pages of the group. Exclude it from the index page and any other pages with conditional markup.

Rating pagelists

If your pages contain one rater markup per page to collect user's ratings of the item shiown on th epage, you can compile a pagelist which shows the pages ordered by rank of rating, including their stars image or other rating value. Here is an example for recipe pages in a Cookbook group:

Rater markup in GroupHeader:

Pagelist markup for an index page:

Custom pagelist template (outputs a table format with some border styling):

!!!#rateridx
Pages ordered by rating, displayed by title and star rating.
[[#rateridx]]
(:template first:)
(:table style='width:30em; border:1px solid #ccc; margin:0; padding:0;':)
(:cellnr style='border-bottom:1px solid #ccc':)'''Page''' 
(:cell style='border-bottom:1px solid #ccc':)'''Rating''' 
(:template each:)
(:cellnr style='border-bottom:1px solid #ccc':) [[{=$FullName}|+]] 
(:cell style='border-bottom:1px solid #ccc':){(rater {{=$FullName}$:Rating1} stars green)} 
(:template last:)
(:tableend:)
[[#rateridxend]]

The template should best be copied to Site.LocalTemplates

Release Notes

• 2008-09-03: Added _(underscore) and -(hyphen) as allowed characters for rater id. Any other not allowed characters (like .(dot)) will be replaced by _. Added optional reverse and zero parameters. Fixed url when voting.
• 2008-07-11: Revised formula for rankings. Added option for choice of zero star vote (set $Rater['zero_choice'] = 1;).
• 2008-07-09: Added markup expression {(rater ....)}. Added star color choices. Changed default dir variables. Added variable to reverse radio button order.
• 2008-07-08b: Added pagelist option order=Rating for creating pagelists by numerical order of values from $:Rating1 PTVs.
• 2008-07-08a: Added check for auth level. Default auth level to vote is 'read'.
• 2008-07-08: Added ptv add/update function and automatic creation/updating of Ratingid PTV.
• 2008-07-07b: Fixed creation of empty log files. Adjusted markup sequence.
• 2008-07-07: Initial release.

If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".

See Also

Contributors

Comments