.. _quickstart: Quick start guide ================= Before installing |project|, you'll need to have a copy of `Django `_ already installed. For the |version| release, Django 2.0 or newer is required. For further information, consult the `Django download page `_, which offers convenient packaged downloads and installation instructions. Installing |project| -------------------- There are several ways to install |project|: * Automatically, via a package manager. * Manually, by downloading a copy of the release package and installing it yourself. * Manually, by performing a Git checkout of the latest code. It is also highly recommended that you learn to use `virtualenv `_ for development and deployment of Python software; ``virtualenv`` provides isolated Python environments into which collections of software (e.g., a copy of Django, and the necessary settings and applications for deploying a site) can be installed, without conflicting with other installed software. This makes installation, testing, management and deployment far simpler than traditional site-wide installation of Python packages. Automatic installation via a package manager ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Several automatic package-installation tools are available for Python; the recommended one is `pip `_. Using ``pip``, type:: pip install django-registration-redux It is also possible that your operating system distributor provides a packaged version of |project|. Consult your operating system's package list for details, but be aware that third-party distributions may be providing older versions of |project|, and so you should consult the documentation which comes with your operating system's package. Manual installation from a downloaded package ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you prefer not to use an automated package installer, you can download a copy of |project| and install it manually. The latest release package can be downloaded from |project|'s `listing on the Python Package Index `_. Once you've downloaded the package, unpack it (on most operating systems, simply double-click; alternately, type ``tar zxvf django-registration-redux-x.x.tar.gz`` at a command line on Linux, Mac OS X or other Unix-like systems). This will create the directory ``django-registration-redux-x.x``, which contains the ``setup.py`` installation script. From a command line in that directory, type:: python setup.py install Note that on some systems you may need to execute this with administrative privileges (e.g., ``sudo python setup.py install``). Manual installation from a Git checkout ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you'd like to try out the latest in-development code, you can obtain it from the |project| repository, which is hosted at `Github `_ and uses `Git `_ for version control. To obtain the latest code and documentation, you'll need to have Git installed, at which point you can type:: git clone https://github.com/macropin/django-registration.git You can also obtain a copy of a particular release of |project| by specifying the ``-b`` argument to ``git clone``; each release is given a tag of the form ``vX.Y``, where "X.Y" is the release number. So, for example, to check out a copy of the |version| release, type:: git clone -b v1.0 https://github.com/macropin/django-registration.git In either case, this will create a copy of the |project| Git repository on your computer; you can then add the ``django-registration-redux`` directory inside the checkout your Python import path, or use the ``setup.py`` script to install as a package. Basic configuration and use --------------------------- Once installed, you can add |project| to any Django-based project you're developing. The default setup will enable user registration with the following workflow: 1. A user signs up for an account by supplying a username, email address and password. 2. From this information, a new ``User`` object is created, with its ``is_active`` field set to ``False``. Additionally, an activation key is generated and stored, and an email is sent to the user containing a link to click to activate the account. 3. Upon clicking the activation link, the new account is made active (the ``is_active`` field is set to ``True``); after this, the user can log in. Note that the default workflow requires ``django.contrib.auth`` to be installed, and it is recommended that ``django.contrib.sites`` be installed as well. You will also need to have a working mail server (for sending activation emails), and provide Django with the necessary settings to make use of this mail server (consult `Django's email-sending documentation `_ for details). Settings ~~~~~~~~ Begin by adding ``registration`` to the ``INSTALLED_APPS`` setting of your project, and specifying one additional setting: ``ACCOUNT_ACTIVATION_DAYS`` This is the number of days users will have to activate their accounts after registering. If a user does not activate within that period, the account will remain permanently inactive and may be deleted by maintenance scripts provided in |project|. ``REGISTRATION_DEFAULT_FROM_EMAIL`` Optional. If set, emails sent through the registration app will use this string. Falls back to using Django's built-in ``DEFAULT_FROM_EMAIL`` setting. ``REGISTRATION_EMAIL_HTML`` Optional. If this is `False`, registration emails will be send in plain text. If this is `True`, emails will be sent as HTML. Defaults to `True`. ``REGISTRATION_AUTO_LOGIN`` Optional. If this is `True`, your users will automatically log in when they click on the activation link in their email. Defaults to `False`. ``ACCOUNT_AUTHENTICATED_REGISTRATION_REDIRECTS`` Optional. If this is `True`, your users will automatically be redirected to ``LOGIN_REDIRECT_URL`` when trying to access the ``RegistrationView``. Defaults to `True`. ``REGISTRATION_USE_SITE_EMAIL`` Optional. If this is `True`, the ``Site`` object will determine the domain that emails are sent. The ``REGISTRATION_SITE_USER_EMAIL`` setting must be set if this is `True`. Defaults to `False`. ``REGISTRATION_SITE_USER_EMAIL`` Required if ``REGISTRATION_USE_SITE_EMAIL`` is set. Determines the user that emails are sent by. For example, if this is set to ``admin`` emails will be sent from ``admin@``. For example, you might have something like the following in your Django settings file:: INSTALLED_APPS = [ 'django.contrib.sites', 'registration', #should be immediately above 'django.contrib.admin' 'django.contrib.admin', # ...other installed applications... ] ACCOUNT_ACTIVATION_DAYS = 7 # One-week activation window; you may, of course, use a different value. REGISTRATION_AUTO_LOGIN = True # Automatically log the user in. Once you've done this, run ``python manage.py migrate`` to install the model used by the default setup. Note, in order for the templates to properly work, the ``registration`` app **must** appear above ``django.contrib.admin``. Setting up URLs ~~~~~~~~~~~~~~~ The :ref:`default backend ` includes a Django ``URLconf`` which sets up URL patterns for :ref:`the views in django-registration-redux `, as well as several useful views in ``django.contrib.auth`` (e.g., login, logout, password change/reset). This ``URLconf`` can be found at ``registration.backends.default.urls``, and so can simply be included in your project's root URL configuration. For example, to place the URLs under the prefix ``/accounts/``, you could add the following to your project's root ``URLconf``:: path('accounts/', include('registration.backends.default.urls')), Users would then be able to register by visiting the URL ``/accounts/register/``, login (once activated) at ``/accounts/login/``, etc. Another ``URLConf`` is also provided -- at ``registration.auth_urls`` -- which just handles the Django auth views, should you want to put those at a different location. Templates ~~~~~~~~~ The templates in |project| assume you have a ``base.html`` template in your project's template directory. This base template should include a ``title``, ``meta``, and ``content`` block. The ``title`` block should allow customization of the ```` tag. The ``meta`` block should appear within the ``<head>`` tag to allow for custom ``<meta`` tags for security reasons. The ``content`` block should be within the ``<body>`` tag. Other than that, every template needed is included. You can extend and customize the included templates as needed. To customize the templates, create a ``registration`` folder where the `template loader is configured to find templates <https://docs.djangoproject.com/en/dev/topics/templates/#configuration>`_. Copy the existing templates from the installed package or for your `version on Github <https://github.com/macropin/django-registration/releases>`_ and modify them as necessary. Some of the templates you'll probably want to customize are covered here: Note that, with the exception of the templates used for account activation emails, all of these are rendered using a ``RequestContext`` and so will also receive any additional variables provided by `context processors <http://docs.djangoproject.com/en/dev/ref/templates/api/#id1>`_. .. _registration_form.html: registration/registration_form.html ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Used to show the form users will fill out to register. By default, has the following context: ``form`` The registration form. This will be an instance of some subclass of ``django.forms.Form``; consult `Django's forms documentation <http://docs.djangoproject.com/en/dev/topics/forms/>`_ for information on how to display this in a template. .. _registration_complete.html: registration/registration_complete.html ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Used after successful completion of the registration form. This template has no context variables of its own, and should simply inform the user that an email containing account-activation information has been sent. .. _registration_closed.html: registration/registration_closed.html ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Used when new account registration has been closed by an administrator. .. _activate.html: registration/activate.html ^^^^^^^^^^^^^^^^^^^^^^^^^^ Used if account activation fails. With the default setup, has the following context: ``activation_key`` The activation key used during the activation attempt. .. _activation_complete.html: registration/activation_complete.html ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Used after successful account activation. This template has no context variables of its own, and should simply inform the user that their account is now active. .. _resend_activation_complete.html: registration/resend_activation_complete.html ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Used after form for resending account activation is submitted. By default has the following context: ``email`` The email address submitted in the resend activation form. .. _activation_email_subject.txt: registration/activation_email_subject.txt ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Used to generate the subject line of the activation email. Because the subject line of an email must be a single line of text, any output from this template will be forcibly condensed to a single line before being used. This template has the following context: ``activation_key`` The activation key for the new account. ``expiration_days`` The number of days remaining during which the account may be activated. ``site`` An object representing the site on which the user registered; depending on whether ``django.contrib.sites`` is installed, this may be an instance of either ``django.contrib.sites.models.Site`` (if the sites application is installed) or ``django.contrib.sites.models.RequestSite`` (if not). Consult `the documentation for the Django sites framework <http://docs.djangoproject.com/en/dev/ref/contrib/sites/>`_ for details regarding these objects' interfaces. .. _activation_email.txt: registration/activation_email.txt ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **IMPORTANT**: If you override this template, you must also override the HTML version (below), or disable HTML emails by adding ``REGISTRATION_EMAIL_HTML = False`` to your settings.py. Used to generate the text body of the activation email. Should display a link the user can click to activate the account. This template has the following context: ``activation_key`` The activation key for the new account. ``expiration_days`` The number of days remaining during which the account may be activated. ``site`` An object representing the site on which the user registered; depending on whether ``django.contrib.sites`` is installed, this may be an instance of either ``django.contrib.sites.models.Site`` (if the sites application is installed) or ``django.contrib.sites.models.RequestSite`` (if not). Consult `the documentation for the Django sites framework <http://docs.djangoproject.com/en/dev/ref/contrib/sites/>`_ for details regarding these objects' interfaces. ``user`` The new user account .. _activation_email.html: registration/activation_email.html ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This template is used to generate the html body of the activation email. Should display the same content as the text version of the activation email. The context available is the same as the text version of the template. .. _admin_approve_email_subject.txt: registration/admin_approve_email_subject.txt ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Used to generate the subject line of the approval email sent to the admin. Because the subject line of an email must be a single line of text, any output from this template will be forcibly condensed to a single line before being used. This template has the following context: ``site`` An object representing the site on which the user registered; depending on whether ``django.contrib.sites`` is installed, this may be an instance of either ``django.contrib.sites.models.Site`` (if the sites application is installed) or ``django.contrib.sites.models.RequestSite`` (if not). Consult `the documentation for the Django sites framework <http://docs.djangoproject.com/en/dev/ref/contrib/sites/>`_ for details regarding these objects' interfaces. .. _admin_approve_email.txt: registration/admin_approve_email.txt ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **IMPORTANT**: If you override this template, you must also override the HTML version (below), or disable HTML emails by adding ``REGISTRATION_EMAIL_HTML = False`` to your settings.py. Used to generate the text body of the approval email sent to the admin. Should display a link the user can click to activate the account. This template has the following context: ``user`` The username of the user that requests approval for the new account. ``site`` An object representing the site on which the user registered; depending on whether ``django.contrib.sites`` is installed, this may be an instance of either ``django.contrib.sites.models.Site`` (if the sites application is installed) or ``django.contrib.sites.models.RequestSite`` (if not). Consult `the documentation for the Django sites framework <http://docs.djangoproject.com/en/dev/ref/contrib/sites/>`_ for details regarding these objects' interfaces. .. _admin_approve_email.html: registration/admin_approve_email.html ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This template is used to generate the html body of the approval email sent to the admin. Should display the same content as the text version of the approval email. The context available is the same as the text version of the template. .. _admin_approve_complete.html: registration/admin_approve_complete.html ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Used after successful account approval. This template has no context variables of its own, and should simply inform the admin that the user account is now approved. .. _admin_approve_complete_email_subject.txt: registration/admin_approve_complete_email_subject.txt ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Used to generate the subject line of the admin approval complete email. Because the subject line of an email must be a single line of text, any output from this template will be forcibly condensed to a single line before being used. This template has the following context: ``site`` An object representing the site on which the user registered; depending on whether ``django.contrib.sites`` is installed, this may be an instance of either ``django.contrib.sites.models.Site`` (if the sites application is installed) or ``django.contrib.sites.requests.RequestSite`` (if not). Consult `the documentation for the Django sites framework <http://docs.djangoproject.com/en/dev/ref/contrib/sites/>`_ for details regarding these objects' interfaces. .. _admin_approve_complete_email.txt: registration/admin_approve_complete_email.txt ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **IMPORTANT**: If you override this template, you must also override the HTML version (below), or disable HTML emails by adding ``REGISTRATION_EMAIL_HTML = False`` to your settings.py. Used after successful account activation. This template has the following context: ``site`` An object representing the site on which the user registered; depending on whether ``django.contrib.sites`` is installed, this may be an instance of either ``django.contrib.sites.models.Site`` (if the sites application is installed) or ``django.contrib.sites.requests.RequestSite`` (if not). Consult `the documentation for the Django sites framework <http://docs.djangoproject.com/en/dev/ref/contrib/sites/>`_ for details regarding these objects' interfaces. .. _admin_approve_complete_email.html: registration/admin_approve_complete_email.html ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ This template is used to generate the html body of the approval complete email sent to the user. Should display the same content as the text version of the approval complete email. The context available is the same as the text version of the template.