Rating Documentation

Tag Parameters

collection

string

Rating allows you to dynamically sort ratings into groups at submission. This is done by specifying the collection parameter on your Rating:Form tag. To filter rating stats by one of those groups, just specify the collection parameter and a value for your Rating:Stats tag.

{exp:rating:stats collection="Shark Reviews"}

entry_id

integer

This parameter allows you to hardcode an entry ID, or pass the entry ID dynamically from the Channel:Entries loop or through the URI or an embed.

{exp:rating:stats entry_id="{entry_id}"}

fractions

string

This parameter allows you to specify which character to indicate fractions in numeric ratings. By default, the value is a decimal (.).

{exp:rating:stats fractions="."}

precision

integer

This parameter allows you to specify the number of decimals to round fractions on numerical rating fields for averages. For example, a value of 1 would give you a result like this for a rating value: 4.5. Default is 0.

Default: 0

{exp:rating:stats precision="2"}

scale

integer

By default, Rating assumes your rating scale is 5. As in, your numerical ratings are out of 5 (ex: 1 out of 5 stars, 2 out of 5 stars, etc). You can however, change the scale to be out of 10 by specifying the scale parameter. When you specify this, the stars_overall_avg and stars_avg_FIELD_NAME variables will switch from the default of 5 graphic images to 10 when placed around your numerical rating value.

{exp:rating:stats scale="5"}

stars_image_path

string

This parameter allows you to specify an alternate Rating star image theme. This controls the images displayed when using the stars variable pair. Specify the public path to your rating image assets folder (that contains star-0, star-25 etc). By default, it loads the Rating images located at ./themes/user/rating/default/images. Used in conjunction with the stars_filetype, stars_height and stars_width parameters.

{exp:rating:stats stars_image_path="assets/images/rating"}

stars_filetype

This parameter allows you to override the default file extension of the images produced for the "star" value of the rating. Just specify a value of png (default), jpg or gif. Used in conjunction with the stars_image_path, stars_height and stars_width parameters.

{exp:rating:stats stars_filetype="png"}

stars_height

integer

This parameter allows you to override the default height of the images produced for the "star" value of the rating. Just specify a numeric value (in pixels). Default is 25 pixels. Used in conjunction with the stars_image_path, stars_filetype and stars_width parameters.

Default: 25

{exp:rating:stats stars_height="40"}

stars_width

integer

This parameter allows you to override the default width of the images produced for the "star" value of the rating. Just specify a numeric value (in pixels). Default is 25 pixels. Used in conjunction with the stars_image_path, stars_filetype and stars_height parameters.

Default: 25

{exp:rating:stats stars_width="40"}

status

This parameter allows you to filter ratings by their status. By default, it will only show ratings that are open. To specify multiple statuses, use the pipe (|) chracter. The closed status for ratings is a special/reserved status. For performance reasons, rating submissions with a status of closed will not run the Stats update routine (and therefore Rating:Stats will not include those ratings in the stats data until they are switched to a different status).

{exp:rating:stats status="open|Pending|Custom"}

thousands

This parameter allows you to specify which character to use to separate groups of thousands in numeric rating fields. For example, a value of , (comma) would parse 10000 as 10,000. Default is , (comma).

{exp:rating:stats thousands=","}

Variables

overall_avg

This variable outputs the overall average rating value for ALL numeric rating fields. So if you have 3 numerical rating fields, it will combine all of them together for one overall average rating. For example, if rating_field_1 has an average rating of 3, and rating_field_2 has an average rating of 4, the overall average rating value would be 3.5.

{overall_avg}

overall_count

This variable outputs the total amount of ratings submitted with a value for any numerical rating field for a given entry.

{overall_count}

overall_sum

This variable outputs the total cumulative value/score of all numerical rating fields from ratings submitted for a given entry. For example, if Joe submitted a rating of 3, and Tom submitted a rating of 5, the overall sum would be 8.

{overall_sum}

avg_FIELD_NAME

This variable outputs the average value for the given numeric rating field. To construct this variable, simply use avg_ + FIELD_NAME.

{avg_FIELD_NAME}

count_FIELD_NAME

This variable outputs the total amount of ratings submitted with a value for the given numeric rating field for a given entry. To construct this variable, simply use count_ + FIELD_NAME.

{count_FIELD_NAME}

sum_FIELD_NAME

This variable outputs the total cumulative value/score for the given numeric rating field from ratings submitted for a given entry. For example, if Joe submitted a rating of 3, and Tom submitted a rating of 5, the sum would be 8. To construct this variable, simply use sum_ + FIELD_NAME.

{sum_FIELD_NAME}

stars_overall_avg

This variable outputs "star" images to construct a graphical representation of the overall average rating value for all numeric rating fields. So if you have 3 numerical rating fields, it will combine all of them together for one overall average rating, but parse it as "star" images.

{stars_overall_avg}

stars_avg_FIELD_NAME

This variable outputs "star" images to construct a graphical representation for a given numerical rating field from ratings submitted for a given entry. So if you have 3 numerical rating fields, it will combine all of them together for one average rating, but parse it as "star" images. To construct this variable, simply use starsavg + FIELD_NAME.

