WP-PostRatings

FAQ

How do I change the colour of the ratings?

Go to WP-Admin -> Ratings -> Settings and look under Individual Rating Text and Value. Each step on the scale has its own pair of colour swatches, in the Rated and Not rated columns, which is what the old stars_crystal and stars_dark image sets were for.

Hovering uses the rated colour. If you would rather tell “about to pick” apart from “already recorded”, set --wp-postratings-color-hover in your theme.

How do I change the size, spacing or hover colour?

Anything beyond the two colours is a CSS custom property on .wp-postratings, so this is all it takes in your theme:

.wp-postratings {
    --wp-postratings-size: 24px;
    --wp-postratings-gap: 4px;
    --wp-postratings-color-hover: #f7c56b;
}

Before 2.0.0 a different colour meant a whole extra folder of images, which is why the plugin shipped stars, stars_crystal and stars_dark separately. They are all the same shape now.

How do I use my own rating shape?

Register it with the wp_postratings_shapes filter. It then appears on the Ratings Options screen like any built-in shape, and unlike the old approach of dropping a folder into wp-content/plugins/wp-postratings/images/, it survives an update.

add_filter( 'wp_postratings_shapes', function ( $shapes ) {
    $shapes['diamond'] = array(
        'type'  => 'scale',
        'label' => 'Diamonds',
        'path'  => 'M12 2l10 10-10 10L2 12z',
    );

    return $shapes;
} );

The path is SVG path data drawn in a 24×24 box. For an up/down control use 'type' => 'updown' and supply 'up' and 'down' paths instead of 'path'.

Every visitor can rate over and over, or every rating log entry shows the same IP

This is about the Header That Contains The IP field on the Ratings Options screen.

Leave it blank unless your site is genuinely behind a reverse proxy or CDN such as Cloudflare. Blank means the plugin uses the address your web server actually saw, which is what you want on a normal host.

If you are behind a proxy, name the exact header your proxy sets, for example HTTP_CF_CONNECTING_IP for Cloudflare or HTTP_X_FORWARDED_FOR for most load balancers. Two things are worth knowing:

• A visitor can send any header they like. If you name a header your own stack does not set and overwrite, anyone can put whatever they want in it and rate as many times as they please.
• X-Forwarded-For is a list, client, proxy1, proxy2. As of 2.0.0 the plugin reads the first valid address in that list rather than storing the whole string. Before 2.0.0 it stored the whole string, which meant a visitor could append one more address and appear to be somebody new on every request.

Because the stored value has changed shape, rating logs recorded through such a header before 2.0.0 will not match any more, and some visitors may be able to rate one more time. Logs recorded without the field set are unaffected.

How To Change Schema Type?

<?php  
add_filter( 'wp_postratings_schema_itemtype', 'wp_postratings_schema_itemtype' );  
function wp_postratings_schema_itemtype( $itemtype ) {  
    return 'itemscope itemtype="https://schema.org/Recipe"';  
}  
?>

The default schema type is ‘Article’, if you want to change it to ‘Recipe’, you need to make use of the wp_postratings_schema_itemtype filter as shown in the sample code above.

How To Add Your Site Logo For Google Rich Snippets

<?php  
add_filter( 'wp_postratings_site_logo', 'wp_postratings_site_logo' );  
function wp_postratings_site_logo( $url ) {  
    return 'https://example.com/logo.png';  
}  
?>

By default, the plugin will use your site header image URL as your site logo. If you want to change it, you need to make use of the wp_postratings_site_logo filter as shown in the sample code above.

How To Change The Text Screen Readers Announce?

add_filter( 'wp_postratings_ratings_image_alt', function ( $label ) {
    return $label;
} );

This is the description a screen reader reads out for a displayed rating, such as “4 votes, average: 3.70 out of 5”. Since 2.0.0 the ratings are drawn with CSS rather than images, so there is no alt or title attribute involved; the value becomes the aria-label on the rating.

