Rating Documentation

Rating:Form template tag

The Rating:Form tag allows your visitors to submit ratings/reviews for your channel entries. This form would typically be displayed on a Single entry page underneath a Channel:Entries loop that's displaying your channel entry. Additionally, the Rating form can be used to allow your users or Super Admins edit ratings via the front end. Users have permission to edit their own rating submissions, and Super Admins have access to edit ALL rating submissions.

{exp:rating:form} content {/exp:rating:form}

Parameters

The following parameters are available for use:

admin_template=

admin_template="some_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.

allow_duplicates=

allow_duplicates="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.

allow_unrated=

allow_unrated="rating"

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.

anonymous=

anonymous="no"

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

collection=

collection="Hotel Reviews"

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.

duplicate_check_guest_ip=

duplicate_check_guest_ip="no"

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.

entry_id

entry_id="{entry_id}"

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.

edit

edit="yes"

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.

form:attribute=

form:class="your_class_name"

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.

notify=

notify="email@example.com|email2@example.com"

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.

notify_author=

notify_author="yes"

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

owner_template=

owner_template="some_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.

rating_id

rating_id="{segment_3}"

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

required=

required="rating|review"

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

return

return="template_group/template_name"

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

secure_action=

secure_action="yes"

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

secure_return=

secure_return="yes"

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

status

status="closed"

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.

template

template="template_group/template_name"

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.

user_template=

user_template="some_template"

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.

field:FIELD_NAME:values=

field:FIELD_NAME:values="1|2|5"

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.

field:FIELD_NAME:min=

field:FIELD_NAME:min="1"

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.

field:FIELD_NAME:max=

field:FIELD_NAME:max="5"

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.

output_json=

output_json="yes"

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

ajax_request=

ajax_request="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.

Variables

All standard and custom member fields are available for use. Additionally, these are also available:

name

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

email

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

url

