Getting Started with Rating

Welcome to the Getting Started area for Rating!

It goes without saying that the intent of Rating is to allow your your users to submit ratings and reviews for your weblog entries. From there, you're going to want to be able to show those ratings/reviews, the current rating statistics for your entries, as well as display lists of entries in order by the highest rating averages. This tutorial will show you how to do all that, as well as get yourself set up in the CP area. Be sure to check out the full Documentation for Rating to see what else you can do.

Installation

To install Rating, follow these simple steps:

  1. Download Rating and unzip the files
  2. Open up the "modules" folder and upload all files in the "rating" folder to your "system/modules" directory
  3. Open up the "language/english" folder and upload the "lang.rating.php" into the appropriate sub-folder of your "system/language" directory
  4. Open up the "extensions" folder and upload all files into your site's "system/extensions" directory
  5. Open up the "themes" folder and upload the "rating_themes" folder into your site's "themes" directory
  6. Go to your "Modules" tab inside your EE control panel. Find the Rating module in the list and click "Install"
  7. That's it! If you encounter any issue, please visit our Support Forums

Configuration

Rating has various configuration and permission controls, including the option to create/modify custom Rating fields and email notification templates.

Creating & Modifying Custom Rating Fields

Similar to custom weblog fields, Rating has it's own set of custom Rating fields. To add, modify or remove and custom Rating fields, click on the Fields tab in the module CP area. By default, you'll see there is already 2 fields called "rating" and "review". These two fields usually suffice for most Rating setups, but if necessary, you can create your own Rating fields. To edit any of the existing fields, just click on the name. To create a new field, click the "Create a New Field" button at the top right corner of the page. Let's create a new field:

  1. In the "Field Name" field, type in "food_quality". This will be the short name used to call this field later on. Remember, lowercase, no special characters and no spaces
  2. In the "Field Label" field, type in "Food Quality". This is the full name of the field. It serves no real purpose other than to look prettier in your list of Fields
  3. In the "Field Type" field, select "Number". You can also make this a "review" type field by selecting "Text Area", or for simple data collection such as personal member info, using "Text Input". Our field will be a numerical field though, which will allow us to collect additional rating data
  4. In the "Field Format" field, select "None". There's a few other formatting options also available
  5. In the "Field Order" field, just leave whatever value is currently there
  6. In the "Field Length" field, change the value to "5". That will be more than sufficient to record numerical values
  7. Click the "Submit" button and the field will be saved

Email Notification Templates

Rating can be configured to send email notifications to Admins, weblog entry authors, and/or users who submit ratings each time a new rating is submitted. To add, modify or remove notification templates, click on the Templates tab in the module CP area. By default, you'll see there is already 1 template called "default_template". To create a new notification template, click the "Create New Template" button at the top right corner of the page. Let's create a new field:

  1. In the "Template Name" field, type in "admin_email". This will be the short name used to call this notification template later on. Remember, lowercase, no special characters and no spaces
  2. In the "Template Label" field, type in "Admin Email". This is the full name of the field. It serves no real purpose other than to look prettier in your list of notification templates
  3. In the "Email Subject" field, type in "New Rating Submitted!". This will be the subject line of the email notification
  4. In the "Word Wrap" field, just leave it at "No".
  5. In the "Email Message" field, enter in whatever you wish, including using any custom Rating fields you've created. Here's a sample:
    Hello Admin!

    Someone has just submitted a Rating!
    You can view it here: http://www.yoursite.com/path_to/ratings/{url_title}/

    {name} ({email})
    Submitted on: {entry_date}
    Food Quality: {food_quality}/5
    Service Quality: {service_quality}/5
    Review: {review}
  6. Click the "Submit" button and the notification template will be saved

Weblog Preferences

Rating contains its own series of preferences per weblog. You can access this area by clicking the "Weblog Preferences" tab in the module CP area. To edit preferences for any weblog, just click it in the list and edit as necessary.

Member Group Preferences

Rating contains its seperate preferences per member group as well. You can access this area by clicking the "Group Preferences" tab in the module CP area. To edit preferences for any member group, just click it in the list and edit as necessary.

Maintenance

It's possible that Rating might occasionally have some statistics out of wack. To refresh the system and have Rating recount it's statistics, use this tool. You can access this area by clicking the "Maintenance" tab in the module CP area.

Allowing your users to submit Ratings

You're obviously going to need to allow your users to submit ratings. The relevant question for you might be, do you want to allow only Members to submit ratings, or Guests as well? We'll show you both ways. You'll be using the Rating:Form function for this part of the tutorial.

Starting Up

Let's first create a new EE template group called "rating". Then, create a new template called "entries". This will replicate your typical Single Entry page that you would display a full weblog entry on. You can of course apply this code to any existing template, but we'll use this one for example purposes. In this template, insert the following code:

{exp:weblog:entries}
<h2>{title}</h2>
<p>{body}</p>
{/exp:weblog:entries}
 
<h4>Submit a Rating for this Entry:</h4>
{if logged_in}
{exp:rating:form form_name="Hotel Ratings" required="rating|review" return="rating/entries/{segment_3}"}
 
