WP Review Site Plugin Documentation

Installation Guides
Plugin Function Reference

Installation Guide

Installing WP Review Site is easy and should take just a few minutes:

Uploading and Activating WP Review Site
1. Open and extract wpreviewsite.zip somewhere on your computer.
2. Browse into the "plugins" folder.
3. Copy the entire "review-site" folder to your blog installation (locally or via FTP). Relative to the root of your blog, the new folder location should be "/wp-content/plugins/review-site".
4. Browse into the "themes" folder.
5. Copy the theme folders to your blog installation (locally or via FTP). Relative to the root of your blog, the new folder location should be "/wp-content/themes/theme-name".
6. Browse to your WordPress administration panel (http://www.example.com/wp-admin).
7. Click the "Plugins" link in the left menu.
8. In the list of plugins, find "WP Review Site" and click the "Activate" link below it.
9. To use one of the included themes (easiest way to start), click the "Appearance" link in the left menu, click on the theme name and click the "Activate" link in the window that pops up..

Changing Settings
To start, you will want to choose your general options and add the rating dimensions you want people to use when leaving a review. WP Review Site adds a new category to your left menu called "Review Site" under which all its settings can be found.
1. First, choose "General Settings" under the "Review Site" menu in the left of your wp-admin area.
2. Choose how you want your WordPress posts sorted (default, which is chronological, by rating, or by number of reviews).
3. If you are NOT using one of the themes that came with WP Review Site, then fill out the rest of the form to add ratings to your custom theme. The plugin will automatically add the ratings your users have left to the top or bottom of posts, pages and comments depending on your settings on this page. Note that until you add some rating categories to your posts, you won't see anything added to the posts.
Now configure the rating categories, which are the dimensions you want people to rate when leaving a review, such as "price", "value" or "quality of support".
1. Choose "Rating Categories" under the "Review Site" menu in the left of your wp-admin area.
2. Use the empty box next to "Add a Category" to type a new rating category, and submit the form with the save button. Do this as many times as you need to add all the rating categories you want.
3. You can specify different rating categories for different parts of your site. Add them all using the top form, then use the bottom form.
4. Check off only the rating categories you want posts in a specific post category to use, choose the category from the dropdown box, and submit the form to apply.
You can optionally add a Comparison Table to the home page or category pages of your site.
1. Choose "Comparison Table" under the "Review Site" menu in the left of your wp-admin area.
2. Fill in the form and check off the boxes specifying where you want to display the table, and what it should display. The custom fields refer to the "Custom Fields" box on the Write/Edit Post or Page screens. You can use this to add custom data to a post, such as a price, then use this form to display it in the comparison table.
3. For more control over where the comparison table appears, manually add the comparison table code to your theme by referring to the examples in the API Reference section further down this page.
You can optionally add Google Maps to your posts.
1. Check off the box and fill in your Google Maps API Key to turn on this feature.
2. On the Write/Edit Post or Page screens, add a Custom Field in the Custom Fields box called "mapaddress" with the address. WP Review Site will automatically add a Google Map to that post or page displaying the address you have entered.
How to Use Your Own Theme
You have two options when using your own theme, instead of one of the ones that comes with WP Review Site. By checking off the boxes on the General Settings page of the plugin settings, WP Review Site will add the ratings displays and inputs to your theme automatically. However, you might want more control over the placement and appearance than this provides.

You can manually add WP Review Site features to your theme by using the many Theme Functions it makes available, which are documented below. To do so, open the relevant template file in your theme directory and paste the example code from the reference below.

Important files that are usually relevant to this: index.php (home page), single.php (single post), page.php (pages), and comments.php (comments list and form).

If you have any questions on how to do something, feel free to contact us for help.

Plugin Function Reference

Important note: Many of these functions will not display anything if you use them on a post or page where you have not set any rating categories to display.

ratings_table($custom_id = null)
Outputs a table with average ratings for the current post. This function can be called within The Loop with no arguments, or outside The Loop by specifying the ID of the post to display ratings for.
Usage Example:

<?php if (function_exists('ratings_table')) ratings_table(); ?>
Output Example:

<table class="ratings"> <tr><td class="rating_label">Price</td><td class="rating_value"><img src="/wp-content/plugins/review-site/star.gif" />...</td></tr> <tr><td class="rating_label">Support</td><td class="rating_value"><img src="/wp-content/plugins/review-site/star.gif" />...</td></tr> <tr><td class="rating_label">Reliability</td><td class="rating_value"><img src="/wp-content/plugins/review-site/star.gif" />...</td></tr> </table>

ratings_list($custom_id = null)

Outputs an unordered list with average ratings for the current post. This function can be called within The Loop with no arguments, or outside The Loop by specifying the ID of the post to display ratings for.

Usage Example:

<?php if (function_exists('ratings_list')) ratings_list(); ?>

Output Example:

<ul class="ratings">
		    <li><label class="rating_label">Price</label> <span class="rating_value"><img src="/wp-content/plugins/review-site/star.gif" />...</span></li>
		    <li><label class="rating_label">Support</label> <span class="rating_value"><img src="/wp-content/plugins/review-site/star.gif" />...</span></li>
		    <li><label class="rating_label">Reliability</label> <span class="rating_value"><img src="/wp-content/plugins/review-site/star.gif" />...</span></li>
		</ul>

get_ratings($custom_id = null)
Returns an array with average ratings for the current post. This function can be called within The Loop with no arguments, or outside The Loop by specifying the ID of the post to display ratings for. Since the array contains numeric values for each dimension posts or pages are rated on, you may use num_to_stars() to convert this number to star graphics.
Usage Example:
```
<?php if (function_exists('get_ratings')) $ratings = get_ratings(); ?>
```
Output Example:
This function has no output. The array returned has the following format:
```
array(
		    [Price] => 3.5,
		    [Support] => 2.5,
		    [Reliability] => 3.2
		)
```
positive_reviews($custom_id = null)
Displays the number of unique reviews of the current post with an average rating of 3 stars or higher.
Usage Example:
```
<?php if (function_exists('positive_reviews')) echo positive_reviews(); ?> Positive Reviews
```
Output Example:
```
8 Positive Reviews
```
negative_reviews($custom_id = null)
Displays the number of unique reviews of the current post with an average rating of less than 3 stars.
Usage Example:
```
<?php if (function_exists('negative_reviews')) echo negative_reviews(); ?> Negative Reviews
```
Output Example:
```
2 Negative Reviews
```
get_positive_negative_count($custom_id = null)
Returns an array with the number of positive (3 star or higher) and negative reviews received by the current post.
Usage Example:
```
<?php if (function_exists('get_positive_negative_count')) $counts = get_positive_negative_count(); ?>
```
Output Example:
This function has no output. The array returned has the following format:
```
array(
		    [positive] => 8,
		    [negative] => 2
		)
```

comment_ratings_table($custom_id = null)

Outputs a table with ratings submitted with the specified comment. This function can be called within the comments loop in comments.php with no arguments, or outside the loop by specifying the ID of the comment to display ratings for. If used within a comment display loop, it expects the current comment to be called $comment.

Usage Example:

<?php if (function_exists('comment_ratings_table')) comment_ratings_table(); ?>

Output Example:

<table class="ratings">
		    <tr><td class="rating_label">Price</td><td class="rating_value"><img src="/wp-content/plugins/review-site/star.gif" />...</td></tr>
		    <tr><td class="rating_label">Support</td><td class="rating_value"><img src="/wp-content/plugins/review-site/star.gif" />...</td></tr>
		    <tr><td class="rating_label">Reliability</td><td class="rating_value"><img src="/wp-content/plugins/review-site/star.gif" />...</td></tr>
		</table>

comment_ratings_list($custom_id = null)

Outputs an unordered list with ratings submitted with the specified comment. This function can be called within the comments loop in comments.php with no arguments, or outside the loop by specifying the ID of the comment to display ratings for. If used within a comment display loop, it expects the current comment to be called $comment.

Usage Example:

<?php if (function_exists('comment_ratings_list')) comment_ratings_list(); ?>

Output Example:

<ul class="ratings">
		    <li><label class="rating_label">Price</label> <span class="rating_value"><img src="/wp-content/plugins/review-site/star.gif" />...</span></li>
		    <li><label class="rating_label">Support</label> <span class="rating_value"><img src="/wp-content/plugins/review-site/star.gif" />...</span></li>
		    <li><label class="rating_label">Reliability</label> <span class="rating_value"><img src="/wp-content/plugins/review-site/star.gif" />...</span></li>
		</ul>

ratings_input_table($custom_id = null)

Outputs a table which collects ratings within the comment form of a post or page. Includes HTML which displays a table containing the dimensions you want to collect ratings for (ex: "value", "support", "reliability") as well as JavaScript star rating widgets that allow ratings to be set by clicking on star images. Must be used between the <form> and </form> tags in comments.php for ratings to be submitted along with the comment.

Usage Example:

<?php if (function_exists('ratings_input_table')) ratings_input_table(); ?>

Output Example:

<table class="ratings">
		<tr>
			<td class="rating_label">Features</td>
			<td class="rating_value">
				<a onclick="rateIt(this, 0)" id="0_1" title="1" onmouseover="rating(this, 0)" onmouseout="rolloff(this, 0)"></a>
				<a onclick="rateIt(this, 0)" id="0_2" title="2" onmouseover="rating(this, 0)" onmouseout="rolloff(this, 0)"></a>
				<a onclick="rateIt(this, 0)" id="0_3" title="3" onmouseover="rating(this, 0)" onmouseout="rolloff(this, 0)"></a>
				<a onclick="rateIt(this, 0)" id="0_4" title="4" onmouseover="rating(this, 0)" onmouseout="rolloff(this, 0)"></a>
				<a onclick="rateIt(this, 0)" id="0_5" title="5" onmouseover="rating(this, 0)" onmouseout="rolloff(this, 0)"></a>
				<input type="hidden" id="0_rating" name="0_rating" value="0" />
			</td>
		</tr>
		<tr>
			<td class="rating_label">Support</td>
			<td class="rating_value">
				<a onclick="rateIt(this, 1)" id="1_1" title="1" onmouseover="rating(this, 1)" onmouseout="rolloff(this, 1)"></a>
				<a onclick="rateIt(this, 1)" id="1_2" title="2" onmouseover="rating(this, 1)" onmouseout="rolloff(this, 1)"></a>
				<a onclick="rateIt(this, 1)" id="1_3" title="3" onmouseover="rating(this, 1)" onmouseout="rolloff(this, 1)"></a>
				<a onclick="rateIt(this, 1)" id="1_4" title="4" onmouseover="rating(this, 1)" onmouseout="rolloff(this, 1)"></a>
				<a onclick="rateIt(this, 1)" id="1_5" title="5" onmouseover="rating(this, 1)" onmouseout="rolloff(this, 1)"></a>
				<input type="hidden" id="1_rating" name="1_rating" value="0" />
			</td>
		</tr>
		</table>

ratings_input_list($custom_id = null)

Outputs an unordered list which collects ratings within the comment form of a post or page. Includes HTML which displays a list containing the dimensions you want to collect ratings for (ex: "value", "support", "reliability") as well as JavaScript star rating widgets that allow ratings to be set by clicking on star images. Must be used between the <form> and </form> tags in comments.php for ratings to be submitted along with the comment.

Usage Example:

<?php if (function_exists('ratings_input_list')) ratings_input_list(); ?>

Output Example:

<ul class="ratings">
		<li>
			<label class="rating_label" style="float: left">Features</label>
			<div class="rating_value">
				<a onclick="rateIt(this, 0)" id="0_1" title="1" onmouseover="rating(this, 0)" onmouseout="rolloff(this, 0)"></a>
				<a onclick="rateIt(this, 0)" id="0_2" title="2" onmouseover="rating(this, 0)" onmouseout="rolloff(this, 0)"></a>
				<a onclick="rateIt(this, 0)" id="0_3" title="3" onmouseover="rating(this, 0)" onmouseout="rolloff(this, 0)"></a>
				<a onclick="rateIt(this, 0)" id="0_4" title="4" onmouseover="rating(this, 0)" onmouseout="rolloff(this, 0)"></a>
				<a onclick="rateIt(this, 0)" id="0_5" title="5" onmouseover="rating(this, 0)" onmouseout="rolloff(this, 0)"></a>
				<input type="hidden" id="0_rating" name="0_rating" value="0" />
			</div>
		</li>
		<li>
			<label class="rating_label" style="float: left">Support</label>
			<div class="rating_value">
				<a onclick="rateIt(this, 1)" id="1_1" title="1" onmouseover="rating(this, 1)" onmouseout="rolloff(this, 1)"></a>
				<a onclick="rateIt(this, 1)" id="1_2" title="2" onmouseover="rating(this, 1)" onmouseout="rolloff(this, 1)"></a>
				<a onclick="rateIt(this, 1)" id="1_3" title="3" onmouseover="rating(this, 1)" onmouseout="rolloff(this, 1)"></a>
				<a onclick="rateIt(this, 1)" id="1_4" title="4" onmouseover="rating(this, 1)" onmouseout="rolloff(this, 1)"></a>
				<a onclick="rateIt(this, 1)" id="1_5" title="5" onmouseover="rating(this, 1)" onmouseout="rolloff(this, 1)"></a>
				<input type="hidden" id="1_rating" name="1_rating" value="0" />
			</div>
		</li>
		</ul>

num_to_stars($num)

Returns an HTML fragment containing star images depicting a numeric rating between 0 and 5. Values are rounded down to the nearest half star.

Usage Example:

<?php echo num_to_stars(3.8); ?>

Output Example:

<img src="/wp-content/plugins/review-site/star.gif" alt="3.8" />
		<img src="/wp-content/plugins/review-site/star.gif" alt="3.8" />
		<img src="/wp-content/plugins/review-site/star.gif" alt="3.8" />
		<img src="/wp-content/plugins/review-site/star-half.gif" alt="3.8" />
		<img src="/wp-content/plugins/review-site/star-empty.gif" alt="3.8" />

visit_site_link($text)
Displays a link to the URL saved on the post or page edit screen for the current post or page. Specify the link text with the first parameter, or "Visit This Site" will be printed by default.
Usage Example:
```
<?php visit_site_link('Visit This Web Host'); ?>
```
Output Example:
```
<a href="http://www.example.com/affiliate/?affid=12345">Visit This Web Host</a>
```
rs_comparison_table($count, $link_text, $category)
Displays a comparison table listing the top $count rated posts. Omit the category parameter to list posts from all categories, otherwise provide a comma separated list. You must configure the list of columns to display from the WP Review Site Settings page in your WP Admin area or the comparison table will only contain "Rank", "Name", "Rating" and "More Info" columns.
Usage Example:
```
<?php rs_comparison_table(5, 'Visit Web Host'); ?>
```