{stars_avg_FIELD_NAME}

Tag Parameters

rating_id

required

{exp:rating:reporting_allowed rating_id="3"}

Tag Parameters

rating_id

required

This parameter tells the Rating module which rating/review will receive the report vote. This is a required parameter.

{exp:rating:report rating_id="7"}

Variables

message

This variable will output the appropriate message generated by the Rating module depending on the outcome of the report action.

{message}

Tag Parameters

duplicate_check_guest_ip

yes/no

This parameter allows you disable IP checking on Guest voting submissions. By default, Rating will check for a matching IP address and a cookie. Setting this parameter to no will set Rating to ONLY look for a cookie with a Guest user. While this isn't a complete solution, it solves the issue where multiple users have a shared IP address.

accepts: "y","n"

{exp:rating:rating_vote_stats duplicate_check_guest_ip="no"}

rating_id

string

This parameter tells the function which rating to pull vote statistics for.

{exp:rating:rating_vote_stats rating_id="{rating_id}"}

Variables

down_votes

integer

This variable will display the total number of down votes for the given rating/review.

{down_votes}

down_percent

This variable will display the percent of down votes for the given rating/review.

{down_percent}

up_votes

This variable will display the total number of up votes for the given rating/review.

{up_votes}

up_percent

This variable will display the percent of up votes for the given rating/review.

{up_percent}

{}

total_votes

This variable will display the total number of votes for the given rating/review.

{total_votes}

previous_vote

This variable will display the vote the currently logged in user gave for a specific rating/review. Will parse as up, down or an empty string if no previous vote was made by the user.

{previous_vote}

rating_comments

When using the Rating:Comments feature, this variable will display the total number of comments submitted to the rating entry.

{rating_comments}

Tag Parameters

example tag

example

Here is an example of using the tag with the stats to show how many stars entries got and ranks them based on the paramaters rank tag has below.

{exp:rating:rank
    orderby="bayesian:rating"
    limit="10"
    display_unrated="yes"
    sort="asc"
}
    <li>
        {exp:rating:stats
            entry_id="{entry_id}"
            precision="1"
        }
            {stars_avg_rating} ({avg_rating}/5)

			The averate rating for this entry is : {stars_overall_avg}

			The number of ratings given for this is : {overall_count}
            
        {/exp:rating:stats}
        <a href="{url_title_path='blog/entry'}/">{title}</a>
    </li>
{/exp:rating:rank}

bayesian_average_score

double

Used in conjunction with the orderby parameter when set to Bayesian weighting method mode. This parameter allows you manipulate the overall site average rating value that is calculated by Rating. It's very possible that your site average rating value could be above or below what you might consider a "middle" value of 2.5. You can override this part of the Bayesian calculation and specify any value you wish. For example, if you felt that the middle value should be 2.5, simply enter that value in the parameter. If you wanted EVERY value of your Rating scale to be positive (as opposed to 2.5 and up being positive, and 2.5 and below being negative), you could specify a value of 0.

{exp:rating:rank bayesian_average_score="2.5"}

category

integer

This parameter allows you filter your list of channel entries by the specified categories. Separate multiples with pipe character.

{exp:rating:rank category="1|4"}

collection

string

Rating allows you to dynamically sort ratings into groups at submission. This is done by specifying the collection parameter on your Rating:Form. To filter ratings by one of those groups, just specify this parameter for your Rating:Rank loop.

{exp:rating:rank collection="Shark Reviews"}

display_unrated

yes/no

This parameter allows you to have entries that have not yet been rated, included in the results. These unrated entries will have no rank value and if ordered by any Rating field or overall, will display AFTER entries that have been rated.

accepts: "y","n"

{exp:rating:rank display_unrated="yes"}

fractions

string

This parameter allows you to specify which character to use to indicate fractions in numeric ratings. The default is a period (.)

{exp:rating:rank fractions="."}

limit

integer

This parameter controls how many results will be outputted. The limit will default to 100 entries if a value is not specified.

Default: 100

{exp:rating:rank limit="20"}

orderby

string

This parameter sets the display order of the entries. You can use all numeric rating field names or overall for this parameter. Additionally, you can use Bayesian (weighted) method of ranking your entries. It makes some calculations on your site and weights the entries a little differently. For example, an entry with an average rating of 4.6/5 from 30 rating submissions would likely be ranked higher than that of an entry with average rating of 5/5 from 3 rating submissions. You can also use all numeric rating field names or overall for this parameter with Bayesian (weighted) method. The Bayesian method looks at ALL ratings in the results, determines the average for ALL ratings, and sets that as the middle point. To manipulate this average value, see the bayesian_average_score parameter. Any averages above that is considered a positive rating, and anything below it is considered a negative rating. So if the overall average rating value for your results in 2.73/5, an entry with an average rating of 4.7/5 from 3 rating submissions would be ranked higher than that of an entry with average rating of 5/5 from 1 rating submission. And an entry with an average rating of 1.5/5 from 2 rating submissions would be ranked lower than that of an entry with an average rating of 1/5 from 1 rating submission.

