Rating templates are used to display rating elements on the front end. This can include like, text, current user rating, and other things. And, with the use of templates, you have a lot of control over the rating display.

This user guide is for the Default template for the Single Rating Block for the Thumbs Rating method.

Introduction

Single Rating Block is used to display rating for the single rating item. To do so, you can use one of the many provided templates each rating method has. But, each rating method has one main template, called Default that also includes additional actions and filters to control the display of the elements in the template without the need to directly modify the template. Because of that, the Default template is the best solution to be used as a general purpose template with additional control through filters and actions. Other templates might include some actions and filters too, and you should check individual templates.

Templates display various elements of the rating block. Some of these elements can be controlled by providing additional settings though function (method) calls, or by using filters to modify these additional settings. Each rating method has different methods available and different filters to modify settings. This user guide will show the whole process of how Default template works, and how can you modify the results by using filters and actions provided, and it will include references to the used filters and actions.

Anatomy of the Default Template

Here is how the Default Stars Rating template for single rating block looks like:

<?php // GDRTS Template: Default // ?>

<div class="<?php gdrts_loop()->render()->classes(); ?>">
    <div class="gdrts-inner-wrapper">

        <?php do_action('gdrts-template-rating-block-before'); ?>

        <?php

        do_action('gdrts-template-thumbs-rating-default-before-rating-stars');

        gdrts_loop()->render()->thumbs();

        do_action('gdrts-template-thumbs-rating-default-after-rating-stars');

        ?>

        <?php if (apply_filters('gdrts-template-thumbs-rating-default-show-rating-text', true)) { ?>

            <div class="gdrts-rating-text">
                <?php

                do_action('gdrts-template-thumbs-rating-default-before-rating-text');

                if (gdrts_loop()->render()->has_votes()) {
                    gdrts_loop()->render()->rating();
                } else {
                    $no_votes = __("No votes yet.", "gd-rating-system");

                    echo apply_filters('gdrts-template-thumbs-rating-default-no-votes-message', $no_votes);
                }

                do_action('gdrts-template-thumbs-rating-default-after-rating-text');

                ?>
            </div>

        <?php } ?>

        <?php

        if (apply_filters('gdrts-template-thumbs-rating-default-show-user-rating', true)) {
            if (gdrts_loop()->user()->has_voted()) {

            ?>

                <div class="gdrts-rating-user">
                    <?php

                    do_action('gdrts-template-thumbs-rating-default-before-user-rating');

                    gdrts_loop()->render()->vote_from_user();

                    do_action('gdrts-template-thumbs-rating-default-after-user-rating');

                    ?>
                </div>

            <?php

            }
        }

        ?>

        <?php

        if (gdrts_loop()->is_save()) {

        ?>

            <?php if (apply_filters('gdrts-template-thumbs-rating-default-show-thank-you', true)) { ?>

                <div class="gdrts-rating-thanks">
                    <?php

                    $thank_you = __("Thanks for your vote!", "gd-rating-system");

                    echo apply_filters('gdrts-template-thumbs-rating-default-thank-you-message', $thank_you);

                    ?>
                </div>

            <?php } ?>

        <?php

        } else {
            if (apply_filters('gdrts-template-thumbs-rating-default-show-please-wait', true)) {
                do_action('gdrts-template-thumbs-rating-default-before-please-wait');

                gdrts_loop()->please_wait();

                do_action('gdrts-template-thumbs-rating-default-before-please-wait');
            }
        }

        gdrts_loop()->json();

        do_action('gdrts-template-rating-block-after');
        do_action('gdrts-template-rating-rich-snippet');

        ?>

    </div>
</div>

Line 3 renders main wrapping DIV using method to get CSS classes for this rating block using method call: gdrts_loop()->render()->classes(). If you are customizing the template you can pass one or more CSS class as a string argument for the classes() method. This method runs the filter for all the CSS classes to add:

The rest of the rating block is inside the DIV with the gdrts-inner-wrapper class. The first action fired there is universal for all single block templates:

Rating Element

After that, we have the main thumbs rating element. This element has two actions fired before and after the stars are displayed: gdrts-template-thumbs-rating-default-before-rating-stars and gdrts-template-thumbs-rating-default-after-rating-stars. Stars are rendered on the line 12 using the method call: gdrts_loop()->render()->thumbs(). This method has various parameters you can set, or you can use the filter to modify them. For method information check this out:

Or, if you prefer to use the filter, check out the filter gdrts_render_single_thumbs_rating_args_stars. This filter works with all the templates, not just the Default one, if the template calls the thumbs() rendering method.

Most of the other template elements are optional.

Rating Text

Filter gdrts-template-thumbs-rating-default-show-rating-text is used to decide if the rating text will be displayed (default: true). Inside the rating text DIV, we have two actions fired: gdrts-template-thumbs-rating-default-before-rating-text and gdrts-template-thumbs-rating-default-after-rating-text. Between these two, we have the block that shows the rating text if the rating item has votes, or display ‘No votes.’ message if there are no votes. To display rating text, the template uses the method: gdrts_loop()->render()->rating().

Or, if you prefer to use the filter, check out the filter gdrts_render_single_thumbs_rating_args_rating. This filter allows you to modify the strings displaying the rating text. This filter works with all the templates, not just the Default one, if the template calls the rating() rendering method.

User Vote

Filter gdrts-template-thumbs-rating-default-show-user-rating is used to decide if the current user vote information will be displayed (default: true). If that is enabled, template checks if the user has voted at all, and if that is so, we have the user rating DIV with two actions fired: gdrts-template-thumbs-rating-default-before-user-rating and gdrts-template-thumbs-rating-default-after-user-rating. Between these two, the template uses a method gdrts_loop()->render()->vote_from_user() to display the user rating.

Or, if you prefer to use the filter, check out the filter gdrts_render_single_thumbs_rating_args_vote_from_user. This filter allows you to modify the strings displaying the user vote.This filter works with all the templates, not just the Default one if the template calls the vote_from_user() rendering method.

Thank you, and Please wait

Finally, we have the last section that shows ‘Thank you’ message when the vote is saved and ‘Please wait’ message when the vote is submitted. With the filter gdrts-template-thumbs-rating-default-show-thank-you template decides if the ‘Thank you’ message is displayed (default: true). Actions gdrts-template-thumbs-rating-default-before-thank-you and gdrts-template-thumbs-rating-default-after-thank-you are called before and after ‘Thank you’ message. With filter gdrts-template-thumbs-rating-default-thank-you-message, you can modify the ‘Thank you’ message.

As for the ‘Please wait’ message, you have a filter gdrts-template-thumbs-rating-default-show-please-wait to decide if the ‘Please wait’ will be displayed or not (default: true). Actions gdrts-template-thumbs-rating-default-before-please-wait and gdrts-template-thumbs-rating-default-after-please-wait are run around the ‘Please wait’ message. And, the message is displayed using the method call: gdrts_loop()->please_wait().

In the end, lines with the method call gdrts_loop()->json() and actions that follow are required in all single block templates.

Other templates

The plugin includes more than just the Default template. But, these templates are simpler, they don’t have all the extra filters and actions Default template has. If you understand the Default template, you can think of other templates as examples of what else can be done with templates customization, and to help you started with your own templates.

0
0
198
Rate this user guide

You are not allowed to rate this post.

Comments

Leave a Reply