A reusable Django app that lets users write reviews for any model
Project description
Django Review
============
A reusable Django app that lets users write reviews for any model
Installation
------------
To get the latest stable release from PyPi
.. code-block:: bash
$ pip install django-review
To get the latest commit from GitHub
.. code-block:: bash
$ pip install -e git+git://github.com/bitmazk/django-review.git#egg=review
TODO: Describe further installation steps (edit / remove the examples below):
Add ``review`` to your ``INSTALLED_APPS``
.. code-block:: python
INSTALLED_APPS = (
...,
'review',
'user_media',
'generic_positions',
)
Add the ``review`` URLs to your ``urls.py``
.. code-block:: python
urlpatterns = patterns('',
...
url(r'^review/', include('review.urls')),
)
Don't forget to migrate your database
.. code-block:: bash
./manage.py migrate review
Usage
-----
The only step you'll have to take is to link to the review views. For example,
you created a ``Book`` model, which should be reviewed by users.
Create a button and add some markup like:
.. code-block:: html
<a href="{% url "review_create" content_type='book' object_id=book.pk %}">{% trans "Review this book" %}</a>
Template tags
-------------
total_review_average
++++++++++++++++++++
For rendering the total review average for any object, you can use the
assignment tag ``total_review_average``. It automatically calculates the
averages of all reviews for the given object and you can specify what range it
should have. The following examples would resemble a percentage or a stars
rating:
.. code-block:: html
{% load review_tags %}
{% total_review_average object 100 as percentage %}
<p>{{ percentage }}% of our users recommended this!</p>
{% total_review_average object 5 as stars %}
<p>This object got {{ stars }} out of 5 stars.</p>
render_category_averages
++++++++++++++++++++++++
Renders the template ``review/partials/category_averages.html`` to display a
table of categories with their average rating.
Again, you can specify what maximum rating value the averages normalize to.
.. code-block:: html
{% load review_tags %}
{% render_category_averages object 100 %}
If you had 2 categories, this would per default render to something like the
following example, but you can of course customize the template to your needs.
.. code-block:: html
<table>
<tr><th>Category 1:</th><td>10.0</td></tr>
<tr><th>Category 2:</th><td>20.0</td></tr>
<tr><th>Amount of reviews:</th><td>2</td></tr>
</table>
get_reviews
+++++++++++
An assignment tag, that simply returns the reviews made for the given object.
An example usage would look like this:
.. code-block:: html
{% load review_tags %}
{% get_reviews object as reviews %}
{% for review in reviews %}
<p>
{{ review.get_average_rating }}
</p>
<p>
{% if review.content %}
{{ review.content|truncatewords:'70' }}
{% else %}
Reviewed without description.
{% endif %}
</div>
<a href="{% url "review_detail" pk=object.pk %}">Review details</a>
{% endfor %}
get_review_average
++++++++++++++++++
An assignment tag, that returns the review average for the given object. An
example usage would look like this:
.. code-block:: html
{% load review_tags %}
{% get_review_average object as review_average %}
<p>This object is rated by {{ review_average }}</p>
get_review_count
++++++++++++++++
An assignment tag, that simply returns the amount of reviews made for the
given object. An example usage would look like this:
.. code-block:: html
{% load review_tags %}
{% get_review_count object as review_count %}
<p>{{ review_count }} users have reviewed this so far.</p>
user_has_reviewed
+++++++++++++++++
To quickly check if a user has already reviewed the given object, you can use
this template tag. An example usage could be something like this:
.. code-block:: html
{% load review_tags %}
{% user_has_reviewed myobject request.user as has_reviewed %}
{% if has_reviewed %}
<p>Thanks for your opinion!</p>
{% else %}
<a href="{% url "review_create" content_type='book' object_id=book.pk %}">{% trans "Review this book" %}</a>
{% endif %}
Settings
--------
Default behaviour:
* Users can rate form 0 to 5
* Only authenticated users can post a review
* Users can post multiple reviews on one object
* Users can always update their posted reviews
If you want to change this behaviour, or if you like to add some more
permission checks, read on.
REVIEW_RATING_CHOICES
+++++++++++++++++++++
If you want other rating choices than 0-5, you can define a new tuple, like:
.. code-block:: python
REVIEW_RATING_CHOICES = (
('1', 'bad'),
('2', 'average'),
('3', 'excellent'),
)
REVIEW_ALLOW_ANONYMOUS
++++++++++++++++++++++
Allows anonymous review postings, if set to ``True``.
REVIEW_DELETION_SUCCESS_URL
+++++++++++++++++++++++++++
Name of the URL to redirect to after deleting a review instance. This could
be your review listing, for example.
REVIEW_UPDATE_SUCCESS_URL (optional)
++++++++++++++++++++++++++++++++++++
Default: DetailView of the instance.
Name of the URL to redirect to after creating/updating a review instance.
This could be your review listing, for example.
.. code-block:: python
REVIEW_UPDATE_SUCCESS_URL = 'my_view_name'
Or you can also specify a function, that returns the full path. The function
then takes the review as parameter, so you can also access the reviewed item
like follows
.. code-block:: python
REVIEW_UPDATE_SUCCESS_URL = lambda review: review.reviewed_item.get_absolute_url()
REVIEW_AVOID_MULTIPLE_REVIEWS
+++++++++++++++++++++++++++++
Avoids multiple reviews by one user, if set to ``True``.
Doesn't work with anonymous users.
REVIEW_PERMISSION_FUNCTION
++++++++++++++++++++++++++
Custom function to check the user's permission. Use a function and note that
the user and the reviewed item are only parameters.
.. code-block:: python
REVIEW_PERMISSION_FUNCTION = lambda u, item: u.get_profile().has_permission(item)
REVIEW_UPDATE_PERIOD
++++++++++++++++++++
You can limit the period, in which a user is able to update old reviews.
Make sure to use minutes, e.g. 2880 for 48 hours.
REVIEW_CUSTOM_FORM
++++++++++++++++++
You can create your own review form (e.g. if you want to make use of the review
extra info). Just name it.
.. code-block:: python
REVIEW_CUSTOM_FORM = 'myapp.forms.MyCustomReviewForm'
Take a look at the included test app to get an example.
You can also use a custom form to add another content object to the review
instance.
REVIEW_FORM_CHOICE_WIDGET
+++++++++++++++++++++++++
If you only want to override Django's default widget for the used
``ChoiceField``, that is used in the form, you can specify this optional
setting.
.. code-block:: python
# this would use a RadioSelect instead of the default Select
REVIEW_FORM_CHOICE_WIDGET = 'django.forms.widgets.RadioSelect'
Contribute
----------
If you want to contribute to this project, please perform the following steps
.. code-block:: bash
# Fork this repository
# Clone your fork
$ mkvirtualenv -p python2.7 django-review
$ python setup.py install
$ pip install -r dev_requirements.txt
$ git co -b feature_branch master
# Implement your feature and tests
$ git add . && git commit
$ git push -u origin feature_branch
# Send us a pull request for your feature branch
============
A reusable Django app that lets users write reviews for any model
Installation
------------
To get the latest stable release from PyPi
.. code-block:: bash
$ pip install django-review
To get the latest commit from GitHub
.. code-block:: bash
$ pip install -e git+git://github.com/bitmazk/django-review.git#egg=review
TODO: Describe further installation steps (edit / remove the examples below):
Add ``review`` to your ``INSTALLED_APPS``
.. code-block:: python
INSTALLED_APPS = (
...,
'review',
'user_media',
'generic_positions',
)
Add the ``review`` URLs to your ``urls.py``
.. code-block:: python
urlpatterns = patterns('',
...
url(r'^review/', include('review.urls')),
)
Don't forget to migrate your database
.. code-block:: bash
./manage.py migrate review
Usage
-----
The only step you'll have to take is to link to the review views. For example,
you created a ``Book`` model, which should be reviewed by users.
Create a button and add some markup like:
.. code-block:: html
<a href="{% url "review_create" content_type='book' object_id=book.pk %}">{% trans "Review this book" %}</a>
Template tags
-------------
total_review_average
++++++++++++++++++++
For rendering the total review average for any object, you can use the
assignment tag ``total_review_average``. It automatically calculates the
averages of all reviews for the given object and you can specify what range it
should have. The following examples would resemble a percentage or a stars
rating:
.. code-block:: html
{% load review_tags %}
{% total_review_average object 100 as percentage %}
<p>{{ percentage }}% of our users recommended this!</p>
{% total_review_average object 5 as stars %}
<p>This object got {{ stars }} out of 5 stars.</p>
render_category_averages
++++++++++++++++++++++++
Renders the template ``review/partials/category_averages.html`` to display a
table of categories with their average rating.
Again, you can specify what maximum rating value the averages normalize to.
.. code-block:: html
{% load review_tags %}
{% render_category_averages object 100 %}
If you had 2 categories, this would per default render to something like the
following example, but you can of course customize the template to your needs.
.. code-block:: html
<table>
<tr><th>Category 1:</th><td>10.0</td></tr>
<tr><th>Category 2:</th><td>20.0</td></tr>
<tr><th>Amount of reviews:</th><td>2</td></tr>
</table>
get_reviews
+++++++++++
An assignment tag, that simply returns the reviews made for the given object.
An example usage would look like this:
.. code-block:: html
{% load review_tags %}
{% get_reviews object as reviews %}
{% for review in reviews %}
<p>
{{ review.get_average_rating }}
</p>
<p>
{% if review.content %}
{{ review.content|truncatewords:'70' }}
{% else %}
Reviewed without description.
{% endif %}
</div>
<a href="{% url "review_detail" pk=object.pk %}">Review details</a>
{% endfor %}
get_review_average
++++++++++++++++++
An assignment tag, that returns the review average for the given object. An
example usage would look like this:
.. code-block:: html
{% load review_tags %}
{% get_review_average object as review_average %}
<p>This object is rated by {{ review_average }}</p>
get_review_count
++++++++++++++++
An assignment tag, that simply returns the amount of reviews made for the
given object. An example usage would look like this:
.. code-block:: html
{% load review_tags %}
{% get_review_count object as review_count %}
<p>{{ review_count }} users have reviewed this so far.</p>
user_has_reviewed
+++++++++++++++++
To quickly check if a user has already reviewed the given object, you can use
this template tag. An example usage could be something like this:
.. code-block:: html
{% load review_tags %}
{% user_has_reviewed myobject request.user as has_reviewed %}
{% if has_reviewed %}
<p>Thanks for your opinion!</p>
{% else %}
<a href="{% url "review_create" content_type='book' object_id=book.pk %}">{% trans "Review this book" %}</a>
{% endif %}
Settings
--------
Default behaviour:
* Users can rate form 0 to 5
* Only authenticated users can post a review
* Users can post multiple reviews on one object
* Users can always update their posted reviews
If you want to change this behaviour, or if you like to add some more
permission checks, read on.
REVIEW_RATING_CHOICES
+++++++++++++++++++++
If you want other rating choices than 0-5, you can define a new tuple, like:
.. code-block:: python
REVIEW_RATING_CHOICES = (
('1', 'bad'),
('2', 'average'),
('3', 'excellent'),
)
REVIEW_ALLOW_ANONYMOUS
++++++++++++++++++++++
Allows anonymous review postings, if set to ``True``.
REVIEW_DELETION_SUCCESS_URL
+++++++++++++++++++++++++++
Name of the URL to redirect to after deleting a review instance. This could
be your review listing, for example.
REVIEW_UPDATE_SUCCESS_URL (optional)
++++++++++++++++++++++++++++++++++++
Default: DetailView of the instance.
Name of the URL to redirect to after creating/updating a review instance.
This could be your review listing, for example.
.. code-block:: python
REVIEW_UPDATE_SUCCESS_URL = 'my_view_name'
Or you can also specify a function, that returns the full path. The function
then takes the review as parameter, so you can also access the reviewed item
like follows
.. code-block:: python
REVIEW_UPDATE_SUCCESS_URL = lambda review: review.reviewed_item.get_absolute_url()
REVIEW_AVOID_MULTIPLE_REVIEWS
+++++++++++++++++++++++++++++
Avoids multiple reviews by one user, if set to ``True``.
Doesn't work with anonymous users.
REVIEW_PERMISSION_FUNCTION
++++++++++++++++++++++++++
Custom function to check the user's permission. Use a function and note that
the user and the reviewed item are only parameters.
.. code-block:: python
REVIEW_PERMISSION_FUNCTION = lambda u, item: u.get_profile().has_permission(item)
REVIEW_UPDATE_PERIOD
++++++++++++++++++++
You can limit the period, in which a user is able to update old reviews.
Make sure to use minutes, e.g. 2880 for 48 hours.
REVIEW_CUSTOM_FORM
++++++++++++++++++
You can create your own review form (e.g. if you want to make use of the review
extra info). Just name it.
.. code-block:: python
REVIEW_CUSTOM_FORM = 'myapp.forms.MyCustomReviewForm'
Take a look at the included test app to get an example.
You can also use a custom form to add another content object to the review
instance.
REVIEW_FORM_CHOICE_WIDGET
+++++++++++++++++++++++++
If you only want to override Django's default widget for the used
``ChoiceField``, that is used in the form, you can specify this optional
setting.
.. code-block:: python
# this would use a RadioSelect instead of the default Select
REVIEW_FORM_CHOICE_WIDGET = 'django.forms.widgets.RadioSelect'
Contribute
----------
If you want to contribute to this project, please perform the following steps
.. code-block:: bash
# Fork this repository
# Clone your fork
$ mkvirtualenv -p python2.7 django-review
$ python setup.py install
$ pip install -r dev_requirements.txt
$ git co -b feature_branch master
# Implement your feature and tests
$ git add . && git commit
$ git push -u origin feature_branch
# Send us a pull request for your feature branch
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-review-1.9.2.tar.gz
(25.1 kB
view hashes)