{exp:rating:rank orderby="bayesian:YOUR_RATING_FIELD"}

precision

integer

This parameter allows you to specify to the number of decimals to round fractions for averages and totals on stats of numeric ratings. The default is 0.

{exp:rating:rank precision="2"}

rating_status

string

This parameter allows you to filter ratings by their status. By default, it will only show ratings that are open. To specify multiple statuses, use the pipe (|) chracter.

{exp:rating:rank rating_status="open|Pending|Custom"}

sort

The sort order can be ascending or descending. The order will default to descending (desc) if nothing is specified.

{exp:rating:rank sort="asc"}

thousands

This parameter allows you to specify the character to use to separate groups of thousands in numerical rating fields. The default is a comma (,).

{exp:rating:rank thousands=","}

Variables

rating_timeframe_count

The number of ratings the entry has

{rating_timeframe_count}

rating_timeframe_avg

The averate rating the entry has

{rating_timeframe_avg}

rating_timeframe_sum

The sum of all stars the entry has been given

{rating_timeframe_sum}

Tag Parameters

allow_duplicates

yes/no

This parameter is available to prevent users from submitting duplicate votes for reviews.

accepts: "y","n"

{exp:rating:insert_rating_vote allow_duplicates="no"}

duplicate_check_guest_ip

This parameter allows you disable IP checking on Guest voting submissions. By default, Rating will check for a matching IP address and a cookie. Setting this parameter to no will set Rating to ONLY look for a cookie with a Guest user. While this isn't a complete solution, it solves the issue where multiple users have a shared IP address.

{exp:rating:insert_rating_vote duplicate_check_guest_ip="no"}

rating_id

This parameter tells the function which rating to count the vote for.

{exp:rating:insert_rating_vote rating_id="{rating_id}"}

Variables

message

This variable will display a success or failure message for the vote.

{message}

Tag Parameters

admin_template

This parameter is for specifying the admin notification template to be used for sending a notification email to an Admin. Used in conjunction with the notify parameter.

{exp:rating:form admin_template="some_template"}

allow_duplicates

yes/no

This parameter controls whether or not the Rating form will accept more than 1 submission from the same user for a single entry. The default is yes.

accepts: "y","n"

Default: y

{exp:rating:form allow_duplicates="no"}

allow_unrated

string

This parameter allows the submission of ratings without a rating value and without assigning a value of zero (0) to the specified rating fields, which can affect Rating statistics. Used to differentiate ratings with a value of 0 and unrated/unused rating fields. To specify multiple rating fields, use the pipe character.

{exp:rating:form allow_unrated="rating"}

anonymous

yes/no

This parameter controls whether or not the Rating form will accept submissions from Guests without the name and email fields filled in.

accepts: "y","n"

{exp:rating:form anonymous="no"}

collection

This parameter is used by Rating to dynamically sort ratings into groups at submission. The organization happens dynamically when you view your entries in the control panel, and when specifying this parameter on other Rating loops, it allows you to filter down your ratings to those only contained by the specified group name.

{exp:rating:form collection="Hotel Reviews"}

duplicate_check_guest_ip

This parameter allows you disable IP checking on Guest rating submissions. By default, Rating will check for a matching IP address and a cookie. Setting this parameter to no will set Rating to only look for a cookie with a Guest user. While this isn't a complete solution, it solves the issue where multiple users have a shared IP address.

{exp:rating:form duplicate_check_guest_ip="no"}

entry_id

required

This parameter is required to display the Rating form. You can hardcode an entry ID, or pass the entry ID dynamically from the Channel:Entries loop or through the URI or an embed.

{exp:rating:form entry_id="{entry_id}"}

edit

yes/no

This parameter allows you to use your Rating form in edit mode. With this enabled, Super Admins and authors can edit their rating submissions. Simply add this parameter in conjunction with the rating_id parameter and users will be able to edit the ratings they submitted.

accepts: "y","n"

{exp:rating:form edit="yes"}

form:attribute

string

This parameter allows you to control any form attribute for the form in your template. Simply replace attribute with an attribute name such as id, name, class, etc, and specify a value for that attribute. You can specify this parameter multiple times to control as many attributes as necessary. This would normally be done to control your form with Javascript or style it with CSS.

{exp:rating:form form:class="your_class_name"}

notify

This parameter sends notification emails to the email address(es) specified when new ratings are submitted. Used in conjunction with the admin_template parameter. Separate multiple email addresses with the pipe character.

{exp:rating:form notify="email@example.com|email2@example.com"}

notify_author

yes/no

This parameter sends notification emails to the author of the channel entry. Used in conjunction with the owner_template parameter.

accepts: "y","n"

{exp:rating:form notify_author="yes"}

owner_template

This parameter is for specifying the author notification template to be used for sending a notification email to the Author of the entry when new ratings are submitted. When this parameter is used, it automatically sends email notifications to the author of the channel entry. Used in conjunction with the notify_author parameter.

