Rating Documentation

Rating:Stats template tag

The Rating:Stats tag allows you display stats based on numerical rating fields for your channel entries. In other words, you can show how many times an entry has been rated, it's average rating, and more with this function. This can be used as a standalone stats display for an entry, or it can also be used with other Rating functions such as the Rating:Rank tag.

{exp:rating:stats} content {/exp:rating:stats}

Parameters

The following parameters are available for use:

collection

collection="Shark Reviews"

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.

entry_id

entry_id="{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.

fractions

fractions="."

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

precision

precision="2"

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.

scale

scale="5"

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.

stars_image_path

stars_image_path="assets/images/rating"

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.

stars_filetype

stars_filetype="png"

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.

stars_height

stars_height="40"

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.

stars_width

stars_width="40"

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.

status=

status="open|Pending|Custom"

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).

thousands

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).

Variables

The following variables are available for use:

overall_avg

{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_count

{overall_count}

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

overall_sum

{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.

avg_FIELD_NAME

{avg_FIELD_NAME}

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

count_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.

sum_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.

stars_overall_avg

{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_avg_FIELD_NAME

{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.

Conditionals

Conditionals are available on all of the variables above. Additionally these exist as well:

rating_no_results

{if rating_no_results}Sorry, no ratings have been submitted for this entry yet.{/if}

This conditional evaluates to true and displays its contents when there are no results found for this tag.

Examples

The following is a basic example of how you would display some simple Rating stats for an entry (on a Single entry view page):

{exp:channel:entries require_entry="yes"}

    <h2>{title}</h2>
    <p>{body}</p>

    <h4>Rating 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>
        {if rating_no_results}
            <p>No ratings have been submitted for this entry yet.</p>
        {/if}
    {/exp:rating:stats}

{/exp:channel:entries}

Support

Having problems setting up and/or using Rating? Support is offered from 10am to 4pm EST weekdays. Send us an email at help@eeharbor.com and we will respond as quickly as we can.