Skip to main content

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',
)

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``.


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_CHOICES_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

from django import forms

# this would use a RadioSelect instead of the default Select
REVIEW_FORM_CHOICES_WIDGET = forms.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

History Node

1.10.0

History Node

1.9.7

History Node

1.9.6

History Node

1.9.5

History Node

1.9.4

History Node

1.9.3

History Node

1.9.2

History Node

1.9.1

History Node

1.9

This version
History Node

1.8.1

History Node

1.8

History Node

1.7.4

History Node

1.7.3

History Node

1.7.2

History Node

1.7.1

History Node

1.7

History Node

1.6

History Node

1.5

History Node

1.4

History Node

1.3

History Node

1.2.1

History Node

1.2

History Node

1.1

History Node

1.0

History Node

0.4

History Node

0.3

History Node

0.2.1

History Node

0.2

History Node

0.1.1

History Node

0.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
django-review-1.8.1.tar.gz (24.5 kB) Copy SHA256 hash SHA256 Source None May 30, 2014

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page