• 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 images:

Available color options:
The same color will be used for all star types. Default is yellow.
The image shows also the various star types, in declining order of rating value, but not all of them.

Installation

• download rater.zipΔ
• copy included rater.php to cookbook/ directory
• copy the star images to a pub/rater/img/ directory
• include the recipe in config.php with

• add optional configuration options

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. highest 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.

If you need a rating PTV before any rating has occurred, add the PTV manually to the page, like (:Rating'id': unrated:). Choose a value like 'unrated' or 0 or something else you like to see in your listing. Insert the right 'id' for the PTV name, the default would be 1, i.e. a PTV (:Rating1: 0:) works when no id is set in the rater markup.

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['authid_voting_restrictions'] = true; # if you want voting restrictions 
//based on logged-in AuthId instead of IP. For internal wikis. 
$Rater['ip_voting_restrictions'] = false; # if you want to allow 
//multiple votes from the same IP
$Rater['vote_quantity'] = 3; # if you want to allow 
//as many as 3 votes from the same user or 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. Alternatively the user name can be used to prevent multiple voting, but this would need installation of AuthUser to have users login with a username (best for internal wikis). Perhaps it will be in a future version it also can be expanded to allow 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 shown on the page, 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):
This template should best be copied to Site.LocalTemplates, or otherwise included on the page with the pagelist markup and enclosed in (:if false:)......(:ifend:)

!!!#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]]

Release Notes

• 2014-10-09: updated markup definition for PHP 7.2 compatibility
• 2014-10-09: updated markup definition for PHP 5.5 compatibility (missed one markup in previous update).
• 2014-02-21: updated markup definition for PHP 5.5 compatibility.
• 2009-10-15: Added $Rater['rating_in_summary_unit']; fixed RC summary to suppress rater id if only 1 rater without id.
• 2009-10-14: Added $Rater['rating_in_summary'] for enabling display of rated value in RecentChanges summary.
• 2009-10-12: Fixed HTML elements which led to XHTML validation errors.
• 2009-08-01: Added $Rater['authid_voting_restrictions']. Changed $Rater['ip_vote_qty'] to $Rater['vote_quantity'].
• 2009-07-06: Added condition to prevent rater showing on pages which do not exist.
• 2009-05-19: Changed previous fix to set 'anonymous' as author if no author and author is required.
• 2009-05-15: Fixed bug which prevented updates of Rater PTVs when $EnablePostAuthorRequired was set to true, and user was not logged in.
• 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

See discussion at StarRater-Talk