Returning an empty string removes it, which is what this filter was usually used for. Be aware that it leaves the rating with no accessible name at all, so anyone using a screen reader is told nothing about it. Prefer rewording it over removing it.

How To Display Comment Author Ratings?

add_filter( 'wp_postratings_display_comment_author_ratings', '__return_true' );

By default, the comment author ratings are not displayed. If you want to display the ratings, you need to make use of the wp_postratings_display_comment_author_ratings filter as shown in the sample code above.

How To change the cookie expiration time?

function custom_rating_cookie_expiration() {
    return strtotime( 'tomorrow' ) ;
}
add_filter( 'wp_postratings_cookie_expiration', 'custom_rating_cookie_expiration', 10, 0 );

The default cookie expiration if ‘time() + 30000000’, if you want to change the lenght of the experation, you need to make use of the wp_postratings_cookie_expiration filter as shown in the sample code above.

How Does WP-PostRatings Load CSS?

Most restyling needs no CSS file at all any more: the colours are a setting, and the size, spacing and hover colour are custom properties. See the two questions above first.

If you do want to replace the stylesheet wholesale, WP-PostRatings loads wp-postratings.css from your theme’s directory (or its css/ subdirectory) when that file exists, and its own copy otherwise, so an upgrade will not overwrite your styles.

Note the filename changed in 2.0.0: it was postratings-css.css before. A theme still shipping the old name is simply ignored, and the plugin’s own stylesheet loads instead. There is no separate RTL stylesheet any more either, because the rules use logical properties.

How To Use Ratings Stats With Widgets?

1. Go to WP-Admin -> Appearance -> Widgets
2. The widget name is Ratings.

To Display Lowest Rated Post

<?php if (function_exists('get_lowest_rated')): ?>
    <ul>
        <?php get_lowest_rated(); ?>
    </ul>
<?php endif; ?>

• Default: get_lowest_rated(‘both’, 0, 10)
• The value ‘both’ will display both the lowest rated posts and pages.
• If you want to display the lowest rated posts only, replace ‘both’ with ‘post’.
• If you want to display the lowest rated pages only, replace ‘both’ with ‘page’.
• The value 0 refers to the minimum votes required before the post get shown.
• The value 10 will display only the top 10 lowest rated posts/pages.

To Display Lowest Rated Post By Tag

<?php if (function_exists('get_lowest_rated_tag')): ?>
    <ul>
        <?php get_lowest_rated_tag(TAG_ID); ?>
    </ul>
<?php endif; ?>

• Default: get_lowest_rated_tag(TAG_ID, ‘both’, 0, 10)
• Replace TAG_ID will your tag ID. If you want it to span several categories, replace TAG_ID with array(1, 2) where 1 and 2 are your categories ID.
• The value ‘both’ will display both the lowest rated posts and pages.
• If you want to display the lowest rated posts only, replace ‘both’ with ‘post’.
• If you want to display the lowest rated pages only, replace ‘both’ with ‘page’.
• The value 0 refers to the minimum votes required before the post get shown.
• The value 10 will display only the top 10 lowest rated posts/pages.

To Display Lowest Rated Post In A Category

<?php if (function_exists('get_lowest_rated_category')): ?>
    <ul>
        <?php get_lowest_rated_category(CATEGORY_ID); ?>
    </ul>
<?php endif; ?>

• Default: get_lowest_rated_category(CATEGORY_ID, ‘both’, 0, 10)
• Replace CATEGORY_ID will your category ID. If you want it to span several categories, replace CATEGORY_ID with array(1, 2) where 1 and 2 are your categories ID.
• The value ‘both’ will display both the lowest rated posts and pages.
• If you want to display the lowest rated posts only, replace ‘both’ with ‘post’.
• If you want to display the lowest rated pages only, replace ‘both’ with ‘page’.
• The value 0 refers to the minimum votes required before the post get shown.
• The value 10 will display only the top 10 lowest rated posts/pages.

