Pinax Ratings

About Pinax
Important Links
Overview
- Supported Django and Python Versions
Documentation
- Installation
- Usage
- Settings
- Templates
Change Log
Contribute
Code of Conduct
Connect with Pinax
License

About Pinax

Pinax is an open-source platform built on the Django Web Framework. It is an ecosystem of reusable Django apps, themes, and starter project templates. This collection can be found at http://pinaxproject.com.

Important Links

Where you can find what you need:

Releases: published to PyPI or tagged in app repos in the Pinax GitHub organization
Global documentation: Pinax documentation website
App specific documentation: app repos in the Pinax GitHub organization
Support information: SUPPORT.md file in the Pinax default community health file repo
Contributing information: CONTRIBUTING.md file in the Pinax default community health file repo
Current and historical release docs: Pinax Wiki

pinax-ratings

Overview

pinax-ratings is a ratings app for Django.

Supported Django and Python Versions

Django / Python	3.6	3.7	3.8
2.2	*	*	*
3.0	*	*	*

Documentation

Installation

To install pinax-ratings:

    $ pip install pinax-ratings

Add pinax.ratings to your INSTALLED_APPS setting:

    INSTALLED_APPS = [
        # other apps
        "pinax.ratings",
    ]

Add pinax.ratings.urls to your project urlpatterns:

    urlpatterns = [
        # other urls
        url(r"^ratings/", include("pinax.ratings.urls", namespace="pinax_ratings")),
    ]

Finally, view the list of settings to modify pinax-ratings's default behavior and make adjustments for your website.

Optionally, if want to use the ratings category feature of pinax-ratings then you will need to add the pinax-RATINGS_CATEGORY_CHOICES setting in your settings.py:

    PINAX_RATINGS_CATEGORY_CHOICES = {
        "app.Model": {
            "exposure": "How good is the exposure?",
            "framing": "How well was the photo framed?",
            "saturation": "How would you rate the saturation?"
        },
        "app.Model2": {
            "grammar": "Good grammar?",
            "complete": "Is the story complete?",
            "compelling": "Is the article compelling?"
        }
    }

Usage

Integrating pinax-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.

First add load the template tags for pinax-ratings:

    {% load pinax_ratings_tags %}

Then pick a template tag for display or obtaining rating data.

Template Tags

overall_rating

Display an overall rating average for an object:

    {% overall_rating obj as the_overall_rating %}

    <div class="overall_rating">{{ the_overall_rating }}</div>

Display overall rating average for a specific category for an object:

    {% overall_rating obj "accuracy" as category_rating %}

    <div class="overall_rating category-accuracy">
        {{ category_rating }}
    </div>

user_rating

Display a specific user's rating:

    {% user_rating request.user obj as the_user_rating %}

    <div class="user_rating">{{ the_user_rating }}</div>

Display specific user rating for a specific category for an object:

    {% user_rating request.user obj "accuracy" as category_rating %}

    <div class="user_rating category-accuracy">
        {{ category_rating }}
    </div>

user_rating_js

If you want to add an AJAX form for allowing a user to set a rating, add the following in the appropriate location on your page:

    <div id="user_rating"></div>

And then add this near the end of your HTML <body> to emit some Javascript libraries and hook up the ratings UI:

    {% user_rating_js request.user obj %}

Hook up the ratings UI for a specific category:

    <div id="user_rating" class="category-accuracy"></div>

    {% user_rating_js request.user obj "accuracy" %}

ratings

Returns all Ratings for an object type, regardless of category:

    {% ratings obj as the_ratings %}
    {% for rating in the_ratings %}
        Rating: {{ rating.rating }}
    {% endfor %}

user_rating_url

Returns a URL for user to post a rating for an object:

    {% user_rating_url request.user obj as rating_url %}
    {{ rating_url }}

rating_count

Returns the number of ratings for an object type:

    {% rating_count obj as count %}
    {{ obj }} has {{ count }} ratings

