James Bennett avatar James Bennett committed 7049aa2

More documentation.

Comments (0)

Files changed (5)

docs/backend-api.rst

 Specifying the backend to use
 -----------------------------
 
-To determine which backend to use, the views in django-registration
-accept a keyword argument ``backend``; in all cases, this should be a
-string containing the full dotted Python import path to the backend
-class to be used.
-
-So, for example, to use the default backend, you'd pass
-the string ``'registration.backends.default.DefaultBackend'`` as the
-value of the ``backend`` argument (and the default URLConf included
-with that backend does so).
-
-The specified backend class will then be imported and instantiated (by
-calling its constructor with no arguments), and the resulting instance
-will be used for all backend-specific functionality.
+To determine which backend to use, the :ref:`views in
+django-registration <views>` accept a keyword argument ``backend``; in
+all cases, this should be a string containing the full dotted Python
+import path to the backend class to be used. So, for example, to use
+the default backend, you'd pass the string
+``'registration.backends.default.DefaultBackend'`` as the value of the
+``backend`` argument (and the default URLConf included with that
+backend does so). The specified backend class will then be imported
+and instantiated (by calling its constructor with no arguments), and
+the resulting instance will be used for all backend-specific
+functionality.
 
 If the specified backend class cannot be imported, django-registration
 will raise ``django.core.exceptions.ImproperlyConfigured``.
    
    quickstart
    backend-api
-   upgrade
+   views
+   upgrade

docs/quickstart.rst

 
 Before installing django-registration, you'll need to have a copy of
 `Django <http://www.djangoproject.com>`_ already installed. For the
-0.8 release, Django 1.1 or newer is required; once Django 1.1 is
-released.
+|version| release, Django 1.1 or newer is required.
 
 For further information, consult the `Django download page
 <http://www.djangoproject.com/download/>`_, which offers convenient
     easy_install -Z django-registration
 
 Note that the ``-Z`` flag is required, to tell ``easy_install`` not to
-create a zipped package; zipped packages prevent Django from locating
-custom management commands.
+create a zipped package; zipped packages prevent certain features of
+Django from working properly.
 
 Using ``pip``, type::
 
 obtain it from the django-registration repository, which is hosted at
 `Bitbucket <http://bitbucket.org/>`_ and uses `Mercurial
 <http://www.selenic.com/mercurial/wiki/>`_ for version control. To
-obtain the latest code and documentation, type::
+obtain the latest code and documentation, you'll need to have
+Mercurial installed, at which point you can type::
 
     hg clone http://bitbucket.org/ubernostrum/django-registration/
 
 This will create a copy of the django-registration Mercurial
 repository on your computer; you can then add the
 ``django-registration`` directory inside the checkout your Python
-import path, or use the ``setup.py`` script to perform a global
-installation from that code.
+import path, or use the ``setup.py`` script to install as a package.
 
 
 Basic configuration and use
 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
+URLs under the prefix ``/accounts/``, you could add the following to
 your project's root ``URLConf``::
 
     (r'^accounts/', include('registration.backends.default.urls')),
     account which was just activated. If activation was unsuccessful,
     the boolean value ``False``; this may be because the activation
     period has expired, or the activation view was accessed with an
-    invalid or nonexistent activation key. In this case, an
-    appropriate error message should be displayed to the user.
+    invalid or nonexistent activation key. In such cases, an
+    appropriate error message should be displayed.
 
 **registration/activation_email_subject.txt**
 
 Upgrade guide
 =============
 
-The 0.8 release of django-registration represents a complete rewrite
-of the previous codebase, and introduces several new features which
-greatly enhance the customizability and extensibility of
+The |version| release of django-registration represents a complete
+rewrite of the previous codebase, and introduces several new features
+which greatly enhance the customizability and extensibility of
 django-registration. Whenever possible, changes were made in ways
 which preserve backwards compatibility with previous releases, but
 some changes to existing installations will still be required in order
-to upgrade to 0.8. This document provides a summary of those changes,
-and of the new features available in the 0.8 release.
+to upgrade to |version|. This document provides a summary of those
+changes, and of the new features available in the |version| release.
 
 
 Backwards-incompatible changes
     (r'^accounts/', include('registration.backends.default.urls')),
 
 The older include will continue to work until django-registration 1.0;
