django-secretballot 0.2.3

django-secretballot<br /><br />Django voting application that allows voting without a logged in user.<br /><br />Provides abstract base model for types that the user wishes to allow voting on as well as related utilities including generic views to ease the addition of 'anonymous' voting to a Django project.<br /><br />django-secretballot is a project of Sunlight Labs (c) 2009. Written by James Turk <jturk@sunlightfoundation.com><br /><br />Source: http://github.com/sunlightlabs/django-secretballot/<br />Requirements<br /><br />python >= 2.4<br /><br />django >= 1.0<br />Usage<br />settings.py<br /><br /> * add secretballot to INSTALLED_APPS<br /> * add a secretballot middleware to MIDDLEWARE_CLASSES (see middleware section for details)<br /><br />Enabling voting for models<br /><br />In order to attach the voting helpers to a particular model it is enough to call secretballot.enable_voting_on passing the model class.<br /><br />For example:<br /><br />from django.db import models<br />import secretballot<br /><br />class Story(models.Model):<br /> title = models.CharField(max_length=100)<br /> description = models.CharField(max_length=200)<br /> timestamp = models.DateTimeField()<br /> ...<br /><br />secretballot.enable_voting_on(Story)<br /><br />Using voting-enabled models<br /><br />Once a model is 'voting-enabled' a number of special fields are available on all instances:<br />Fields<br />votes:<br /> Manager to of all Vote objects related to the current model (typically doesn't need to be accessed directly) (can be renamed by passing votes_name parameter to enable_voting_on)<br />total_upvotes:<br /> Total number of +1 votes (can be renamed by passing upvotes_name parameter to enable_voting_on)<br />total_downvotes:<br /> Total number of -1 votes (can be renamed by passing downvotes_name parameter to enable_voting_on)<br />vote_total:<br /> shortcut accessor for (total_upvotes-total_downvotes) (can be renamed by passing total_name parameter to enable_voting_on)<br />Functions<br />add_vote:<br /> function that takes a token and a vote (+1 or -1) and adds or updates the vote for said token (can be renamed by passing add_vote_name parameter to enable_voting_on)<br />remove_vote:<br /> function that takes a token and removes the vote (if present) for said token (can be renamed by passing remove_vote_name parameter to enable_voting_on)<br />Manager<br /><br />A special manager is added that enables the inclusion of total_upvotes and total_downvotes as well as some extra functionality.<br /><br />This manager by default replaces the objects manager, but this can be altered by passing the manager_name parameter to enable_voting_on.<br /><br />There is also an additional method on the Votable manager:<br />from_request(self, request):<br /> When called on a votable object's queryset will add a user_vote attribute that is the vote cast by the current 'user' (actually the token assigned to the request)<br /><br />For example:<br /><br />def story_view(request, slug):<br /> story = Story.objects.from_request(request).get(pk=slug)<br /> # story has the following extra attributes<br /> # user_vote: -1, 0, or +1<br /> # total_upvotes: total number of +1 votes<br /> # total_downvotes: total number of -1 votes<br /> # vote_total: total_upvotes-total_downvotes<br /> # votes: related object manager to get specific votes (rarely needed)<br /><br />tokens and SecretBallotMiddleware<br /><br />Without user logins it is impossible to be certain that a user does not vote more than once, but there are several methods to limit abuses. secretballot takes a fairly hands-off approach to this problem, the Vote object has a token field that is used to store a uniquely identifying token generated from a request. To limit how many votes come from a particular ip address it is sufficient to set the token to the IP address, but it is also possible to develop more sophisticated heuristics to limit voters.<br /><br />secretballot uses a simple piece of middleware to do this task, and makes it trival for users to define their own middleware that will use whatever heuristic they desire.<br /><br />SecretBallotMiddleware is an abstract class that defines a generate_token(request) method that should return a string to be used for the token.<br /><br />For convinience several middleware have already been defined:<br />SecretBallotIpMiddleware:<br /> simply sets the token to request.META['REMOTE_ADDR'] -- the user's IP address<br />SecretBallotIpUseragentMiddleware:<br /> sets the token to a hash of the user's ip address and user agent -- hopefully slightly more unique than IP alone<br /><br />If you wish to define your own middleware simply derive a class from SecretBallotMiddleware and implement the generate_token method. If you come up with something that may be useful for others contributions are always welcome.<br />Generic Views<br /><br />secretballot.views includes the following generic views:<br /><br />vote(request, content_type, object_id, vote,<br /> redirect_url=None, template_name=None, template_loader=loader,<br /> extra_context=None, context_processors=None, mimetype=None)<br /><br />This view creates or alters a vote on the object of content_type with a primary key of object_id. If a vote already exists it will be replaced (unless vote is 0 in which case it will be deleted).<br /><br />The token attribute of the vote that is used to prevent unlimited voting is set within this view based on the active SecretBallotMiddleware.<br /><br />Depending on the parameters given the return value of this view varies:<br /><br /> 1. if redirect_url is specified it will be used no matter what<br /> 2. if template_name is specified it will be used (along with template_loader, context_processors, etc.)<br /> 3. without redirect_url or template_name a text/json response will be returned<br /><br />content_type:<br /> Class that voting is taking place on (a VotableModel-derived model) May be an instance of django.contrib.contenttypes.models.ContentType, the Model class itself, or an "app.modelname" string.<br />object_id:<br /> primary key of object to vote on<br />vote:<br /> value of this vote (+1, 0, or -1) (0 deletes the vote)<br />can_vote_test:<br /> (optional) function that allows limiting if user can vote or not (see can_vote_test)<br />redirect_url:<br /> (optional) url to redirect to, if present will redirect instead of returning a normal HttpResponse<br />template_name:<br /> (optional) template to render to, recieves a context containing content_obj which is the object voted upon<br />template_loader:<br /> (optional) template loader to use, defaults to django.template.loader<br />extra_context:<br /> (optional) dictionary containing any extra context, callables will be called at render time<br />context_processors:<br /> (optional) list of context processors for this view<br />mimetype:<br /> (optional) mimetype override<br />can_vote_test<br /><br />can_vote_test is an optional argument to the view that can be specified in the urlconf that is called before a vote is recorded for a user<br /><br />Example implementation of can_vote_test:<br /><br />def only_three_votes(request, content_type, object_id, vote):<br /> return Vote.objects.filter(content_type=content_type, token=request.secretballot_token).count() < 3<br /><br />All can_vote_test methods must take the non-optional parameters to secretballot.views.vote and should return True if the vote should be allowed. If the vote is not allowed by default the view will return a 403, but it is also acceptable to raise a different exception.<br /><br />#md5=d83db62753e85116050b8084b01eb17f

Requirements:	No special requirements
Platforms:	*nix, Linux
Keyword:	Called,  Context,  Django,  Django Secretballot,  Extra,  Function,  Manager,  Middleware,  Model,  Number,  Object,  Optional,  Parameter,  Passing,  Renamed,  Return,  Secretballot,  Takes,  Token,  Votes,  Voting
Users rating:	0/10