Star Rating for Reviews

Star Rating for Reviews is a simple WordPress plugin that inserts pretty rating stars based on the score you assign using intuitive, inline [rating:] tags. It can also calculate and output overall ratings for you based on all previous scores you have assigned, useful for reviews that have multiple categories or an album review where each track is assigned a score.

This plugin supports storing rating data into your WordPress database. These data can then be retrieved by functions provided to output a list of reviews, sortable by date, post title or rating scores. Random reviews function and single post function (to be used in WordPress loop) are also provided, see Usage section for detailed description of these functions.

Features

• uses simple, intuitive tags to generate kawaii inline rating stars for your posts
• supports versatile rating systems
• supports text only output for RSS
• automatically calculates and displays overall ratings, if desired
• supports storing rating scores automatically into database *
• supports outputting list of reviews sortable by date, post title or rating scores *
• supports widget-like, sortable table of reviews *
• supports custom star images
• supports custom prefixes and suffixes for your own CSS class
• supports globally forced star count for consistency
• uses as many stars as you want! **
• standards compliant: valid XHTML

* database writing has to be enabled via Options
** limited to 20 for practicality

Usage

Presentation

Once installed, you can add rating stars to your posts by using [rating:] tags.

Normal rating:

By default, this will be interpreted as 3.5/5, as shown in the rating stars generated. Default denominator can be changed via options detailed in the next section. Even though this tagging style is simple, it might not be future proof when someday you decided to change the default denominator to say 10 (for whatever reason). In this case 3.5 will be interpreted as 3.5/10, which is very different compared to 3.5/5. Once you start using this tagging style, make sure you are not going to change the default denominator in the future. :)

“3/4″ will generate a “3 out of 4 stars” rating and “2/8″ will generate “2 out of 8 stars” and so on. This will continue to work as long as the denominator is not larger than 20. Beyond that, the score will be normalized and display in the default 5 stars system, as shown in the next example.

The “Rating:” prefix you can see in all examples above is the default prefix, which you can remove easily to show just the stars or add in your own custom CSS class by changing some options. More information about this in the Options section.

 

Overall rating:
Automatically calculated overall rating based on previous scores can be inserted using the following tag style:

Similar to the first example, this overall rating will be represented in the default 5 star rating system. It is possible to force the overall rating to be outputted in different number of stars by using the following tag style:

The “Overall Rating:” is again, the default prefix, which can be changed via options. For more information, see Options.

Demo review

 

Custom images:
First of all, the default star image used is taken from the excellent Silk icon set. These png icons support different background colours via png transparency. However, you can still use your own star images by replacing the 3 images included in the “star-rating” plugin folder, namely “star.png”, “halfstar.png” and “blankstar.png”. File extensions can be changed via options if desired.

For your information, “tiny-star.png”, “tiny-halfstar.png” and “tiny-blankstar.png” are only used by special functions that output list of reviews based on stored data in the database. Feel free to replace them with your own images as well if desired.

 

Text only output:
By default, this plugin will output text only ratings for your RSS feeds and use graphical output when someone is reading the post on your site. This is, in my opinion, the optimal choice since some RSS readers do not support images. However, if you like you can output images for your RSS feeds too, or oppositely, output text only ratings for both RSS and posts displayed on your site. Please refer to the Options section if you want to make these changes.

Demo feeds

 

Data (for advanced users)

Database writing is turned off by default. In order to use these advanced features, you will need to manually turn it on by changing the option values, see Options for more details. If you are not interested in this feature, you should skip this section.

Custom fields
If database writing is turned on, this plugin will parse your document searching for rating tags and store the overall rating score into a custom field called “rating” when you edit or save your blog post. The name of the custom field can be changed via options to prevent conflict with other plugins. The reason why custom field is used instead of a new database table is the ease of implementation and the fact that most people write reviews occasionally. The downside of this is when uninstalling this plugin, you will need to manually remove those “rating” entries within the custom field table.