Settings

PINAX_RATINGS_NUM_OF_RATINGS

Default: 5

Defines the number of different rating choices there will be.

PINAX_RATINGS_CATEGORY_CHOICES

Default: None

Defines a dictionary of rating category choices for application models. Each model specified has a dictionary of rating categories, with associated rating prompt string. Only rating categories associated with a model in this setting are allowed.

    PINAX_RATINGS_CATEGORY_CHOICES = {
        "app.Photo": {
            "exposure": "How good is the exposure?",
            "framing": "How well was the photo framed?",
            "saturation": "How would you rate the saturation?"
        },
        "app.Story": {
            "grammar": "Good grammar?",
            "complete": "Is the story complete?",
            "compelling": "Is the article compelling?"
        }
    }

Templates

pinax-ratings comes with two minimal template snippets rendered by template tags for displaying the rating form.

Templates are found in "pinax/ratings/" subdirectory for your project.

`_rating.html`

`_script.html`

This is a snippet that renders the bundled Javascript and a simple AJAX posting and hooking up of a rating UI. This is optional and overridable by the site developer.

Change Log

4.0.0

Drop Django 1.11, 2.0, and 2.1, and Python 2,7, 3.4, and 3.5 support
Add Django 2.2 and 3.0, and Python 3.6, 3.7, and 3.8 support
Update packaging configs
Direct users to community resources

3.0.3

Improve test clarity and coverage
Improve documentation

3.0.2

Add templatetag tests, model tests

3.0.1

Import reverse from django.urls

3.0.0

Add Django 2.0 compatibility testing
Drop Django 1.8, 1.9, 1.10, and Python 3.3 support
Add URL namespacing (BI: urlname "pinax_ratings_rate" is now "pinax_ratings:rate")
Move documentation into README and standardize layout
Convert CI and coverage to CircleCi and CodeCov
Add PyPi-compatible long description

2.0.0

converted category on ratings.Rating and ratings.OverallRating models to be a CharField that is the actual category label rather than a runtime generated ID. upgrading will require you manually update the database values

1.0.0

@@@ write change log

0.3

renamed from agon_ratings to pinax-ratings

0.2.1

added ability in overall_rating template tag to omit the category label and get an average rating without concern for category averages.
added ability to get average rating over all categories for a particular user and particular object.

0.2

added support for ratings to have categories instead of just a single rating for an object
dropped natural language of template tags

Migrations

Added a category model and updated the unique index on both models:

ALTER TABLE "agon_ratings_overallrating" ADD COLUMN "category" int;
ALTER TABLE "agon_ratings_rating" ADD COLUMN "category" int;
CREATE UNIQUE INDEX "agon_ratings_overallrating_unq_object_id_content_type_id_category_idx"
    ON "agon_ratings_overallrating" (object_id, content_type_id, category);
CREATE UNIQUE INDEX "agon_ratings_rating_unq_object_id_content_type_id_user_id_category_idx"
    ON "agon_ratings_rating" (object_id, content_type_id, user_id, category);
ALTER TABLE "agon_ratings_rating" DROP CONSTRAINT
    IF EXISTS "agon_ratings_rating_object_id_content_type_id_user_id_key";
ALTER TABLE "agon_ratings_overallrating" DROP CONSTRAINT
    IF EXISTS "agon_ratings_overallrating_object_id_content_type_id_key";

0.1.2

added a tag, user_rating_url, for getting the POST url for posting a rating
changed user_rate_form and documented javascript wiring to a single user_rating_js inclusion tag that output all the javascript and removed the need for a form.

0.1

initial release

Contribute

Contributing information can be found in the Pinax community health file repo.

Code of Conduct

In order to foster a kind, inclusive, and harassment-free community, the Pinax Project has a Code of Conduct. We ask you to treat everyone as a smart human programmer that shares an interest in Python, Django, and Pinax with you.