{exp:rating:form owner_template="some_template"}

rating_id

{exp:rating:form rating_id="{segment_3}"}

required

This parameter allows you to control which fields you wish to be required for your users to fill in.

{exp:rating:form required="rating|review"}

return

This parameter determines where to send users once they have submitted your form.

{exp:rating:form return="template_group/template_name"}

secure_action

yes/no

This parameter allows you to set the action on the form to have https://. Used for securely processing forms with SSL.

accepts: "y","n"

{exp:rating:form secure_action="yes"}

secure_return

yes/no

This parameter allows you to set the return on the form to have https://. Used for securely processing forms with SSL.

accepts: "y","n"

{exp:rating:form secure_return="yes"}

status

This parameter allows you to set the status of incoming ratings. By default, all ratings are set to open. If you wish to review ratings first, set the status parameter to closed. For performance reasons, rating submissions with a status of closed will not run the Stats update routine (and therefore Rating:Stats will not include those ratings in the stats data until they are switched to a different status). You can use the module CP to review/modify/delete any of the ratings. To create custom statuses, simply specify any status name you want in this parameter, and it will be created and applied to the rating.

{exp:rating:form status="closed"}

template

string

This parameter is used to tell the Rating module which template to use to format messages returned by the module for successful and unsuccessful actions. You will most likely be using this parameter to enable AJAX functionality. Two conditionals and one variable become available in the template that you refer to. {if success}{/if} will evaluate to true if the submission action is successful. {if failure}{/if} will evaluate to true if the submission fails for some reason. And {message} will return the message from the Rating module indicating the details of a successful or unsuccessful action.

{exp:rating:form template="template_group/template_name"}

user_template

string

This parameter is for specifying the user notification template to be used for sending a notification emails of followup ratings to users that have submitted a rating, and subscribed to the entry by checking the notify_me checkbox.

{exp:rating:form user_template="some_template"}

field:FIELD_NAME:values

string

This parameter is used to force the user to only be able to submit one of the specified values for a given numerical rating field. Separate multiples with the pipe character.

{exp:rating:form field:FIELD_NAME:values="1|2|5"}

field:FIELD_NAME:min

integer

This parameter is used to force the user to have to submit a value equal to or higher than the specified value for a given numerical rating field.

{exp:rating:form field:FIELD_NAME:min="1"}

field:FIELD_NAME:max

integer

This parameter is used to force the user to have to submit a value equal to or lower than the specified value for a given numerical rating field.

{exp:rating:form field:FIELD_NAME:max="5"}

output_json

yes/no

Using this parameter with a value of yes allows for AJAX requests to return errors and success mesages in JSON. Default is no.

accepts: "y","n"

{exp:rating:form output_json="yes"}

ajax_request

yes/no

Using this parameter with a value of no forces the form to do a standard redirect after a new entry is inserted, even when the request was made via AJAX.

accepts: "y","n"

{exp:rating:form ajax_request="no"}

Variables

name

This variable will be replaced by the screen name of the logged in user or the name of a Guest that has opted to save their info for their next visit using the save_info form field. For logged in members, beware using this variable if you place your Rating:Form inside of a Channel:Entries loop. You should instead use the {logged_in_screen_name} variable. In edit mode, this variable will parse as the screen name of the member (or name for guest) that submitted the rating.

{name}

email

This variable will be replaced by the email address of the logged in user or the email address of a Guest that has opted to save their info for their next visit using the save_info form field. For logged in members, beware using this variable if you place your Rating:Form inside of a Channel:Entries loop. You should instead use the {logged_in_email} variable. In edit mode, this variable will parse as the email address of the member (or email the guest supplied) that submitted the rating.

{email}

url

This variable will be replaced by the email address of the logged in user or the email address of a Guest that has opted to save their info for their next visit using the save_info form field. For logged in members, beware using this variable if you place your Rating:Form inside of a Channel:Entries loop. You should instead use the {logged_in_email} variable. In edit mode, this variable will parse as the email address of the member (or email the guest supplied) that submitted the rating.

{url}

location

This variable will be replaced by the Location of the logged in user or the Location of a Guest that has opted to save their info for their next visit using the save_info form field. In edit mode, this variable will parse as the location for the member or guest that submitted the rating.

{location}

captcha

This variable will be replaced by the CAPTCHA image generated by the system. It will only appear for guests if you have enabled Captcha's in the Rating module CP, and will only appear for logged in members if you've also set the Require CAPTCHA with logged-in members? preference in EE CAPTCHA Preferences to Yes.

{captcha}

rating_author_id

This variable becomes available for use in edit mode, and parses as the member ID of the author that submitted the rating. If submitted by a guest, it'll parse as 0. You might typically use this as a conditional to check to see if the submitter was a guest or not, and then display different fields accordingly.

{rating_author_id}

FIELD_NAME

You can parse values for all your custom Rating fields when using the Rating form in edit mode. Simply use the short name of the Rating field specified in the Rating CP.

{FIELD_NAME}

Tag Parameters

collection

