search

pinax / pinax-ratings

a ratings app for Django
MIT License
89 stars 28 forks source link

readme

Pinax Ratings

CircleCi Codecov

Table of Contents

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:

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

3.0.3

3.0.2

3.0.1

3.0.0

2.0.0

1.0.0

0.3

0.2.1

0.2

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

0.1

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.

Connect with Pinax

For updates and news regarding the Pinax Project, please follow us on Twitter @pinaxproject and check out our Pinax Project blog.

License

Copyright (c) 2012-present James Tauber and contributors under the MIT license.