ExpressionEngine Add-ons

Rating:Entries template tag

The Rating:Entries loop allows you to display all submitted ratings/reviews for your channel entries. This can also be filtered down by collection, status, author, timeframe of dates ratings were submitted, etc. You can even use as a standalone to display all ratings by a given member. This loop would typically be used on a single entry page underneath a Channel:Entries loop that's displaying your channel entry.

{exp:rating:entries} content {/exp:rating:entries}

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 ratings by one of those groups, just specify the collection parameter and a value for your Rating:Entries loop.

dynamic=

dynamic="off"

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

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.

exclude_unrated=

exclude_unrated="yes"

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.

fractions=

fractions="."

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

limit=

limit="20"

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

orderby=

orderby="some_custom_rating_field"

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

paginate=

paginate="both"

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.

precision=

precision="1"

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.

rating_author_id=

rating_author_id="{segment_3}"

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.

rating_author_username=

rating_author_username="{segment_3}"

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.

rating_id=

rating_id="{segment_3}"

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.

scale=

scale="10"

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.

sort=

sort="asc"

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

status=

status="open"

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

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.

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.

timeframe_start=

timeframe_start="60 days ago"

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.

timeframe_end=

timeframe_end="30 days ago"

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.

unrated_only=

unrated_only="yes"

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.

unrated_fields=

unrated_fields="rating"

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.

Variables

Most of the standard and custom member field variables available here. Additionally, these exist as well:

absolute_results

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

avatar_filename

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

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

avatar_url

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

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.

avatar_height

{avatar_height}

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

avatar_width

{avatar_width}

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

count

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

rating_email

{rating_email}

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

first_rating

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

gmt_rating_date

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

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

gmt_rating_edit_date

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

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.

name

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

rating

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

review

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

rating_location

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

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

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

rating_edit_date

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

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_id

{rating_id}

This variable outputs the unique ID of the rating submission.

rating_status

{rating_status}

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

switch

{switch="blue|red"}

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

total_results

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

{total_rating_count}

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

FIELD_NAME

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

Variable Pairs

The following variable pairs are available for use:

rating_paginate

{rating_paginate}
    <li>
        Page {rating_current_page} of
        {rating_total_pages} pages &nbsp;
        {rating_pagination_links}
    </li>
{/rating_paginate}

OR

{rating_paginate}
<ul class="pagination">
    {rating_pagination_links}
        {first_page}
            <li><a href="{pagination_url}">First</a></li>
        {/first_page}
        {previous_page}
            <li><a href="{pagination_url}">&laquo; Previous</a></li>
        {/previous_page}
        {page}
            <li{if current_page} class="active"{/if}><a href="{pagination_url}">{pagination_page_number}</a></li>
        {/page}
        {next_page}
            <li><a href="{pagination_url}">Next &raquo;</a></li>
        {/next_page}
        {last_page}
            <li><a href="{pagination_url}">Last</a></li>
        {/last_page}
    {/rating_pagination_links}
</ul>
{/rating_paginate}

Pagination is available for this tag and works just like regular EE pagination, but each variable/variable pair is prepended with rating_ (except for any variables and variable pairs inside of the rating_pagination_links variable pair). Used in conjunction with the paginate parameter.

stars

{stars}{/stars}

This variable pair is used to create graphical representations of numeric rating fields. Inside of this variable pair you can call your numeric rating fields and they will be converted to their graphical representations using images from the rating theme folder you specify. For example, if you place the {rating} variable within this variable pair and the value is 3 out of 5, it will display 3 full stars and 2 empty/grayed out stars.

Conditionals

Most of the variables above in addition to standard and custom member fields are available as conditionals. Additionally, these exist as well:

can_delete

{if can_delete}{/if}

This conditional is available to show/hide a link to allow the currently logged in user to delete the rating. It respects the member group Deletion preference in the Rating CP.

can_edit

{if can_edit}{/if}

This conditional is available to show/hide a link to allow the currently logged in user to edit the rating. It allows Super Admins to edit all ratings, and logged in members to edit their own ratings.

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

Below is an example of how to display of a list of ratings that have been submitted to an entry, on a single entry page:

{exp:channel:entries require_entry="yes"}
    <h2>{title}</h2>
    <p>{body}</p>
{/exp:channel:entries}

<h3>Ratings for this Entry:</h3>
{exp:rating:entries
    paginate="both"
    limit="10"
}

    {if screen_name}
        <p><a href="{path='user/profile'}/{member_id}/">
            {screen_name}</a></p>
        {if avatar_filename}
            <img src="{avatar_url}" width="{avatar_width}" height="{avatar_height}" />
        {/if}
    {if:else}
        <p>{name} (Guest)</p>
    {/if}
        <p>{stars}{rating}{/stars}</p>
        <p>Submitted on {rating_date format="%F %j, %Y at %g:%i %a"}</p>
        <p>{review}</p>

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

    {rating_paginate}
        <p>Page {rating_current_page} of {rating_total_pages} pages
        {rating_pagination_links}</p>
    {/rating_paginate}

{/exp:rating:entries}

Below is an example of how to display of a standalone list of ratings submitted by the currently logged in user, along with a custom query to pull the entry title and URL title to generate a link:

Main Template:

{exp:rating:entries
    rating_author_id="CURRENT_USER"
    limit="10" paginate="bottom"
}

    <p><a href="{path='user/profile'}/{member_id}/">
        {screen_name}</a></p>
    {if avatar_filename}
        <img src="{avatar_url}" width="{avatar_width}" height="{avatar_height}" />
    {/if}
    <p>{stars}{rating}{/stars}</p>
    <p>Submitted on {rating_date format="%F %j, %Y at %g:%i %a"}</p>
    <p>{review}</p>
    {exp:query limit="1" sql="
        SELECT entry_id
        FROM exp_ratings
        WHERE rating_id = '{rating_id}'"
    }
        <p>Posted in {embed="rating/entry_title" entry_id="{entry_id}"}</p>
    {/exp:query}
</div>

{if rating_no_results}
    <p>You have not rated any entries yet.</p>
{/if}

{rating_paginate}
    <p>Page {rating_current_page} of {rating_total_pages} pages
        {rating_pagination_links}</p>
{/rating_paginate}

{/exp:rating:entries}

Embedded Template (located at "rating/entry_title"):

{exp:query sql="
    SELECT title, url_title
    FROM exp_channel_titles
    WHERE entry_id = '{embed:entry_id}'"
}
    <a href="{path='news/article'}/{url_title}/">{title}</a>
{/exp:query}