string

Rating allows you to dynamically sort ratings into groups at submission. This is done by specifying the collection parameter on your Rating:Form tag. To filter ratings by one of those groups, just specify the collection parameter and a value for your Rating:Entries loop.

{exp:rating:entries collection="Shark Reviews"}

dynamic

By default, this tag will search the URI for an entry ID or URL title. This parameter allows you to disable this dynamic checking.

{exp:rating:entries dynamic="off"}

entry_id

This parameter allows you to hardcode an entry ID, or pass the entry ID dynamically from the Channel:Entries loop or through the URI or an embed.

{exp:rating:entries entry_id="{entry_id}"}

exclude_unrated

yes/no

This parameter allows you to exclude rating entries that contain no value (unrated) for the specified numeric rating field(s). Used together with the unrated_fields parameter. This feature can be enabled using a value of yes. Default is no.

accepts: "y","n"

{exp:rating:entries exclude_unrated="yes"}

fractions

This parameter allows you to specify which character to indicate fractions in numeric ratings. By default, the value is a decimal (.).

{exp:rating:entries fractions="."}

limit

integer

This parameter allows you to limit the number of ratings in your results.

{exp:rating:entries limit="20"}

orderby

This parameter allows you to control the order of your ratings. You can specify any custom Rating field, rating_date, votes or random. When ordering by votes, the rating reviews will be ordered by the highest voted (from Rating:Insert_Rating_Vote feature).

{exp:rating:entries orderby="some_custom_rating_field"}

paginate

This parameter allows you to control where the pagination will display. Options are top, bottom, or both. Used in conjunction with the rating_paginate variable pair.

{exp:rating:entries paginate="both"}

precision

integer

This parameter allows you to specify the number of decimals to round fractions on numerical rating fields for averages. For example, a value of 1 would give you a result like this for a rating value: 4.5. Default is 0.

Default: 0

{exp:rating:entries precision="1"}

rating_author_id

This parameter allows you to limit ratings by a specific member. This can be hardcoded or specified dynamically in the URI. Be sure to use the dynamic parameter if you're placing a member ID in the URI. Also accepts CURRENT_USER. You can also use the Rating:Entries tag as a standalone tag to display all ratings submitted by a given member (across all entries) - just omit the entry_id parameter.

{exp:rating:entries rating_author_id="{segment_3}"}

rating_author_username

This parameter allows you to limit ratings by a specific member. This can be hardcoded or specified dynamically in the URI. You can also use the Rating:Entries tag as a standalone tag to display all ratings submitted by a given member (across all entries) - just omit the entry_id parameter.

{exp:rating:entries rating_author_username="{segment_3}"}

rating_id

It's possible to show a specific rating submission by specifying the rating_id parameter and hardcoding a rating ID or grabbing it dynamically from the URI.

{exp:rating:entries rating_id="{segment_3}"}

scale

integer

By default, Rating assumes your rating scale is 5. As in, your numerical ratings are out of 5 (ex: 1 out of 5 stars, 2 out of 5 stars, etc). You can however, change the scale to be out of 10 by specifying the scale parameter. When you specify this, the stars variable pairs will switch from the default of 5 graphic images to 10 when placed around your numerical rating value.

Default: 5

{exp:rating:entries scale="10"}

sort

This parameter allows you to indicate which direction to sort your entries. Options are ascending (asc) or descending (desc).

{exp:rating:entries sort="asc"}

status

This parameter allows you to filter ratings by their status. By default, it will only show ratings that are open. To specify multiple statuses, use the pipe character. The closed status for ratings is a special/reserved status. For performance reasons, rating submissions with a status of closed will not run the Stats update routine (and therefore Rating:Stats (and the stats available to Rating:Entries) will not include those ratings in the stats data until they are switched to a different status).

{exp:rating:entries status="open"}

stars_image_path

This parameter allows you to specify an alternate Rating star image theme. This controls the images displayed when using the stars variable pair. Specify the public path to your rating image assets folder (that contains star-0, star-25 etc). By default, it loads the Rating images located at ./themes/user/rating/default/images. Used in conjunction with the stars_filetype, stars_height and stars_width parameters.

{exp:rating:entries stars_image_path="assets/images/rating"}

stars_filetype

This parameter allows you to override the default file extension of the images produced for the "star" value of the rating. Just specify a value of png (default), jpg or gif. Used in conjunction with the stars_image_path, stars_height and stars_width parameters.

{exp:rating:entries stars_filetype="png"}

stars_height

This parameter allows you to override the default height of the images produced for the "star" value of the rating. Just specify a numeric value (in pixels). Default is 25 pixels. Used in conjunction with the stars_image_path, stars_filetype and stars_width parameters.

{exp:rating:entries stars_height="40"}

stars_width

This parameter allows you to override the default width of the images produced for the "star" value of the rating. Just specify a numeric value (in pixels). Default is 25 pixels. Used in conjunction with the stars_image_path, stars_filetype and stars_height parameters.

{exp:rating:entries stars_width="40"}

thousands