To check if this plugin is doing its job, once you turned on the database writing, go to edit one of your older posts which already used the rating tags (or simply insert the rating tags into any post if you’re new to this plugin) and choose “Save and Continue Editing”. Now, check the custom field near the bottom of the editing panel to see if a new “rating” field has been added. If it’s there, congrats, this plugin is working properly; if it’s not, you might have forgotten to turn on the database writing option, or the rating tag is invalid. Feel free to post your questions here (with detailed explanation) if you can’t get this to work.

Once you turned on this auto insert feature, you can still disable it for specific post by putting [rating:none] anywhere in your blog post, preferably at the bottom for tidyness.

 

Functions
4 different functions are provided in this plugin that allow you to output a list of reviews based on date, rating score, or randomly selected. These functions uses “rating” custom field data to retrieve and sort the reviews. You need to either turn on autometa (see Options) or manually put these rating in yourself.

1. sr_getreviews()

sr_getreviews($limit, $orderby, $order, $usestar, $prefix, $suffix)

$limit
- number of reviews to be returned
Acceptable value: any integer
Default value: 5

$orderby
- criterion used to sort the review
Acceptable value: “date”, “title”, “rating”
Default value: date

$order
- sort ascendingly or descendingly
Acceptable value: “ASC”, “DESC”
Default value: “DESC”

$usestar
- number of star to be used for rating
Acceptable value: any integer
Default value: 5
Note 1: put in “0″ to output rating in percentage i.e. numerically
Note 2: rating stars used are with tiny prefix (tiny-star.png, tiny-blankstar.png etc.), they are smaller than regular stars in blog post

$prefix
- prefix to be put before the code for each reviews
Acceptable value: any valid XHTML tags or plain text
Default value: “<li>”

$suffix
- suffix to be put after the code for each reviews
Acceptable value: any valid XHTML tags or plain text
Default value: “</li>”

 
You can also output ratings in percentage format as illustrated below:

 

2. sr_getrandom()

sr_getrandom($limit, $usestar, $prefix, $suffix)

See the explanation above for each parameter.

 

3. sr_listreviews()

sr_listreviews($orderby, $order, $usestar, $date, $limit)

This outputs list of reviews in a widget-like, sortable table format. (implemented using the awesome tablesorter plugin for jQuery)

$date
- format of date to be used
Acceptable value: PHP date format
Default value: “M j, Y”

$limit
- number of reviews to be returned
Acceptable value: any integer
Default value: “0″
Note: “0″ limit implies no limit i.e. retrieve all available reviews

Date	Title	Rating
Tips: Shift+Click to sort multiple columnsPowered by Star Rating for Reviews
2009-04-30 Apr 30, 2009	Kuroki Meisa debuts Hellcat	71.3
2009-03-25 Mar 25, 2009	Perfume – One Room Disco	70
2009-02-02 Feb 2, 2009	Hinouchi Emi – ME…	75.3
2009-01-31 Jan 31, 2009	Nishino Kana – MAKE UP	85
2009-01-12 Jan 12, 2009	Perfume – Dream Fighter	95
2009-01-07 Jan 7, 2009	Proposal Daisakusen	90
2009-01-05 Jan 5, 2009	Arashi – truth/Kaze no Mukou e	93.3
2008-12-22 Dec 22, 2008	Ai Otsuka – Kurage, Nagareboshi	90
2008-12-17 Dec 17, 2008	GREEN/Days	95
2008-10-10 Oct 10, 2008	Aira Mitsuki – COPY	60

 

4. sr_getsingle()

sr_getsingle($post_id, $usestar, $prefix, $suffix, $size)

This function is intended to be used within the WordPress Loop. You can put this within the loop to display rating score or stars in categories, tags, or main page for each posting. See examples: categories, tags, main page.

$post_id
- the ID of current post within the loop
Acceptable value: $post->ID

$prefix, $suffix
- prefix, suffix to be added before and after the ratings code returned
Acceptable value: any valid XHTML tags or plain text
Default value: ” (empty)

$size
- the size of stars, can be normal or tiny
Acceptable value: 0, 1 (0 for tiny stars, 1 for normal stars)
Default value: 0

For $usestar, see the sr_getreviews().

Customization

