<commit_before>.. _usage:

Usage
=====

Integrating `agon_ratings` into your project is just a matter of using a couple of
template tags and wiring up a bit of javascript. The rating form is intended
to function via AJAX and as such returns JSON.

Firstly, you will want to add the following blocks in your templates where
you want to expose the rating form::

    {% load agon_ratings_tags %}
    
    <div class="rating">
        {% user_rate_form some_object %}
        
        <div class="user_rating">
            {% user_rating for request.user and some_object as the_user_rating %}
            <span class="rating-{{ the_user_rating }}">{{ the_user_rating }}</span>
        </div>
        
        <div class="overall_rating">
            {% overall_rating for some_object as the_overall_rating %}
            <span class="rating-{{ the_overall_rating }}">{{ the_overall_rating }}</span>
        </div>
    </div>


And then a bit of jQuery (this assumes use of the jquery.form plugin)::

    $('.rating form').ajaxForm(function(data) {
        var user_r = parseInt(data["user_rating"]);
        var over_r = parseFloat(data["overall_rating"]);
        var over_class = parseInt(over_r * 10);
        var user_class = user_r * 10;
        $(".rating .user_rating span").attr("class", "rating-" + user_class).text(user_r);
        $(".rating .overall_rating span").attr("class", "rating-" + over_class).text(over_r);
    });


Wiring up the interface is up to you the site developer. One approach that seems to
work nicely is integrating with _raty:Raty: like so::

    <div id="user_rating"></div>
    <div id="overall_rating"></div>
    
    <script type="text/javascript" src="jquery.raty.min.js" />
    <script type="text/javascript">
        $("#user_rating").raty({
            start = {{ the_user_rating }},
            click = function(score, evt) {
                $(".rating form input[name]").val(score);
                $(".rating form").submit();
            },
            cancel = true
        })
    </script>


_raty:Raty: http://www.wbotelhos.com/raty/<commit_msg>Update docs for better js example<commit_after>.. _usage:

Usage
=====

Integrating `agon_ratings` into your project is just a matter of using a couple of
template tags and wiring up a bit of javascript. The rating form is intended
to function via AJAX and as such returns JSON.

Firstly, you will want to add the following blocks in your templates where
you want to expose the rating form::

    {% load agon_ratings_tags %}
    
    <div class="rating">
        {% user_rate_form some_object %}
        <div id="user_rating"></div>
        <div class="overall_rating">
            {% overall_rating for some_object as the_overall_rating %}
            <span class="rating-{{ the_overall_rating }}">{{ the_overall_rating }}</span>
        </div>
    </div>


Wiring up the interface is up to you the site developer. One approach that seems to
work nicely is integrating with _raty:Raty: like so::

    <script type="text/javascript" src="{{ STATIC_URL }}js/jquery.raty.js"></script>
    <script type="text/javascript">
        {% user_rating for request.user and post as the_user_rating %}
        $(function () {
            $('.rating form').ajaxForm(function(data) {
                var over_r = parseFloat(data["overall_rating"]);
                var over_class = parseInt(over_r * 10);
                $(".rating .overall_rating span").attr("class", "rating-" + over_class).text(over_r);
            });
            $("#user_rating").raty({
                start: {{ the_user_rating }},
                click: function(score, evt) {
                    if (score == null) {
                        $(".rating form input[name=rating]").val(0);
                    } else {
                        $(".rating form input[name=rating]").val(score);
                    }
                    $(".rating form").submit();
                },
                cancel: true,
                path: "{{ STATIC_URL }}images/"
            });
        });
        </script>
     </script>


_raty:Raty: http://www.wbotelhos.com/raty/
{'fraction_non_alphanumeric': 0.12958910770726964, 'fraction_numerical': 0.0017019207391198638, 'mean_word_length': 2.3231017770597737, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 33, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4461191', 'n_tokens_mistral': 1221, 'n_tokens_neox': 1160, 'n_words': 349}