This parameter allows you to specify which character to use to separate groups of thousands in numeric rating fields. For example, a value of , (comma) would parse 10000 as 10,000.

{exp:rating:entries thousands=","}

timeframe_start

This parameter allows you specify a start date from which to pull ratings for a given channel entry that were submitted on or after this date. This parameter is often used together with the timeframe_end parameter for limiting the entry display to a specific date range, but is not required. Additionally, the date formatting is VERY flexible. You can use exact timestamp style, or something relative like 2 weeks ago.

{exp:rating:entries timeframe_start="60 days ago"}

timeframe_end

string/timestamp

This parameter allows you specify an end date from which to pull ratings for a given channel entry that were submitted on or before this date. This parameter is often used together with the timeframe_start parameter for limiting the entry display to a specific date range, but is not required. Additionally, the date formatting is VERY flexible. You can use exact timestamp style, or something relative like 2 weeks ago.

{exp:rating:entries timeframe_end="30 days ago"}

unrated_only

yes/no

This parameter allows you to list only rating entries that contain no value (unrated) for the specified numeric rating field(s). Used together with the unrated_fields parameter. This feature can be enabled by using a value of yes. Default is no.

accepts: "y","n"

Default: n

{exp:rating:entries unrated_only="yes"}

unrated_fields

This parameter allows you to specify numeric rating fields to check against that contain no value (unrated). To specify multiple rating fields, use the pipe character. When used with the unrated_only parameter, rating entries in which all fields specifed are unrated will be excluded. When used with the exclude_unrated parameter, rating entries in which one or more of the fields specified contain a rated value will be displayed.

{exp:rating:entries unrated_fields="rating"}

Variables

absolute_results

This variable displays the total number of results pulled from the database and thus the total number that will be displayed on all pages.

{absolute_results}

avatar_filename

Parses as the file name of the users avatar. Used in conjunction with avatar_url, avatar_height, avatar_width variables.

{if avatar_filename}<img src="{avatar_url}" height="{avatar_height}" width="{avatar_width}" />{/if}

avatar_url

Parses as the full file path (including file name) of the user's avatar. Used in conjunction with avatar_filename, avatar_height, avatar_width variables.

{{if avatar_url}<img src="{avatar_url}" height="{avatar_height}" width="{avatar_width}" />{/if}}

avatar_height

Parses as the width of the user's avatar. Used in conjunction with avatar_filename, avatar_url, avatar_width variables.

{avatar_height}

avatar_width

Parses as the width of the user's avatar. Used in conjunction with avatar_filename, avatar_url, avatar_height variables.

{avatar_width}

count

This variable displays the position number of the rating in the list for a given page. This number will always reset back to 1 for the first result on the page if used with pagination.

{count}

rating_email

This variable displays the email address of the user that submitted the rating.

{rating_email}

first_rating

The first_rating variable will display the numeric rating of the FIRST rating submitted by the user for the given entry. This is useful if you're allowing users to submit more than 1 rating/review for an entry (to simulate comments, etc), but only letting them submit the first one with a numeric rating (you can make this happen by wrapping the if not_duplicate conditional around the numeric Rating field in your Rating:Form tag) so the rating score does not get skewed. Note: This variable will only work with registered/logged in members, and does not work with Guest ratings.

{first_rating}

gmt_rating_date

This variable allows you to display the date of the Rating submission in GMT. Time formatting is also available.

{gmt_rating_date format="%F %j, %Y at %g:%i %a"}

gmt_rating_edit_date

This variable allows you to display the date of the Rating submission in which the rating was edited (in the CP) in GMT. Time formatting is also available.

{gmt_rating_edit_date format="%F %j, %Y at %g:%i %a"}

name

This variable displays the screen name of the user that submitted the rating, or the name entered by a guest in the name field in the Rating form.

{name}

rating

This variable will parse out the value for this field for a given rating entry. All of your other Rating fields are available for output here. Simply use the short name of the Rating field specified in the Rating CP.

{rating}

review

This variable will parse out the value for this field for a given rating entry. All of your other Rating fields are available for output here. Simply use the short name of the Rating field specified in the Rating CP.

{review}

rating_location

This variable will parse out the value the of the submitters location. If the rating was submitted by a member it will parse the value in the members location member field. If the rating was submitted by a guest, it will parse out the value the guest filled in the location form field, if any.

{rating_location}

rating_date

This variable allows you to display the date of the Rating submission. Time formatting is also available.

{rating_date format="%F %j, %Y at %g:%i %a"}

rating_edit_date

This variable allows you to display the date of the Rating submission in which it was edited (in the CP). Time formatting is also available.

{rating_edit_date format="%F %j, %Y at %g:%i %a"}

rating_id

This variable outputs the unique ID of the rating submission.

{rating_id}

rating_status

This variable will parse out the status for the given rating entry.

{rating_status}

switch

This variable will output alternately by each of the two values you provide. You would typically use this for styling your results with CSS.

{switch="blue|red"}

total_results

This variable displays the total number of results in the list for a given page. This number will always "reset" on the page if used with pagination. You would typically use this in a conditional statement.

