=================== Django registration =================== This is a fairly simple user-registration application for Django_, designed to make allowing user signups as painless as possible. .. _Django: http://www.djangoproject.com/ Overview ======== This application enables a common user-registration workflow: 1. User fills out a registration form, selecting a username and password and entering an email address. 2. An inactive account is created, and an activation link is sent to the user's email address. 3. 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 Using a package-management tool ------------------------------- The easiest way by far to install django-registration and most other interesting Python software is by using an automated package-management tool, so if you're not already familiar with the available tools for Python, now's as good a time as any to get started. The most popular option currently is `easy_install`_; refer to its documentation to see how to get it set up. Once you've got it, you'll be able to simply type:: easy_install django-registration And it will handle the rest. Another option that's currently gaining steam (and which I personally prefer for Python package management) is `pip`_. Once again, you'll want to refer to its documentation to get up and running, but once you have you'll be able to type:: pip install django-registration And you'll be done. 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. .. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall .. _pip: http://pypi.python.org/pypi/pip/ .. _django-registration 0.7 package: http://pypi.python.org/pypi/django-registration/0.7 .. _Mercurial: http://www.selenic.com/mercurial/wiki/ Basic use ========= To use the registration system with all its default settings, you'll need to do the following: 1. Add ``registration`` to the ``INSTALLED_APPS`` setting of your Django project. 2. 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. 3. Create the necessary templates (see the section on templates below for details). 4. Add this line to your site's root URLConf:: (r'^accounts/', include('registration.urls')), 5. 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. .. _views documentation: views.txt .. _models documentation: models.txt .. _the Django authentication documentation: http://www.djangoproject.com/documentation/authentication/ 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: 1. 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. 2. 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. 3. 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: * `Forms documentation`_ for details on ``RegistrationForm``, pre-packaged subclasses and available customizations. * `Models documentation`_ for details on ``RegistrationProfile`` and its custom manager. * `Views documentation`_ for details on the ``register`` and ``activate`` views, and methods for customizing them. .. _Forms documentation: forms.txt .. _Models documentation: models.txt .. _Views documentation: views.txt 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. .. _latest released version: http://pypi.python.org/pypi/django-registration/0.7 .. _the development repository: http://www.bitbucket.org/ubernostrum/django-registration/src/ 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. .. _project page on Bitbucket: http://www.bitbucket.org/ubernostrum/django-registration/overview/ .. _the issues list: http://www.bitbucket.org/ubernostrum/django-registration/issues/