Movie Vote
==========

This is a Django application suited for organizing movie showings. I schedule
movie showings every week and I wanted a way for viewers to vote for a
movie they'd like to see. Viewers are authenticated, and weighting is done of
votes to favor those who consistently show up.

The main movie list is sorted by score and provides links to IMDB, Rotten
Tomatoes, and Metacritic. Of course this information needs to be entered in
the database. You can do this via the admin interface. See the tools/
directory for ideas on automating such tasks.

Setup
=====

Packages
--------

sudo aptitude install python-django
sudo aptitude install libapache2-mod-python
sudo aptitude install postfix (or any other mailer daemon)
sudo aptitude install sqlite3
sudo aptitude install python-imdbpy
sudo aptitude install python-libxml2
sudo aptitude install python-yahoo

Django
------

This has been tested with Django 1.0.2.

Create a new Django project. Let's say the directory you want to install in
is /home/valankar/django-sites.

export PYTHONPATH=/home/valankar/django-sites
cd /home/valankar/django-sites
django-admin startproject movie

Extract this archive into the movie directory. Edit settings.py and setup your
database. See settings.py.SAMPLE. Do not just copy the sample file and use it,
since the secret key is missing. Be sure to enable the admin and movie as
installed apps.

Initialize the DB:

python manage.py syncdb

Now create the webserver configuration. Here is an example for Apache:

<VirtualHost *:81>
	ServerAdmin you@you.com

	DocumentRoot /home/valankar/django-sites/movie/webroot
	ErrorLog /var/log/apache2/movie-error.log

	# Possible values include: debug, info, notice, warn, error, crit,
	# alert, emerg.
	LogLevel warn

	CustomLog /var/log/apache2/movie-access.log combined

	Alias /media/ "/usr/share/python-support/python-django/django/contrib/admin/media/"
	Alias /static/ "/home/valankar/django-sites/movie/webroot/"

	<Location "/">
		SetHandler python-program
		PythonHandler django.core.handlers.modpython
		SetEnv DJANGO_SETTINGS_MODULE movie.settings
		# PythonOption django.root /
		PythonDebug On
		PythonPath "['/home/valankar/django-sites'] + sys.path"
	</Location>
	<Location "/media">
		SetHandler None
	</Location>
	<Location "/static">
		SetHandler None
	</Location>
</VirtualHost>

That should do it. If you use sqlite3, be sure your database is writable by
the webserver.

Migration
=========

When upgrading from a previous version, you will need to modify your DB schema
in case there are new fields. I've provided sample ALTER TABLE scripts for
upgrading in the tools/ directory.

v0.1-1.2 to v1.3: migrate01.sql
This change added review scores. 

v1.3 to v1.4: migrate02.sql
Adds support for secondary sort on unweighted tally.

v1.4 to v1.5: migrate03.sql
Adds youtube trailer url field.
Adds 'votable' boolean field to hide movies but still keep screening info.

v1.5 to v1.6: migrate04.sql
Adds rating table.
Adds tables to keep track of voters/downvoters for a screening.

Admnistration
=============

You will need to add movies to the Movie table. Users should be created in the
/admin interface. Users must be unique by their email address as well as by
their username.

Typically you'll also want to add entries to the Screening table as movies are
shown. If you don't do this and use the default weight algorithm, all voters
will get default weighting of 1. You can create your own weighting algorithms
by editing vote/weighting.py. The algorithm to use is defined in vote/models.py.

The tools/ directory contains various scripts for automating tasks such as
recalculating tallies, importing movies, adding review URLs, adding a
screening, and populating review scores. See the cron.sh script for an example
of what to cron. You should at least periodically run the update_tallies.py
script. These scripts make use of the following Python libraries:

libxml2dom
http://www.boddie.org.uk/python/libxml2dom.html

DOPAL
http://dopal.sourceforge.net/

Forgotten Passwords
===================

The login page allows users to request a password reset. This works a bit
differently than the Django-provided password resetting functions. The way it
works is it utilizes the Message interface in the User objects. When a user
selects the forgotten password link, a random string is generated and inserted
as a Message in the User object for the given email address. An email is sent to
the user with a special URL including that random string and the username. That
URL checks whether the random string exists as a Message in the User object. If
it does, the user is given a change password form. Otherwise an error is shown.

This prevents any passwords resets unless the proper URL is visited. The
Django-provided password reset functions reset the password immediately, giving
the ability for anyone to reset anyone else's password. I felt that inadequate.

Note that also once a user logs in, the messages for the user are essentially
discarded, which means any pending password reset requests are discarded.

You should make sure that email is setup properly in your Django site (e.g. be
sure to set a DEFAULT_FROM_EMAIL).

Customizing the UI
==================

The UI is written mostly in Java using Google Web Toolkit. See the gwt/
directory for the source.

Help
====

You can contact me at valankar@gmail.com.

Happy viewing!