Follow for free plugins, new theme releases and theme news
Plugin Description
The “Post Rating and Review” plugin offers the possibility to connected visitors to review posts or types of posts that you have created (custom post types). You may define the rating scale yourself.
You can use the plugin in 2 ways:
1. Full activation of reviews management (rating + comment): to allow your users to rate AND leave a comment
2. Enabling rating only: when you want your users to leave a rating but you don’t need to collect their feedback
These features are mainly usable with shortcodes, so without development. Three shortcodes are integrated into the plugin allowing the display of 3 different widgets:
– the “set rating” widget which allows a visitor to leave a rating for a post
– the “display rating” widget which allows you to display the overall rating of a post
– the “rating chart” widget which displays the overall rating of a post as well as a breakdown by rating scale
Enabling review management will automatically display the “rating chart” widget above the list of comments in a single post page without the need of a shortcode. Additionally, you can integrate other widgets on the same page if you wish (for instance, a widget “display rating” at the top of the page).
This plugin integrates schema.org specifications on ratings: microdata (“aggregateRating” type) will be automatically generated when you display the overall rating of a post.
An important point: in this first version, the plugin allows rating only for visitors connected to your site, which seems to us to be the best choice to manage reviews on a website. Nevertheless, a future update may integrate the management of ratings and reviews by non-connected visitors if needed.
I developed this plugin for my own use and then made it as configurable as possible so that it could be used by others. Do not hesitate to contact me if you are missing certain features. I can’t promise you that I will be able to integrate them into a future release for you, but it doesn’t hurt to ask!
Overview of plugin options
You can access and customize the following parameters:
Rating widget general settings
- Rating max (integer): maximum rating that a visitor can assign (usually 5)
- Default star size: size in pixels of the stars displayed in the widgets. This parameter can then be modified when calling a shortcode.
- Step for rating display: display precision of the overall rating (often 0.1)
- Step for rating set: precision for the visitor to assign a rating (I recommend 0.5 or 1)
Rating display settings
- Display overall rating after stars: if yes, the shortcode overall rating (prar_display_rating_for_post) will display the rating in plain text after the stars.
- Display number of ratings after stars: if yes, the shortcode overall rating (prar_display_rating_for_post) will display the number of ratings after the stars.
- Text displayed below user’s rating: indicates the text displayed below a user’s note when the user has already rated (shortcode prar_set_rating_for_post). The text {note} will be replaced by the rating given by the user.
Rating recording settings
- Text displayed after rating update: this text will be displayed under the widget when the visitor validates his rating (shortcode prar_set_rating_for_post). After a few moments, this text will disappear and be replaced by the text defined in “text displayed below the user note” option field.
- User can change rating after submission?: if yes, the visitor can modify his rating even after submission. If not, the visitor will be able to modify his note as long as he does not leave the page; if he leaves the page and then returns, the rating will no longer be editable.
- Save overall rating and number of ratings in post meta? : if yes, the overall rating as well as the number of ratings will be updated in the meta of the post that the visitor rated. You can then choose the name of the fields that will be saved (meta_key in the postmeta table) and what type of meta you want to use (Meta WordPress as standard, ACF field if you use ACF and you have created a custom field to store these values ).
Reviews management settings
Enable review management? : if yes, the management of reviews will be activated. Then choose the type or types of post for which you want to activate this management of reviews. Then indicate which fields are mandatory for a visitor to be able to submit their review (N.B. at least one of the 2 fields must be selected as mandatory).
Tools
- By clicking on the “Start database reset” button, all datas stored by the plugin will be erased. This can be useful in the development phase to test your site and dump the data from your tests before going live.
Rating Management Shortcodes
Three shortcodes display a Rating widget. You can integrate these shortcodes in several ways: in the Gutenberg editor, in the Classic Editor, in a widget or even directly in your templates.
You can also integrate several rating widgets on the same page: for example, if you integrate the shortcode at the top and bottom of the page, the validation of the rating with one of rating widgets will trigger the update of the other widgets present on the page.
- Shortcode to give a rating
[prar_set_rating_for_post]
Example: [prar_set_rating_for_post post_id=”153″ step=”0.5″ size=”32″ update_after_vote=”false”]
Optional parameters accepted in the shortcode:
* post_id (numeric): id of the post that will be rated by the visitor. If the parameter is not specified, the plugin will use the active post.
* size (numeric): size in pixels of the stars displayed. By default, uses the size defined in the plugin options.
* step (numeric > 0 and <= 1): by default, uses the value indicated in the options of the plugin.
* readonly (true/false): displays the read-only widget that cannot be modified by the visitor. This can be useful to show the visitor the rating he gave to a post (for example in a My Account section).
* class (text): css class that will be added to the widget to facilitate formatting customization
* external_id (numeric): this is the id of a post attached to the post_id you specified. Example of use: you have created two types of posts “Books” and “Writers”, each book being attached to a writer. You call the shortcode for a book and you provide the writer’s post_id in the “external_id” parameter. The plugin will store the writer’s id along with book’s post id. It will allow you to display the writer’s overall rating on his page: this rating will be based on all of his books that have been rated by visitors on your website .
* update_after_vote (false / true): by default filled by the value indicated in the options of the plugin. If false, visitors will not be able to change their rating once they leave the page. When visitors return to the page, they will see the rating they gave but will not be able to modify it. If true, the note will be editable at any time by the visitor.
- Shortcode to display overall rating
[prar_display_rating_for_post]
Example: [prar_display_rating_for_post post_id=”153″ size=”32″ display_compteurs=”true”]
Optional parameters accepted in the shortcode:
* post_id (numeric): id of the post for which you want to display the overall rating. If the parameter is not specified, the plugin will use the active post.
* size (numeric): size in pixels of the stars displayed. By default, uses the size defined in the plugin options.
* step (numeric > 0 and <= 1): by default, uses the value indicated in the options of the plugin.
* display_compteurs (true/false): if true, the overall rating as well as the number of ratings will be displayed next to the widget.
* class (text): css class that will be added to the widget to facilitate formatting customization
* user_id (numeric): if the id of a user is indicated then the behavior will depend on the post_id and external_id parameters. Below are the different cases:
user_id filled in alone: the widget will display the overall rating of a given user (average of all his ratings)
user_id with post_id: the widget will display the rating given by the user to the post
user_id with external_id: the widget will display the overall rating of all ratings given by the user and linked to this external_id.
* external_id (numeric): this is the id of a post attached to the post_id you specified (cf. shortcode prar_set_rating_for_post). If filled in alone (without user_id or post_id), then the widget will display the overall rating of all ratings assigned to this external_id.
- Shortcode to display overall rating + detailed rating chart
[prar_display_rating_chart_for_post]
Example: [prar_display_rating_chart_for_post post_id=”153″ size=”20″]
Optional parameters accepted in the shortcode:
* post_id (numeric): id of the post for which you want to display the widget. If the parameter is not specified, the plugin will use the active post.
* size (numeric): height in pixels of the horizontal bars used to represent the number of notes per note scale.
* class (text): css class that will be added to the widget to facilitate formatting customization
Overview of reviews management
Managing reviews consists of associating a rating with a comment. The reviews management uses WordPress commenting functionalities: therefore, comments must be activated for the types of post for which you want to activate reviews.
Thanks to the use of standard WP features, the settings you specify for comments will automatically apply to reviews (manual approval of comments, notification messages, automatic moderation, etc.). The settings that will not apply to review management are:
1. “Users must be registered and logged in to comment”: currently the plugin only accepts reviews for logged-in visitors. Regardless of your choice for this option, only logged-in visitors will be able to leave a review.
2. Enable threaded (nested) comments N levels deep: in the plugin, only administrators will be able to respond to a review via the WordPress admin screens. Visitors – logged in or not – will not be able to respond to a review.
To enable reviews, indicate “yes” in the plugin options (“Reviews management settings” section) then select the post types for which you want the review management features to be automatically implemented.
When you activate this management of reviews, the standard “Comments” area will be replaced by a plugin owned template (“post-reviews.php”) which is located in the “includes/template” directory of the plugin. You can also customize this template by copying it into a “prar-rating” directory in your theme.
This template displays the overall rating, the detailed rating chart, the list of reviews already published as well as a button allowing a visitor to leave a new review. This button is active if the visitor is logged in and has not already left a review on the post. The writing of the review by the visitor is done in a popin which combines the rating attribution and the comment left by the visitor. Via the options of the plugin, it is possible to determine if the note and/or the comment are mandatory to leave a review.
Reviews left by users will be visible in admin in the standard WordPress comments list as well as on the post editing page.
For Developers
Several hooks are available for developers as well as callable functions:
Actions
- prar_rating_before_save_note | called before saving rating to database | parameters: post_id, user_id, note, external_id
- prar_rating_after_save_note | called right after saving rating to database | parameters: post_id, user_id, note, external_id
- prar_rating_tpl_reviews_begin_header | called in the post-reviews.php template just before the section title | parameter: none
- prar_rating_tpl_reviews_before_add_review | called in the post-reviews.php template just before the “Add a review” button | parameter: none
- prar_rating_tpl_reviews_after_add_review | called in the post-reviews.php template just after the “Add a review” button | parameter: none
- prar_rating_tpl_reviews_end_header | called in the post-reviews.php template at the end of the header| parameter: none
- prar_rating_tpl_have_reviews_start | called in the post-reviews.php template just before the list of reviews (when there are reviews) | parameter: none
- prar_rating_tpl_have_reviews_end | called in the post-reviews.php template just after the list of reviews (when there are reviews) | parameter: none
- prar_rating_tpl_no_reviews_start | called in the post-reviews.php template just before the list of reviews (when there are no reviews for the post yet) | parameter: none
- prar_rating_tpl_no_reviews_end | called in the post-reviews.php template just before the list of reviews (when there are no reviews for the post yet) | parameter: none
Filters
- prar_rating_sc_set_note_atts | allows to override the parameters indicated during the call to the shortcode prar_set_rating_for_post | parameter: array atts
- prar_rating_text_save_user_note | allows to override the text displayed to the visitor when the rating is saved with the prar_set_rating_for_post shortcode. Default text is set in plugin options | parameters: initial text, note, post_id
- prar_rating_text_user_note | allows to override the text displayed to the visitor next to his rating in the prar_set_rating_for_post shortcode. Default text is set in plugin options | parameters: initial text, note, post_id
- prar_rating_html_block_user_note | allows to modify the html block which is after the rating in the prar_set_rating_for_post shortcode. | parameters: initial html block, note, post_id
- prar_rating_html_block_display_note | allows to modify the html block displayed after the widget in the shortcode prar_display_rating_for_post | parameters: initial html block, array with overall note information (number_of_notes, note, sum_notes)
Functions
- prar_rating_get_average_note_for_post | returns the overall rating for a post, user, external_id as an array (number_of_notes, note, sum_notes) | parameters: post_id, user_id, external_id
- prar_rating_get_average_note_for_user | returns the overall rating given by a user as an array (number_of_notes, rating, sum_notes) | parameter: user_id
- prar_rating_get_average_note_for_external_id | returns the overall rating for an external_id as an array (number_of_notes, rating, sum_notes) | parameter: external_id
- prar_rating_get_all_notes_for_user | returns an array with one line per rating assigned by a user (post, user_id, rating, external_id, date) | parameter: user_id
- prar_rating_get_all_notes_for_post | returns an array with one row per rating assigned for a post (post, user_id, rating, external_id, date) | parameter: post_id
- prar_rating_get_all_notes_for_external_id | returns an array with one row per rating assigned to an external_id (post, user_id, rating, external_id, date) | parameter: external_id
JavaScript
- trigger(‘prar_rating_saved’) – An ‘prar_rating_saved’ event is generated related to the DOM element that carries the widget. This allows you, if necessary, to trigger specific actions in your website when assigning a rating. N.B. this event is generated when the note is saved in a “prar_set_rating_for_post” widget. It is not generated as part of the management of reviews for which the note is recorded after validation of the complete form.
Special thanks
The development of this plugin was greatly facilitated by “RaterJS” javascript library developed by Fredrik Olsson. Many thanks also to (https://www.ericbourges.com “Eric”) for his valuable design advices and feature ideas.
Screenshots
Example of review management on a single post page
Shortcodes set and display note on a single post page
Settings page in admin
Ratings display in admin on post page
Admin rating integrated on comments lists