{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. In edit mode, this variable will parse as the URL of the member or guest that submitted the rating.

location

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

captcha

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

rating_author_id

{if rating_author_id == "0"}{/if}

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.

FIELD_NAME

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

Conditionals

The following conditionals are available for use:

captcha

{if captcha}{/if}

This conditional is available to show/hide your CAPTCHA image based on whether or not it's required. 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.

duplicate

{if duplicate}{/if}

This conditional will display its contents if the user viewing the Rating form has already submitted a rating for the channel entry. It checks to see if a value has been submitted for the default rating field.

not_duplicate

{if not_duplicate}{/if}

This conditional will display its contents if the user viewing the Rating form has NOT yet submitted a rating for the channel entry. It checks to see if a value has been submitted for the default rating field.

rating_no_results

{if rating_no_results}{/if}

This conditional will display its contents if the current user does not have sufficient privileges to submit ratings.

Form Fields

The following form fields are available for use:

captcha

<input type="text" name="captcha" />

This form field allows your users to submit the contents of the CAPTCHA image. Used in conjunction with captcha variable.

email

<input type="text" name="email" />

This form field is intended for use with Guest submissions, and will collect the email address of the Guest submitting a rating. A logged in members' email address will be recorded automatically without any need of specifying this field. This field is required when a user is not logged in and the Require email address for Guests? setting in the Rating Preferences tab is set to Yes.

location

<input type="text" name="location" />

This form field will collect the location of the Guest submitting a rating. Can be later parsed out in the Rating:Entries loop by using the rating_location variable.

name

<input type="text" name="name" />

This form field will collect the name of the Guest submitting a rating. A logged in members' screen name will be recorded automatically without any need of specifying this field. This field is required when a user is not logged in unless you've specified the anonymous parameter (set to yes).

save_info

<label for="save_info">
    <input type="checkbox" name="save_info" id="save_info" value="y" {save_info} />
    Remember my contact info for next time? (Guests)
</label>

This form field allows your Guests to save their contact info for their next visits to your site. All fields such as name, email, url and location will pre-populate with the Guest's information for next time, providing you include the {name}, {email}, {url} and {location} variables as values for the form fields. A {save_info} variable also becomes available and parses as checked="checked" to automatically select the save_info checkbox for next time as well.

notify_me

<label for="notify_me">
    <input type="checkbox" name="notify_me" id="notify_me" value="y" {notify_me} />
    Notify me of future Ratings?
</label>

This form field allows your users to subscribe to a channel entry to be notified of future ratings submitted by others for that particular channel entry. A {notify_me} variable also becomes available an parses as checked="checked" to automatically select the notify_me checkbox for next time as well. Be sure to specify the user_template parameter to designate a notification template for this feature.

url

<input type="text" name="url" />

This form field will collect the URL of the Guest submitting a rating.

rating

<input type="text" name="rating" />

The rating field is a default Rating field (cannot be deleted). While this field is not necessarily required to be used to submit the Rating form (you may just want to collect reviews, or use custom numeric Rating fields), when collecting numeric ratings, it's best practice to use this as your numeric Rating field or one of your numeric Rating fields if you're using multiple numeric custom Rating fields. Some Rating functions assume data in the rating field, and may not run correctly without it. Also, it's very important to know that a value of 0 for a rating is NOT the same as a NULL (empty) value for a numeric rating field. To Stats calculation functions, a NULL value means "don't look at me I'm not here", and a 0 value means "WORST. THING. EVAR.". To submit a NULL value for the rating field, the field needs to be omitted completely from the form, otherwise it'll submit a 0 (if if you submit no value).

review

<input type="text" name="review" />

The review field is a default Rating field (cannot be deleted). If you're using this field in your form to collect reviews, just specify review as the field name.

FIELD_NAME

<input type="text" name="FIELD_NAME" />

All of your custom Rating fields are available to collect data from users when they submit a rating. Simply use the short name of the Rating field specified in the Rating CP. You can format your fields to be any form field type you wish.

Examples

The below example allows users with proper privileges to submit ratings for a given entry on a Single entry view template:

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

{exp:rating:form
    entry_id="{segment_3}"
    collection="Hotel Reviews"
    return="rating/thanks"
}

    <h4>Submit a Rating for this Entry:</h4>

    <!-- only show this to guests -->
    {if logged_out}
        <p>
            <label for="name">Name</label>
            <input type="text" name="name" id="name" value="{name}" />
        </p>
        <p>
            <label for="email">Email</label>
            <input type="text" name="email" id="email" value="{email}" />
        </p>
        <p>
            <label for="save_info">
                <input type="checkbox" name="save_info" id="save_info" value="y" {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>
        <textarea name="review" id="review"></textarea>
    </p>

    <!-- checks Rating CAPTCHA preferences and EE CAPTCHA preferences to see if CAPTCHA is required -->
    {if captcha}
        <p>
            <label for="captcha">Please enter in the word you see below</label>
            <input type="text" name="captcha" id="captcha" />
        </p>
        <p>
            {captcha}
        </p>
    {/if}

    <p>
        <input type="submit" name="submit" value="Submit" />
    </p>

    {if rating_no_results}
        <p>
            Sorry, you currently do not have sufficient privileges to submit ratings.
        </p>
    {/if}

{/exp:rating:form}

The following code is what your Edit form might look like, allowing logged in users to edit their rating submissions, assuming the rating ID is in the third segment of the URI:

{exp:rating:form
    collection="Hotel Reviews"
    edit="yes" rating_id="{segment_3}"
    return="rating/edit/success"
}

<!-- checks to see if submission was from a guest -->
{if rating_author_id == "0"}
    <p>
        <label for="name">Name</label>
        <input type="text" name="name" id="name" value="{name}" />
    </p>
    <p>
        <label for="email">Email</label>
        <input type="text" name="email" id="email" value="{email}" />
    </p>
{/if}

    <p>
        <label for="rating">Your Rating</label>
        <select name="rating" id="rating">
            <option value="1" {if rating == "1"}selected{/if}>1</option>
            <option value="2" {if rating == "2"}selected{/if}>2</option>
            <option value="3" {if rating == "3"}selected{/if}>3</option>
            <option value="4" {if rating == "4"}selected{/if}>4</option>
            <option value="5" {if rating == "5"}selected{/if}>5</option>
        </select>
    </p>
    <p>
        <label for="review">Your Review</label>
        <textarea name="review" id="review">{review}</textarea>
    </p>
    <p>
        <input type="submit" name="submit" value="Update" />
    </p>

{if rating_no_results}
    <p>
        Sorry, you currently do not have sufficient privileges to submit ratings.
    </p>
{/if}

{/exp:rating:form}

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.