Django registration
This is a fairly simple user-registration application for Django,
designed to make allowing user signups as painless as possible.
Overview
This application enables a common user-registration workflow:
- User fills out a registration form, selecting a username and
password and entering an email address.
- An inactive account is created, and an activation link is sent to
the user's email address.
- User clicks the activation link, the account becomes active and the
user is able to log in and begin contributing to your site.
Various methods of extending and customizing the registration process
are also provided.
Installation
In order to use django-registration, you will need to have a
functioning installation of Django 1.0 or newer; due to changes needed
to stabilize Django's APIs prior to the 1.0 release,
django-registration will not work with older releases of Django.
There are three basic ways to install django-registration:
automatically installing a package using Python's package-management
tools, manually installing a package, and installing from a Mercurial
Manually installing the 0.7 package
If you'd prefer to do things the old-fashioned way, you can manually
download the django-registration 0.7 package from the Python
Package Index. This will get you a file named
"django-registration-0.7.tar.gz" which you can unpack (double-click on
the file on most operating systems) to create a directory named
"django-registration-0.7". Inside will be a script named "setup.py";
running:
python setup.py install
will install django-registration (though keep in mind that this
defaults to a system-wide installation, and so may require
administrative privileges on your computer).
Installing from a Mercurial checkout
If you have Mercurial installed on your computer, you can also
obtain a complete copy of django-registration by typing:
hg clone http://bitbucket.org/ubernostrum/django-registration/
Inside the resulting "django-registration" directory will be a
directory named "registration", which is the actual Python module for
this application; you can symlink it from somewhere on your Python
path. If you prefer, you can use the setup.py script in the
"django-registration" directory to perform a normal installation, but
using a symlink offers easy upgrades: simply running hg pull -u
inside the django-registration directory will fetch updates from the
main repository and apply them to your local copy.
Basic use
To use the registration system with all its default settings, you'll
need to do the following:
Add registration to the INSTALLED_APPS setting of your
Django project.
Add the setting ACCOUNT_ACTIVATION_DAYS to your settings file;
this should be the number of days activation keys will remain valid
after an account is registered.
Create the necessary templates (see the section on templates below
for details).
Add this line to your site's root URLConf:
(r'^accounts/', include('registration.urls')),
Link people to /accounts/register/ so they can start signing
up. Using the default URLConf will also automatically set up the
authentication-oriented views in django.contrib.auth for you,
so if you use it you can point people to, e.g.,
/accounts/login/ to log in.
Templates used by django-registration
The views included in django-registration make use of five templates:
- registration/registration_form.html displays the registration
form for users to sign up.
- registration/registration_complete.html is displayed after the
activation email has been sent, to tell the new user to check
his/her email.
- registration/activation_email_subject.txt is used for the
subject of the activation email.
- registration/activation_email.txt is used for the body of the
activation email.
- registration/activate.html is displayed when a user attempts to
activate his/her account.
Examples of all of these templates are not provided; you will need to
create them yourself. For views defined in this application, see the
included views documentation for details on available context
variables, and for details on the templates used by the activation
email see the included models documentation.
Additionally, the URLConf provided with django-registration includes
URL patterns for useful views in Django's built-in authentication
application -- this means that a single include in your root
URLConf can wire up registration and the auth application's login,
logout, and password change/reset views. If you choose to use these
views you will need to provide your own templates for them; consult
the Django authentication documentation for details on the
templates and contexts used by these views.
How it works
Using the recommended default configuration, the URL
/accounts/register/ will map to the view
registration.views.register, which displays a registration form
(an instance of registration.forms.RegistrationForm); this form
asks for a username, email address and password, and verifies that the
username is available and requires the password to be entered twice
(to catch typos). It then does three things:
- Creates an instance of django.contrib.models.auth.User, using
the supplied username, email address and password; the
is_active field on the new User will be set to False,
meaning that the account is inactive and the user will not be able
to log in yet.
- Creates an instance of registration.models.RegistrationProfile,
stores an activation key (a SHA1 hash generated from the new user's
username plus a randomly-generated "salt"), and relates that
RegistrationProfile to the User it just created.
- Sends an email to the user (at the address they supplied)
containing a link which can be clicked to activate the account.
For details on customizing this process, including use of alternate
registration form classes and automatic creation of a site-specific
profile, see the sections on customization below.
After the activation email has been sent,
registration.views.register issues a redirect to the URL
/accounts/register/complete/. By default, this is mapped to the
direct_to_template generic view, and displays the template
registration/registration_complete.html; this is intended to show
a short message telling the user to check his/her email for the
activation link.
The activation link will map to the view
registration.views.activate, which will attempt to activate the
account by setting the is_active field on the User to
True. If the activation key for the User has expired (this is
controlled by the setting ACCOUNT_ACTIVATION_DAYS, as described
above), the account will not be activated (see the section on
maintenance below for instructions on cleaning out expired accounts
which have not been activated).
Maintenance
Inevitably, a site which uses a two-step process for user signup --
registration followed by activation -- will accumulate a certain
number of accounts which were registered but never activated. These
accounts clutter up the database and tie up usernames which might
otherwise be actively used, so it's desirable to clean them out
periodically. For this purpose, a script,
registration/bin/deleted_expired_users.py, is provided, which is
suitable for use as a regular cron job. See that file for notes on how
to add it to your crontab, and the included models documentation (see
below) for discussion of how it works and some caveats.
Where to go from here
Full documentation for all included components is bundled in the
packaged release; see the following files for details:
Development
The latest released version of this application is 0.7, and is
quite stable; it's already been deployed on a number of sites,
including djangoproject.com. You can also obtain the absolute freshest
code from the development repository_, but be warned that the
development code may not always be backwards-compatible, and may well
contain bugs that haven't yet been fixed.
This document covers the 0.7 release of django-registration; new
features introduced in the development trunk will be added to the
documentation at the time of the next packaged release.
Changes from previous versions
Several new features were added between version 0.2 and version 0.3;
for details, see the CHANGELOG.txt file distributed with the packaged
0.3 release.
One important change to note before upgrading an installation of
version 0.1 is a change to the RegistrationProfile model; the
field key_generated has been removed, since it was redundant with
the field date_joined on Django's bundled User model. Since
this field became a NOT NULL column in the database, you will need
to either drop the NOT NULL constraint or, preferably, simply drop
the column. Consult your database's documentation for the correct way
to handle this.
Between version 0.3 and version 0.4, validation of the password fields
was moved from clean_password2() to clean_password(); this
means that errors from mismatched passwords will now show up in
non_field_errors() instead of errors["password2"].
Between version 0.6 and version 0.7, the script
registration/bin/delete_expired_users.py was removed, and replaced
with a custom management command; you can now simply run manage.py
cleanupregistration from any project which has django-registration
installed.
Dependencies
The only dependencies for this application are a functioning install
of Django 1.0 or newer and, of course, a Django project in which you'd
like to use it.
Your Django project should have django.contrib.admin,
django.contrib.auth and django.contrib.sites in its
INSTALLED_APPS setting.
What this application does not do
This application does not integrate in any way with OpenID, nor should
it; one of the key selling points of OpenID is that users don't
have to walk through an explicit registration step for every site or
service they want to use :)
If you spot a bug
Head over to this application's project page on Bitbucket and
check the issues list to see if it's already been reported. If not,
open a new issue and I'll do my best to respond quickly.