Starting from version 0.4, a default CSS is imported into the WordPress header, which I hope will work nicely with your blog theme. If not, feel free to open the CSS and edit it or disable the CSS import by setting $sr_mycss to 1, which will remove all the default styling for CSS classes associated with this plugin.

By default, ratings and reviews returned by listing functions are hardcoded with special CSS classes, namely “sr-review” for the review permalink and “sr-rating” for the ratings returned, which can be either numerical percentage or star images.

You might want to take a look at another plugin I’ve written called “MyCSS”, which allows you to attach and edit custom stylesheet that’s independent of the blog theme you’re using. This makes it convenient and easy to organize theme independent CSS classes such as those used in plugins, saving you the trouble of appending these classes into your theme’s core CSS everytime you change a theme.

Options

Hopefully this plugin will work as desired in an “out of the box” way so that you don’t need to change anything. However, several extra options are still provided for those of you who would like to have it your way. :)

Since this plugin is still in its early stage, setting options in the WordPress admin panel is not supported yet. For now, you will need to open up the php file using either your favourite text editor or WordPress built-in plugin editor to change some of the variables you can find near the top of the code.

• $sr_limitstar: globally set star count, e.g. putting 5 will ALWAYS generate your score using the 5 star rating system, put 0 to disable this feature
• $sr_defaultstar: default denominator when not explicitly specified in your tags
• $sr_prefix: custom prefix for normal ratings
• $sr_allprefix: custom prefix for overall ratings
• $sr_suffix: custom suffix, leave blank unless you want to close html tags
• $sr_ext: file extensions for custom star images, e.g. gif, jpg, png
• $sr_usetext: text only output settings, accepted values are 0, 1 and 2
  0: images for posts and feeds
  1: images for posts, text for feeds
  2: text for all
• $sr_mycss: using your own CSS? if yes, put in 1 to disable default CSS import
• $sr_cuttitle: shorten post title to specific amount of character, put 0 to disable title cut off

The following are advanced options, mainly to turn on the functionality of storing ratings into database as custom field values:

• $sr_autometa: 0 to turn off database writing, 1 to turn it on, this feature is disabled by default (it’s stable, I’m just leaving the choice up to advanced users)
• $sr_metakey: meta key for custom field, change this if there’s conflict with other plugins

Installation

1. Download and extract the “star-rating-for-reviews” folder
2. Upload the “star-rating-for-reviews” folder to your WordPress plugin directory, usually “wp-content/plugins”
3. Activate the plugin in your WordPress admin panel

Upgrade

1. Deactivate the plugin in your WordPress admin panel
2. Remove the “star-rating-for-reviews” folder in your WordPress plugin directory
3. Follow the installation guide above

Download

Star Rating for Reviews plugin 0.4 for WordPress (30kb .zip)

Please donate to support active development of this plugin, thank you!

If you like this plugin, express your love by donating and sharing this plugin with your readers!

Support

If you have any questions, suggestions, or found any bugs in this plugin, feel free to post them in your comments. I’ll try my best to answer them but there’s no guarantee, so don’t be disappointed if you do not hear back from me promptly. :/ If you find this plugin useful and feel like donating some money for my effort, please use the PayPal button above, thanks! <3

History

0.4 [2007.11.02]

• Added: Sort reviews by title
• Added: sr_listreviews() function to output all reviews in a sortable table (good for dedicated review page)
• Added: Default CSS stylesheet (can be turned off via options)
• Added: Cut off long title when getting list of reviews for sidebar
• Changed: XHTML markup for list of reviews generated
• Changed: Tiny star images
• Fixed: Division by zero if overall tag is placed at the top of a post
• Misc: Cleaned up the code and fixed minor bugs

0.3.1 [2006.09.12]

• Fixed: Sorting bugs

0.3 [2006.08.08]

• Added: Support to store rating data into database
• Added: Functions to output list of reviews, sortable by date or by rating scores
• Added: Filter to parse excerpt
• Added: Skip tag parsing by using ` character (suggested by Denis)

0.2 [2006.07.28]

• Fixed: Path error
• Fixed: [strong] instead of [b] for W3C standards
• Fixed: RSS text output bug

0.1 [2006.07.08]

• Initial release