{total_results}

total_rating_count

This variable displays the total number of ratings for the entry.

{total_rating_count}

FIELD_NAME

All of your Rating fields are available for output here. Simply use the short name of the Rating field specified in the Rating CP.

{FIELD_NAME}

Tag Parameters

admin_template

string

This parameter is for specifying the admin notification template to be used for sending a notification email to an Admin. Used in conjunction with the notify parameter.

{exp:rating:comment_from admin_template="some_template"}

anonymous

yes/no

This parameter controls whether or not the comment form will accept submissions from Guests without the name and email fields filled in.

accepts: "y","n"

{exp:rating:comment_from anonymous="no"}

edit

yes/no

This parameter allows you to use your Rating Comment form in "edit" mode. With this enabled, Super Admins and authors can edit their rating comment submissions. Simply add this parameter in conjunction with the rating_comment_id parameter and users will be able to edit the ratings they submitted.

accepts: "y","n"

{exp:rating:comment_from edit="yes"}

attribute

string

This parameter allows you to control any form attribute for the form in your template. Simply replace attribute with an attribute name such as id, name, class, etc, and specify a value for that attribute. You can specify this parameter multiple times to control as many attributes as necessary. This would normally be done to control your form with Javascript or style it with CSS.

{exp:rating:comment_from form:class="your_class_name"}

notify

string

This parameter sends notification emails to the email address(es) specified when new comments are submitted. Used in conjunction with the admin_template parameter. Separate multiple email addresses with the pipe character.

{exp:rating:comment_from notify="email@example.com|email2@example.com"}

owner_template

string

This parameter is for specifying the author notification template to be used for sending a notification email to the Author of the entry when new ratings are submitted. When this parameter is used, it automatically sends email notifications to the author of the channel entry.

{exp:rating:comment_from owner_template="some_template"}

rating_id

This parameter is required to display the comment form. You can pull a rating ID from the Rating:Entries tag, from the URI, or if you need, to pass the rating ID through an embedded template.

{exp:rating:comment_from rating_id="{segment_3}"}

rating_comment_id

This parameter is used in conjunction with the edit parameter and is required be able to allow users to edit their rating comment with the Rating Comment form. You can pull a rating comment ID from the URI, or if you need, to pass the rating comment ID through an embedded template.

{exp:rating:comment_from rating_comment_id="{segment_3}"}

require_membership

yes/no

This parameter lets you set whether or not you want users to be logged in members to submit comments. Specifying a value of yes means that a user has to be logged in to submit comments. Default is no (guests can submit comments as well).

accepts: "y","n"

Default: n

{exp:rating:comment_from require_membership="yes"}

return

string

This parameter determines where to send users once they have submitted your form.

{exp:rating:comment_from return="template_group/template_name"}

secure_action

This parameter allows you to set the action on the form to have https://. Used for securely processing forms with SSL.

{exp:rating:comment_from secure_action="yes"}

secure_return

This parameter allows you to set the return on the form to have https://. Used for securely processing forms with SSL.

{exp:rating:comment_from secure_return="yes"}

site_id

If you're using MSM (Multiple Site Manager), be sure to specify this parameter so Rating comments are saved to the correct MSM Site.

{exp:rating:comment_from site_id="2"}

status

string

This parameter allows you to set the status of incoming commments. By default, all comments are set to open. If you wish to review comments first, set the status parameter to closed. To create custom statuses, simply specify any status name you want in this parameter, and it will be created and applied to the comment.

Default: open

{exp:rating:comment_from status="oogabooga"}

template

string

This parameter is used to tell the Rating module which template to use to format messages returned by the module for successful and unsuccessful actions. You will most likely be using this parameter to enable AJAX functionality. Two conditionals and one variable become available in the template that you refer to. {if success}{/if} will evaluate to true if the submission action is successful. {if failure}{/if} will evaluate to true if the submission fails for some reason. And {message} will return the message from the Rating module indicating the details of a successful or unsuccessful action.

{exp:rating:comment_from template="template_group/template_name"}

user_template

This parameter is for specifying the user notification template to be used for sending a notification emails of followup comments to users that have submitted a rating, and subscribed to the entry by checking the notify_me checkbox.

{exp:rating:comment_from user_template="some_template"}

output_json

yes/no

Using this parameter with a value of yes allows for AJAX requests to return errors and success mesages in JSON. Default is no.

accepts: "y","n"

Default: n

{exp:rating:comment_from output_json="yes"}

ajax_request

yes/no

Using this parameter with a value of no forces the form to do a standard redirect after a new entry is inserted, even when the request was made via AJAX.

accepts: "y","n"

{exp:rating:comment_from ajax_request="no"}

Variables

rating_comment

In edit mode, this variable will parse as the rating comment of the member that submitted the rating comment.

{rating_comment}

rating_comment_name

This variable will be replaced by the screen name of the logged in user or the name of a Guest that has opted to save their info for their next visit using the save_info form field.

{rating_comment_name}

rating_comment_email