To Display Highest Rated Post

<?php if (function_exists('get_highest_rated')): ?>
    <ul>
        <?php get_highest_rated(); ?>
    </ul>
<?php endif; ?>

• Default: get_highest_rated(‘both’, 0, 10)
• The value ‘both’ will display both the highest rated posts and pages.
• If you want to display the highest rated posts only, replace ‘both’ with ‘post’.
• If you want to display the highest rated pages only, replace ‘both’ with ‘page’.
• The value 0 refers to the minimum votes required before the post get shown.
• The value 10 will display only the top 10 highest rated posts/pages.

To Display Highest Rated Post By Tag

<?php if (function_exists('get_highest_rated_tag')): ?>
    <ul>
        <?php get_highest_rated_tag(TAG_ID); ?>
    </ul>
<?php endif; ?>

• Default: get_highest_rated_tag(TAG_ID, ‘both’, 0, 10)
• Replace TAG_ID will your tag ID. If you want it to span several categories, replace TAG_ID with array(1, 2) where 1 and 2 are your categories ID.
• The value ‘both’ will display both the highest rated posts and pages.
• If you want to display the highest rated posts only, replace ‘both’ with ‘post’.
• If you want to display the highest rated pages only, replace ‘both’ with ‘page’.
• The value 0 refers to the minimum votes required before the post get shown.
• The value 10 will display only the top 10 highest rated posts/pages.

To Display Highest Rated Post In A Category

<?php if (function_exists('get_highest_rated_category')): ?>
    <ul>
        <?php get_highest_rated_category(CATEGORY_ID); ?>
    </ul>
<?php endif; ?>

• Default: get_highest_rated_category(CATEGORY_ID, ‘both’, 0, 10)
• Replace CATEGORY_ID will your category ID. If you want it to span several categories, replace CATEGORY_ID with array(1, 2) where 1 and 2 are your categories ID.
• The value ‘both’ will display both the highest rated posts and pages.
• If you want to display the highest rated posts only, replace ‘both’ with ‘post’.
• If you want to display the highest rated pages only, replace ‘both’ with ‘page’.
• The value 0 refers to the minimum votes required before the post get shown.
• The value 10 will display only the top 10 highest rated posts/pages.

To Display Highest Rated Post Within A Given Period

<?php if (function_exists('get_highest_rated_range')): ?>
    <ul>
        <?php get_highest_rated_range('1 day'); ?>
    </ul>
<?php endif; ?>

• Default: get_highest_rated_range(‘1 day’, ‘both’, 10)
• The value ‘1 day’ will be the range that you want. You can use ‘2 days’, ‘1 month’, etc.
• The value ‘both’ will display both the most rated posts and pages.
• If you want to display the most rated posts only, replace ‘both’ with ‘post’.
• If you want to display the most rated pages only, replace ‘both’ with ‘page’.
• The value 10 will display only the top 10 most rated posts/pages.

To Display Most Rated Post

<?php if (function_exists('get_most_rated')): ?>
    <ul>
        <?php get_most_rated(); ?>
    </ul>
<?php endif; ?>

• Default: get_most_rated(‘both’, 0, 10)
• The value ‘both’ will display both the most rated posts and pages.
• If you want to display the most rated posts only, replace ‘both’ with ‘post’.
• If you want to display the most rated pages only, replace ‘both’ with ‘page’.
• The value 0 refers to the minimum votes required before the post get shown.
• The value 10 will display only the top 10 most rated posts/pages.

To Display Most Rated Post In A Category

<?php if (function_exists('get_most_rated_category')): ?>
    <ul>
        <?php get_most_rated_category(CATEGORY_ID); ?>
    </ul>
<?php endif; ?>

