A Django app to add star ratings to models.
Project description
django-star-ratings
===================
|Build Status| |codecov.io| |Documentation Status|
Python 3 compatible ratings for Django.
Add ratings to any Django model with a template tag.
See full `documentation
<http://django-star-ratings.readthedocs.io/en/latest/?badge=latest/>`_.
Installation
------------
Install from PyPI:
::
pip install django-star-ratings
add ``star_ratings`` to ``INSTALLED_APPS``:
::
INSTALLED_APPS = (
...
'star_ratings'
)
sync your database:
::
python manage.py migrate
add the following to your urls.py:
::
url(r'^ratings/', include('star_ratings.urls', namespace='ratings', app_name='ratings')),
Make sure ``'django.core.context_processors.request',`` is in
``TEMPLATE_CONTEXT_PROCESSORS``.
Usage
-----
Add the following javascript and stylesheet to your template
::
{% load static %}
<html>
...
<link rel="stylesheet" href="{% static 'star-ratings/css/star-ratings.css' %}">
<script type="text/javascript" src="{% static 'star-ratings/js/dist/star-ratings.min.js' %}"></script>
...
</html>
To enable ratings for a model add the following tag in your template
::
{% load ratings %}
<html>
...
{% ratings object %}
...
</html>
Template tags
-------------
The template tag takes two arguments:
- ``icon_height``: defaults to ``STAR_RATINGS_STAR_HEIGHT``
- ``icon_width``: defaults to ``STAR_RATINGS_STAR_WIDTH``
- ``read_only``: overrides the ``editable`` behaviour to make the widget read only
Settings
--------
To prohibit users from altering their ratings set
``STAR_RATINGS_RERATE = False`` in settings.py
To change the number of rating stars, set ``STAR_RATINGS_RANGE``
(defaults to 5)
To enable anonymous rating set ``STAR_RATINGS_ANONYMOUS = True``.
Anonymous Rating
----------------
If anonymous rating is enabled only the ip address for the rater will be stored (even if the user is logged in).
When a user rates an object a preexisting object will not be searched for, instead a new rating object will be created
**If this value is changed your lookups will return different results!**
To control the default size of stars in pixels set the values of ``STAR_RATINGS_STAR_HEIGHT`` and
``STAR_RATINGS_STAR_WIDTH``. By default ``STAR_RATINGS_STAR_WIDTH`` is the same as
``STAR_RATINGS_STAR_HEIGHT`` and ``STAR_RATINGS_STAR_HEIGHT`` defaults to 32.
Changing the star graphics
--------------------------
To change the star graphic, add a sprite sheet to
``/static/star-ratings/images/stars.png`` with the states aligned
horizontally. The stars should be laid out in three states: full, empty
and active.
You can also set ``STAR_RATINGS_STAR_SPRITE`` to the location of your sprite sheet.
Customize widget template
-------------------------
You can customize ratings widget by creating ``star_ratings/widget.html``. For example :
::
{% extends "star_ratings/widget_base.html" %}
{% block rating_detail %}
Whatever you want
{% endblock %}
See ``star_ratings/widget_base.html`` for other blocks to be extended.
Ordering by ratings
-------------------
The easiest way to order by ratings is to add a ``GenericRelation`` to
the ``Rating`` model from your model:
::
from django.contrib.contenttypes.fields import GenericRelation
from star_ratings.models import Rating
class Foo(models.Model):
bar = models.CharField(max_length=100)
ratings = GenericRelation(Rating, related_query_name='foos')
Foo.objects.filter(ratings__isnull=False).order_by('ratings__average')
Running tests
-------------
To run the test use:
::
$> ./runtests.py
.. |Build Status| image:: https://travis-ci.org/wildfish/django-star-ratings.svg?branch=master
:target: https://travis-ci.org/wildfish/django-star-ratings
.. |codecov.io| image:: http://codecov.io/github/wildfish/django-star-ratings/coverage.svg?branch=master
:target: http://codecov.io/github/wildfish/django-star-ratings?branch=master
.. |Documentation Status| image:: https://readthedocs.org/projects/django-star-ratings/badge/?version=latest
:target: http://django-star-ratings.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. |Docs| :target: https://django-configurations.readthedocs.io/en/latest/
Releasing
---------
Travis is setup to push releases to pypi automatically on tags, to do a release:
1. Up version number.
2. Update release notes.
3. Push dev.
4. Merge develop into master.
5. Tag with new version number.
6. Push tags.
===================
|Build Status| |codecov.io| |Documentation Status|
Python 3 compatible ratings for Django.
Add ratings to any Django model with a template tag.
See full `documentation
<http://django-star-ratings.readthedocs.io/en/latest/?badge=latest/>`_.
Installation
------------
Install from PyPI:
::
pip install django-star-ratings
add ``star_ratings`` to ``INSTALLED_APPS``:
::
INSTALLED_APPS = (
...
'star_ratings'
)
sync your database:
::
python manage.py migrate
add the following to your urls.py:
::
url(r'^ratings/', include('star_ratings.urls', namespace='ratings', app_name='ratings')),
Make sure ``'django.core.context_processors.request',`` is in
``TEMPLATE_CONTEXT_PROCESSORS``.
Usage
-----
Add the following javascript and stylesheet to your template
::
{% load static %}
<html>
...
<link rel="stylesheet" href="{% static 'star-ratings/css/star-ratings.css' %}">
<script type="text/javascript" src="{% static 'star-ratings/js/dist/star-ratings.min.js' %}"></script>
...
</html>
To enable ratings for a model add the following tag in your template
::
{% load ratings %}
<html>
...
{% ratings object %}
...
</html>
Template tags
-------------
The template tag takes two arguments:
- ``icon_height``: defaults to ``STAR_RATINGS_STAR_HEIGHT``
- ``icon_width``: defaults to ``STAR_RATINGS_STAR_WIDTH``
- ``read_only``: overrides the ``editable`` behaviour to make the widget read only
Settings
--------
To prohibit users from altering their ratings set
``STAR_RATINGS_RERATE = False`` in settings.py
To change the number of rating stars, set ``STAR_RATINGS_RANGE``
(defaults to 5)
To enable anonymous rating set ``STAR_RATINGS_ANONYMOUS = True``.
Anonymous Rating
----------------
If anonymous rating is enabled only the ip address for the rater will be stored (even if the user is logged in).
When a user rates an object a preexisting object will not be searched for, instead a new rating object will be created
**If this value is changed your lookups will return different results!**
To control the default size of stars in pixels set the values of ``STAR_RATINGS_STAR_HEIGHT`` and
``STAR_RATINGS_STAR_WIDTH``. By default ``STAR_RATINGS_STAR_WIDTH`` is the same as
``STAR_RATINGS_STAR_HEIGHT`` and ``STAR_RATINGS_STAR_HEIGHT`` defaults to 32.
Changing the star graphics
--------------------------
To change the star graphic, add a sprite sheet to
``/static/star-ratings/images/stars.png`` with the states aligned
horizontally. The stars should be laid out in three states: full, empty
and active.
You can also set ``STAR_RATINGS_STAR_SPRITE`` to the location of your sprite sheet.
Customize widget template
-------------------------
You can customize ratings widget by creating ``star_ratings/widget.html``. For example :
::
{% extends "star_ratings/widget_base.html" %}
{% block rating_detail %}
Whatever you want
{% endblock %}
See ``star_ratings/widget_base.html`` for other blocks to be extended.
Ordering by ratings
-------------------
The easiest way to order by ratings is to add a ``GenericRelation`` to
the ``Rating`` model from your model:
::
from django.contrib.contenttypes.fields import GenericRelation
from star_ratings.models import Rating
class Foo(models.Model):
bar = models.CharField(max_length=100)
ratings = GenericRelation(Rating, related_query_name='foos')
Foo.objects.filter(ratings__isnull=False).order_by('ratings__average')
Running tests
-------------
To run the test use:
::
$> ./runtests.py
.. |Build Status| image:: https://travis-ci.org/wildfish/django-star-ratings.svg?branch=master
:target: https://travis-ci.org/wildfish/django-star-ratings
.. |codecov.io| image:: http://codecov.io/github/wildfish/django-star-ratings/coverage.svg?branch=master
:target: http://codecov.io/github/wildfish/django-star-ratings?branch=master
.. |Documentation Status| image:: https://readthedocs.org/projects/django-star-ratings/badge/?version=latest
:target: http://django-star-ratings.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. |Docs| :target: https://django-configurations.readthedocs.io/en/latest/
Releasing
---------
Travis is setup to push releases to pypi automatically on tags, to do a release:
1. Up version number.
2. Update release notes.
3. Push dev.
4. Merge develop into master.
5. Tag with new version number.
6. Push tags.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
django-star-ratings-0.5.6.tar.gz
(29.6 kB
view hashes)
Close
Hashes for django-star-ratings-0.5.6.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | e6423cc5ef24a0f7e81b91f47e504d2e568eacdedd84aba7be8de1f1a2cedef2 |
|
MD5 | f9121c2777cdc637acf4d030f361d7d7 |
|
BLAKE2b-256 | cb00e62ce4719e26801fde563393c91e405c6263a46a6f6504043b96c65a9714 |