-in 0.8 it raises a ``PendingDeprecationWarning`` (which is ignored by
-default in Python), in 0.9 it will raise ``DeprecationWarning`` (which
-will begin printing warning messages on import) and in 1.0 it will be
-removed entirely.
+in |version| it raises a ``PendingDeprecationWarning`` (which is
+ignored by default in Python), in 0.9 it will raise
+``DeprecationWarning`` (which will begin printing warning messages on
+import) and in 1.0 it will be removed entirely.
+
+Changes to registration views
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The views used to handle user registration have changed significantly
+as of django-registration |version|. Both views now require the
+keyword argument ``backend``, which specifies the :ref:`registration
+backend <backend-api>` to use, and so any URL pattern for these views
+must supply that argument.
+
+The ``profile_callback`` argument of the ``register`` view has been
+removed; the functionality it provided can now be implemented easily
+via a custom backend, or by connecting listeners to the signals sent
+during the registration process.
+
+Changes to registration forms
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Previously, the form used to collect data during registration was
+expected to implement a ``save()`` method which would create the new
+user account. This is no longer the case; creating the account is
+handled by the backend, and so any custom logic should be moved into a
+custom backend, or by connecting listeners to the signals sent during
+the registration process.
+.. _views:
+.. module:: registration.views
+
+Registration views
+==================
+
+In order to allow users to register using whatever workflow is
+implemented by the :ref:`registration backend <backend-api>` in use,
+django-registration provides two views. Both are designed to allow
+easy configurability without writing or rewriting view code.
+
+.. function:: activate(request, backend, template_name='registration/activate.html', extra_context=None, **kwargs)
+
+   Activate a user's account, for workflows which require a separate
+   activation step.
+
+   The actual activation of the account will be delegated to the
+   backend specified by the ``backend`` keyword argument; the
+   backend's ``activate()`` method will be called, passing the
+   ``HttpRequest`` and any keyword arguments captured from the URL,
+   and will be assumed to return a ``User`` if activation was
+   successful, or a value which evaluates to ``False`` in boolean
+   context if not.
+
+   **Context**
+
+   ``account``
+      A ``User`` object representing the activated account, if the
+      activation was successful. ``False`` if the activation was not
+      successful.
+
+   This view uses ``RequestContext``, so variables populated by
+   context processors will also be present in the context.
+
+   :param backend: A string containing the dotted Python path to the
+      backend class to use.
+   :param template_name: Optional. A custom template name to use. If
+      not specified, this will default to
+      ``registration/activate.html``.
+   :param extra_context: Optional. A dictionary of variables to add to
+      the template context. Any callable object in this dictionary
+      will be called to produce the final result which appears in the
+      context.
+   :param **kwargs: Any keyword arguments captured from the URL, such
+      as an activation key, which will be passed to the backend's
+      ``activate()`` method.
+
+
+.. function:: register(request, backend, success_url=None, form_class=None, disallowed_url='registration_disallowed', template_name='registration/registration_form.html', extra_context=None)
+
+   Allow a new user to register an account.
+
+   The actual registration of the account will be delegated to the
+   backend specified by the ``backend`` keyword argument. The backend
+   is used as follows:
+
+   1. The backend's ``registration_allowed()`` method will be called,
+      passing the ``HttpRequest``, to determine whether registration
+      of an account is to be allowed; if not, a redirect is issued to
+      a page indicating that registration is not permitted.
+
+   2. The form to use for account registration will be obtained by
+      calling the backend's ``get_form_class()`` method, passing the
+      ``HttpRequest``. To override this, pass the keyword argument
+      ``form_class``.
+
+   3. If valid, the form's ``cleaned_data`` will be passed (as keyword
+      arguments, and along with the ``HttpRequest``) to the backend's
+      ``register()`` method, which should return a ``User`` object
+      representing the new account.
+
+   4. Upon successful registration, the backend's
+      ``post_registration_redirect()`` method will be called, passing
+      the ``HttpRequest`` and the new ``User``, to determine the URL
+      to redirect to. To override this, pass the keyword argument
+      ``success_url``.
+
+   **Context**
+
+   ``form``
+        The form instance being used to collect registration data.
+
+   This view uses ``RequestContext``, so variables populated by
+   context processors will also be present in the context.
+
+   :param backend: A string containing the dotted Python path to the
+      backend class to use.
+   :param success_url: The URL to redirect to after successful
+      registration. This should be a string suitable for passing as
+      the ``to`` argument to `Django's "redirect" shortcut
+      <http://docs.djangoproject.com/en/dev/topics/http/shortcuts/#redirect>`_. If
+      not specified, the backend's ``post_registration_redirect()``
+      method will be called to obtain the URL.
+   :param form_classs: The form class to use for registration; this
+      should be some subclass of ``django.forms.Form``. If not
+      specified, the backend's ``get_form_class()`` method will be
+      called to obtain the form class.
+   :param disallowed_url: The URL to redirect to if registration is
+      not permitted (e.g., if registration is closed). This should be
+      a string suitable for passing as the ``to`` argument to
+      `Django's "redirect" shortcut
+      <http://docs.djangoproject.com/en/dev/topics/http/shortcuts/#redirect>`_. If
+      not specified, this will default to ``registration_disallowed``.
+   :param template_name: Optional. A custom template name to use. If
+      not specified, this will default to
+      ``registration/registration_form.html``.
+   :param extra_context: Optional. A dictionary of variables to add to
+      the template context. Any callable object in this dictionary
+      will be called to produce the final result which appears in the
+      context.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.