• Default: get_most_rated_category(CATEGORY_ID, ‘both’, 0, 10)
• Replace CATEGORY_ID will your category ID. If you want it to span several categories, replace CATEGORY_ID with array(1, 2) where 1 and 2 are your categories ID.
• The value ‘both’ will display both the most rated posts and pages.
• If you want to display the most rated posts only, replace ‘both’ with ‘post’.
• If you want to display the most rated pages only, replace ‘both’ with ‘page’.
• The value 0 refers to the minimum votes required before the post get shown.
• The value 10 will display only the top 10 most rated posts/pages.

To Display Most Rated Post Within A Given Period

<?php if (function_exists('get_most_rated_range')): ?>
    <ul>
        <?php get_most_rated_range('1 day'); ?>
    </ul>
<?php endif; ?>

• Default: get_most_rated_range(‘1 day’, ‘both’, 10)
• The value ‘1 day’ will be the range that you want. You can use ‘2 days’, ‘1 month’, etc.
• The value ‘both’ will display both the most rated posts and pages.
• If you want to display the most rated posts only, replace ‘both’ with ‘post’.
• If you want to display the most rated pages only, replace ‘both’ with ‘page’.
• The value 10 will display only the top 10 most rated posts/pages.

To Display Highest Score Post

<?php if (function_exists('get_highest_score')): ?>
    <ul>
        <?php get_highest_score(); ?>
    </ul>
<?php endif; ?>

• Default: get_highest_score(‘both’, 0, 10)
• The value ‘both’ will display both the most rated posts and pages.
• If you want to display the most rated posts only, replace ‘both’ with ‘post’.
• If you want to display the most rated pages only, replace ‘both’ with ‘page’.
• The value 0 refers to the minimum votes required before the post get shown.
• The value 10 will display only the top 10 most rated posts/pages.

To Display Highest Score Post In A Category

<?php if (function_exists('get_highest_score_category')): ?>
    <ul>
        <?php get_highest_score_category(CATEGORY_ID); ?>
    </ul>
<?php endif; ?>

• Default: get_highest_score_category(CATEGORY_ID, ‘both’, 0, 10)
• Replace CATEGORY_ID will your category ID. If you want it to span several categories, replace CATEGORY_ID with array(1, 2) where 1 and 2 are your categories ID.
• The value ‘both’ will display both the most rated posts and pages.
• If you want to display the most rated posts only, replace ‘both’ with ‘post’.
• If you want to display the most rated pages only, replace ‘both’ with ‘page’.
• The value 0 refers to the minimum votes required before the post get shown.
• The value 10 will display only the top 10 most rated posts/pages.

To Display Highest Score Post Within A Given Period

<?php if (function_exists('get_highest_score_range')): ?>
    <ul>
        <?php get_highest_score_range('1 day'); ?>
    </ul>
<?php endif; ?>

• Default: get_highest_score_range(‘1 day’, ‘both’, 10)
• The value ‘1 day’ will be the range that you want. You can use ‘2 days’, ‘1 month’, etc.
• The value ‘both’ will display both the most rated posts and pages.
• If you want to display the most rated posts only, replace ‘both’ with ‘post’.
• If you want to display the most rated pages only, replace ‘both’ with ‘page’.
• The value 10 will display only the top 10 most rated posts/pages.

To Sort Highest/Lowest Rated Posts

$query = new WP_Query( array(
    'meta_key' => 'ratings_average',
    'orderby'  => 'meta_value_num',
    'order'    => 'DESC',
) );

Or pass the variables in the URL: https://yoursite.com/?r_sortby=highest_rated&r_orderby=desc

Replace desc with asc for the lowest rated posts.

To Sort Most/Least Rated Posts

$query = new WP_Query( array(
    'meta_key' => 'ratings_users',
    'orderby'  => 'meta_value_num',
    'order'    => 'DESC',
) );

Or pass the variables in the URL: https://yoursite.com/?r_sortby=most_rated&r_orderby=desc

Replace desc with asc for the least rated posts.

These examples use WP_Query rather than query_posts(), which the old ones called: query_posts() replaces the main query and WordPress has discouraged it for years. To sort the main query instead, use pre_get_posts.