Generic voting application for Django
Project description
A generic voting application for Django projects, which allows registering of votes for any Model instance.
Installation
Install the django-voting distribution
Add voting to your INSTALLED_APPS:
INSTALLED_APPS = [ … 'voting', … ]Run django-admin migrate
Usage
Votes
Votes are represented by the Vote model, which lives in the voting.models module.
Votes are recorded using the record_vote helper function:
>>> from django.contrib.auth.models import User >>> from shop.apps.products.models import Widget >>> from voting.models import Vote >>> user = User.objects.get(pk=1) >>> widget = Widget.objects.get(pk=1) >>> Vote.objects.record_vote(widget, user, +1)
The score for an object can be retrieved using the get_score helper function:
>>> Vote.objects.get_score(widget)
{'score': 1, 'num_votes': 1}
If the same user makes another vote on the same object, their vote is either modified or deleted, as appropriate:
>>> Vote.objects.record_vote(widget, user, -1)
>>> Vote.objects.get_score(widget)
{'score': -1, 'num_votes': 1}
>>> Vote.objects.record_vote(widget, user, 0)
>>> Vote.objects.get_score(widget)
{'score': 0, 'num_votes': 0}
Fields
Vote objects have the following fields:
user – The user who made the vote. Users are represented by the django.contrib.auth.models.User model.
content_type – The ContentType of the object voted on.
object_id – The id of the object voted on.
object – The object voted on.
vote – The vote which was made: +1 or -1.
Methods
Vote objects have the following custom methods:
is_upvote – Returns True if vote is +1.
is_downvote – Returns True if vote is -1.
Manager functions
The Vote model has a custom manager that has the following helper functions:
record_vote(obj, user, vote) – Record a user’s vote on a given object. Only allows a given user to vote once on any given object, but the vote may be changed.
vote must be one of 1 (up vote), -1 (down vote) or 0 (remove vote).
get_score(obj) – Gets the total score for obj and the total number of votes it’s received.
Returns a dictionary with score and num_votes keys.
get_scores_in_bulk(objects) – Gets score and vote count details for all the given objects. Score details consist of a dictionary which has score and num_vote keys.
Returns a dictionary mapping object ids to score details.
get_top(Model, limit=10, reversed=False) – Gets the top limit scored objects for a given model.
If reversed is True, the bottom limit scored objects are retrieved instead.
Yields (object, score) tuples.
get_bottom(Model, limit=10) – A convenience method which calls get_top with reversed=True.
Gets the bottom (i.e. most negative) limit scored objects for a given model.
Yields (object, score) tuples.
get_for_user(obj, user) – Gets the vote made on the given object by the given user, or None if no matching vote exists.
get_for_user_in_bulk(objects, user) – Gets the votes made on all the given objects by the given user.
Returns a dictionary mapping object ids to votes.
get_voted_users(object) – Gets all users voted on the given object.
Returns a list of objects contains user ids.
Generic Views
The voting.views module contains views to handle a couple of common cases: displaying a page to confirm a vote when it is requested via GET and making the vote itself via POST, or voting via XMLHttpRequest POST.
The following sample URLconf demonstrates using a generic view for voting on a model, allowing for regular voting and XMLHttpRequest voting at the same URL:
from django.urls import re_path
from voting.views import vote_on_object
from shop.apps.products.models import Widget
widget_kwargs = {
'model': Widget,
'template_object_name': 'widget',
'allow_xmlhttprequest': True,
}
urlpatterns = [
re_path(
r"^widgets/(?P<object_id>\d+)/(?P<direction>up|down|clear)vote/?$",
vote_on_object,
kwargs=widget_kwargs,
),
]
voting.views.vote_on_object
Description:
A view that displays a confirmation page and votes on an object. The given object will only be voted on if the request method is POST. If this view is fetched via GET, it will display a confirmation page that should contain a form that POSTs to the same URL.
Required arguments:
model: The Django model class of the object that will be voted on.
Either object_id or (slug and slug_field) is required.
If you provide object_id, it should be the value of the primary-key field for the object being voted on.
Otherwise, slug should be the slug of the given object, and slug_field should be the name of the slug field in the QuerySet’s model.
direction: The kind of vote to be made, must be one of 'up', 'down' or 'clear'.
Either a post_vote_redirect argument defining a URL must be supplied, or a next parameter must supply a URL in the request when the vote is POSTed, or the object being voted on must define a get_absolute_url method or property.
The view checks for these in the order given above.
Optional arguments:
allow_xmlhttprequest: A boolean that designates whether this view should also allow votes to be made via XMLHttpRequest.
If this is True, the request headers will be check for an HTTP_X_REQUESTED_WITH header which has a value of XMLHttpRequest. If this header is found, processing of the current request is delegated to voting.views.xmlhttprequest_vote_on_object.
template_name: The full name of a template to use in rendering the page. This lets you override the default template name (see below).
template_loader: The template loader to use when loading the template. By default, it’s django.template.loader.
extra_context: A dictionary of values to add to the template context. By default, this is an empty dictionary. If a value in the dictionary is callable, the generic view will call it just before rendering the template.
context_processors: A list of template-context processors to apply to the view’s template.
template_object_name: Designates the name of the template variable to use in the template context. By default, this is 'object'.
Template name:
If template_name isn’t specified, this view will use the template <app_label>/<model_name>_confirm_vote.html by default.
Template context:
In addition to extra_context, the template’s context will be:
object: The original object that’s about to be voted on. This variable’s name depends on the template_object_name parameter, which is 'object' by default. If template_object_name is 'foo', this variable’s name will be foo.
direction: The argument which was given for the vote’s direction (see above).
voting.views.xmlhttprequest_vote_on_object
Description:
A view for use in voting on objects via XMLHttpRequest. The given object will only be voted on if the request method is POST. This view will respond with JSON text instead of rendering a template or redirecting.
Required arguments:
model: The Django model class of the object that will be voted on.
Either object_id or (slug and slug_field) is required.
If you provide object_id, it should be the value of the primary-key field for the object being voted on.
Otherwise, slug should be the slug of the given object, and slug_field should be the name of the slug field in the QuerySet’s model.
direction: The kind of vote to be made, must be one of 'up', 'down' or 'clear'.
JSON text context:
The context provided by the JSON text returned will be:
success: true if the vote was successfully processed, false otherwise.
score: an object containing a score property, which holds the object’s updated score, and a num_votes property, which holds the total number of votes cast for the object.
error_message: if the vote was not successfully processed, this property will contain an error message.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for django_voting-1.1.0-py3-none-any.whl
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | aed3523167a8b8fea69d5205fa40670e112022ec3aa7c04ef9b6a182e587da96 |
|
| MD5 | 03d3985e7bfc491636b0e61243b69b69 |
|
| BLAKE2b-256 | 6dc46a84de96cfde73afa676247e5748c21e332a8a1f9aba368691b51e82cf55 |