<p><label for="rating">Your Rating:</label>
<select name="rating" id="rating">
<option value="1">1</option>
<option value="2">2</option>
<option value="3">3</option>
<option value="4">4</option>
<option value="5">5</option>
</select></p>
<p><label for="review">Your Review:</label><br />
<textarea name="review" id="review" rows="10" cols="40"></textarea></p>
<p><input type="submit" name="submit" value="Submit!" /></p>
 
{/exp:rating:form}
{if:else}
<p>You must be logged in to submit a rating for this entry.</p>
{/if}

The above code will allow your logged in members to submit ratings/reviews for your weblog entries, and return an error for non-members or logged out members. Rating will automaticalyl detect the member submitting the form, so all profile data for that member will be available for output later on. When a member submits a rating/review, it will be logged by the Rating system, and will be posted to the site immediately.

Allow Guests to submit Ratings

If you wish to allow Guests to submit ratings as well, you'll need to make some modifications to the code above:

{exp:weblog:entries}
<h2>{title}</h2>
<p>{body}</p>
{/exp:weblog:entries}
 
<h4>Submit a Rating for this Entry:</h4>
{exp:rating:form form_name="Hotel Ratings" required="rating|review" require_membership="no" return="rating/entries/{segment_3}"}
 
{if logged_out}
<p><label for="name">Name:</label> <input type="text" name="name" id="name" value="{name}" /></p>
<p><label for="email">Email Address:</label> <input type="text" name="email" id="email" value="{email}" /></p>
<p><input type="checkbox" name="save_info" id="save_info" value="y" {save_info} /> <label for="save_info">Remember my contact info for next time?</label></p>
{/if}
 
<p><label for="rating">Your Rating:</label>
<select name="rating" id="rating">
<option value="1">1</option>
<option value="2">2</option>
<option value="3">3</option>
<option value="4">4</option>
<option value="5">5</option>
</select></p>
<p><label for="review">Your Review:</label><br />
<textarea name="review" id="review" rows="10" cols="40"></textarea></p>
<p><input type="submit" name="submit" value="Submit!" /></p>
 
{/exp:rating:form}

You'll notice that we added some additional code to handle recording of names and email addresses of Guests (but we've hidden it so your members don't have to see it), and a parameter that turns on Guest rating as well.

Using your Notification templates and Custom Rating fields

And lastly, we created a new custom field and email notification template earlier. Here is how you would call those into your template:

{exp:weblog:entries}
<h2>{title}</h2>
<p>{body}</p>
{/exp:weblog:entries}
 
<h4>Submit a Rating for this Entry:</h4>
{exp:rating:form form_name="Hotel Ratings" required="rating|review" require_membership="no" return="rating/entries/{segment_3}" notify="fat_tony@solspace.com" admin_template="admin_email"}
 
{if logged_out}
<p><label for="name">Name:</label> <input type="text" name="name" id="name" value="{name}" /></p>
<p><label for="email">Email Address:</label> <input type="text" name="email" id="email" value="{email}" /></p>
<p><input type="checkbox" name="save_info" id="save_info" value="y" {save_info} /> <label for="save_info">Remember my contact info for next time?</label></p>
{/if}
 
<p><label for="rating">Rating for Service Quality:</label>
<select name="rating" id="rating">
<option value="1">1</option>
<option value="2">2</option>
<option value="3">3</option>
<option value="4">4</option>
<option value="5">5</option>
</select></p>
<p><label for="food_quality">Rating for Food Quality:</label>
<select name="food_quality" id="food_quality">
<option value="1">1</option>
<option value="2">2</option>
<option value="3">3</option>
<option value="4">4</option>
<option value="5">5</option>
</select></p>
<p><label for="review">Your Review:</label><br />
<textarea name="review" id="review" rows="10" cols="40"></textarea></p>
<p><input type="submit" name="submit" value="Submit!" /></p>
 
{/exp:rating:form}

Displaying Stats

To display some Rating statistics for each of your weblog entries, you'll need to use the Rating:Stats function. Using the same "entries" template as noted above, we're going to add just a little more code to it:

<h4>Stats for this Entry</h4>
{exp:rating:stats entry_id="{entry_id}"}
<p>Rated: {stars_overall_avg} ({overall_avg}/5), based on {overall_count} review{if overall_count !="1"}s{/if}</p>
{/exp:rating:stats}

So, if we insert that code into the template code noted earlier, it would look like this:

{exp:weblog:entries}
<h2>{title}</h2>
<p>{body}</p>
 
<h4>Stats for this Entry</h4>
{exp:rating:stats form_name="Hotel Ratings" entry_id="{entry_id}"}
<p>Rated: {stars_overall_avg} ({overall_avg}/5), based on {overall_count} review{if overall_count !="1"}s{/if}</p>
{/exp:rating:stats}
 
{/exp:weblog:entries}
 
<h4>Submit a Rating for this Entry:</h4>
{exp:rating:form form_name="Hotel Ratings" required="rating|review" require_membership="no" return="rating/entries/{segment_3}"}
 