This variable will be replaced by the email address of the logged in user or the email address of a Guest that has opted to save their info for their next visit using the save_info form field.

{rating_comment_email}

rating_comment_url

This variable will be replaced by the URL of the logged in user or the URL of a Guest that has opted to save their info for their next visit using the save_info form field.

{rating_comment_url}

rating_comment_location

This variable will be replaced by the Location of the logged in user or the Location of a Guest that has opted to save their info for their next visit using the save_info form field.

{rating_comment_location}

rating_comment_captcha

This variable will be replaced by the CAPTCHA image generated by the system. It will only appear for guests if you have enabled Captcha's in the Rating module CP, and will only appear for logged in members if you've also set the Require CAPTCHA while logged in? preference in EE CAPTCHA Preferences to Yes. Used in conjunction with captcha form field and rating_comment_captcha conditional.

{rating_comment_captcha}

Tag Parameters

limit

integer

This parameter allows you to limit the number of comments in your results.

{exprating:comments limit="20"}

orderby

string

This parameter allows you to control the order of your comments. You can specify date, or random.

{exprating:comments orderby="date"}

paginate

string

This parameter allows you to control where the pagination will display. Options are top, bottom, or both. Used in conjunction with the rating_comment_paginate variable pair.

{exprating:comments paginate="both"}

rating_id

string

This parameter is required and necessary to display comments for a given rating review. You can pull a rating ID from the Rating:Entries tag, from the URI, or if you need, to pass the rating ID through an embedded template.

{exprating:comments rating_id="{segment_3}"}

sort

This parameter allows you to indicate which direction to sort your comments. Options are ascending (asc) or descending (desc).

{exprating:comments sort="asc"}

status

This parameter allows you to filter ratings by their status. By default, it will only show ratings that are open. To specify multiple statuses, use the pipe character.

{exprating:comments status="open"}

Variables

rating_comment_author_id

This variable displays the member ID of the user that submitted the comment.

{rating_comment_author_id}

rating_comment_avatar

This variable is available as a conditional, and can be used to display a member's avatar with other related variables, such as rating_comment_avatar_url, rating_comment_avatar_height, and rating_comment_avatar_width.

{{if rating_comment_avatar} <img src="{rating_comment_avatar_url}"  height="{rating_comment_avatar_height}"   width="{rating_comment_avatar_width}"    /> {/if}       }

rating_comment_count

This variable displays the position number of the comment in the list for a given page.

{rating_comment_count}

rating_comment_email

This variable displays the email address of the user that submitted the comment.

{rating_comment_email}

rating_comment_name

This variable displays the screen name of the user that submitted the comment, or the name entered by a guest in the name field in the comment form.

{rating_comment_name}

rating_comment_screen_name

This variable displays the screen name of the logged in user that submitted the comment. For parsing of names for guests, refer to the rating_comment_name variable. This variable can also be used as a conditional to check if the comment submitted was a logged in user or a guest.

{rating_comment_screen_name}

rating_comment_group_id

This variable displays the member group ID of the user that submitted the comment.

{rating_comment_group_id}

rating_comment_photo

This variable is available as a conditional, and can be used to display a member's photo with other related variables, such as rating_comment_photo_url, rating_comment_photo_height, and rating_comment_photo_width.

{{if rating_comment_photo}{/if}}

rating_comment

This variable will parse out the comment that was submitted.

{rating_comment}

rating_comment_location

This variable will parse out the value the of the submitters location. If the comment was submitted by a member it will parse the value in the members location member field. If the comment was submitted by a guest, it will parse out the value the guest filled in the location form field, if any.

{rating_comment_location}

rating_comment_date

This variable allows you to display the date of the comment submission. Usual EE time formatting is also available.

{rating_comment_date  format="%F %j, %Y at %g:%i %a"}

rating_comment_switch

This variable will output alternately by each of the two values you provide. You would typically use this for styling your results with CSS.

{rating_comment_switch="blue|red"}

rating_comment_total_results

This variable displays the total number of results in the list for a given page. You would typically use this in a conditional statement.

{rating_comment_total_results}

rating_comment_absolute_results

This variable displays the total number of results in the list across all pages (if pagination is used). You would typically use this in a conditional statement.

{rating_comment_absolute_results}

Tag Parameters

entry_id

integer

This parameter should be specified when you wish to delete all ratings for a particular entry. You would usually grab the entry ID of the entry through a segment in the URL.

{exp:rating:delete entry_id="{segment_4}"}

rating_id

integer

This parameter should be specified when you wish to a specific rating on an entry. You would usually grab the rating ID of the entry through a segment in the URL.

{exp:rating:delete rating_id="{segment_4}"}

rating_comment_id

This parameter should be specified when you wish to delete a specific rating comment for a specific Rating entry. You would usually grab the rating comment ID of the entry through a segment in the URL. You must be the author of the comment or a Super Admin to be able to delete the comment.

{exp:rating:delete rating_comment_id="{segment_4}"}

Variables

message

This variable will output the appropriate message once a rating or entry's ratings are deleted, or not.

{message}