{if logged_out}
<p><label for="name">Name:</label> <input type="text" name="name" id="name" value="{name}" /></p>
<p><label for="email">Email Address:</label> <input type="text" name="email" id="email" value="{email}" /></p>
<p><input type="checkbox" name="save_info" id="save_info" value="y" {save_info} /> <label for="save_info">Remember my contact info for next time?</label></p>
{/if}
 
<p><label for="rating">Your Rating:</label>
<select name="rating" id="rating">
<option value="1">1</option>
<option value="2">2</option>
<option value="3">3</option>
<option value="4">4</option>
<option value="5">5</option>
</select></p>
<p><label for="review">Your Review:</label><br />
<textarea name="review" id="review" rows="10" cols="40"></textarea></p>
<p><input type="submit" name="submit" value="Submit!" /></p>
 
{/exp:rating:form}

Showing All Submitted Ratings

You're almost there! All that's left now is to show the ratings that were submitted. You'll need to use the Rating:Entries function. Using the same "entries" template, we're going to add just a little more code to it:

<h4>Ratings for this Entry:</h4>
{exp:rating:entries form_name="Hotel Ratings" paginate="both" limit="10"}
 
<div class="rating">
{if screen_name} <p><a href="{path=user/profile}{member_id}/">{screen_name}</a><br />
{if avatar}<img src="{avatar_url}" width="{avatar_width}" height="{avatar_height}" />{/if}</p>
{if:else}
<p>{name} (Guest)</p>
{/if}
<p>{stars}{rating}{/stars}</p>
<p>Submitted on {rating_date format="%F %n, %Y at %g:%i %a"}</p>
<p>{review}</p>
</div>
 
{paginate}
<p class="paginate">Page {current_page} of {total_pages} pages {pagination_links}</p>
{/paginate}
 
{/exp:rating:entries}

So, your FINAL code for that template would look like this:

{exp:weblog:entries}
<h2>{title}</h2>
<p>{body}</p>
 
<h4>Stats for this Entry</h4>
{exp:rating:stats form_name="Hotel Ratings" entry_id="{entry_id}"}
<p>Rated: {stars_overall_avg} ({overall_avg}/5), based on {overall_count} review{if overall_count !="1"}s{/if}</p>
{/exp:rating:stats}
 
{/exp:weblog:entries}
 
<h4>Submit a Rating for this Entry:</h4>
{exp:rating:form form_name="Hotel Ratings" required="rating|review" require_membership="no" return="rating/entries/{segment_3}"}
 
{if logged_out}
<p><label for="name">Name:</label> <input type="text" name="name" id="name" value="{name}" /></p>
<p><label for="email">Email Address:</label> <input type="text" name="email" id="email" value="{email}" /></p>
<p><input type="checkbox" name="save_info" id="save_info" value="y" {save_info} /> <label for="save_info">Remember my contact info for next time?</label></p>
{/if}
 
<p><label for="rating">Your Rating:</label>
<select name="rating" id="rating">
<option value="1">1</option>
<option value="2">2</option>
<option value="3">3</option>
<option value="4">4</option>
<option value="5">5</option>
</select></p>
<p><label for="review">Your Review:</label><br />
<textarea name="review" id="review" rows="10" cols="40"></textarea></p>
<p><input type="submit" name="submit" value="Submit!" /></p>
 
{/exp:rating:form}
 
<h4>Ratings for this Entry:</h4>
{exp:rating:entries form_name="Hotel Ratings" paginate="both" limit="10"}
 
<div class="rating">
{if screen_name} <p><a href="{path=user/profile}{member_id}/">{screen_name}</a><br />
{if avatar}<img src="{avatar_url}" width="{avatar_width}" height="{avatar_height}" />{/if}</p>
{if:else}
<p>{name} (Guest)</p>
{/if}
<p>{stars}{rating}{/stars}</p>
<p>Submitted on {rating_date format="%F %n, %Y at %g:%i %a"}</p>
<p>{review}</p>
</div>
 
{paginate}
<p class="paginate">Page {current_page} of {total_pages} pages {pagination_links}</p>
{/paginate}
 
{/exp:rating:entries}

That's it! Your page is now set up to record and display Ratings!

Ordering your Entries by Highest Rating

There's a good chance you're going to want to display a list of your top rated weblog entries. This is where the Rating:Rankings function comes in. You can order your entries by any Rating field. The most common method is by "rating", so that's what we'll use in this example.

First, create a new template in your "rating" template group called "rank". Then, insert the following code to display a list of the Top Ten weblog entries, with the assistance of the Rating:Stats loop to output the scores for each entry:

<h3>Top 10 Rated Entries</h3>
 
<ul>
{exp:rating:rankings limit="10"}
<li>{exp:rating:stats entry_id="{entry_id}" precision="1"}{stars_avg_rating} ({avg_rating}/){/exp:rating:stats} <a href="{title_permalink="rating/entries"}">{title}</a></li>
{/exp:rating:rankings}
<ul>

And remember, there's a lot more you can do with Rating. Whether you want to tweak some of the above examples, or add a feature not mentioned here, make sure you check out the full Documentation for Rating.