Commits

Anonymous committed 3fcf785

Documentation updates

Comments (0)

Files changed (3)

+Thanks for downloading django-registration.
+
+To install it, run the following command inside this directory:
+
+    python setup.py install
+
+Or if you'd prefer you can simply place the included ``registration``
+directory somewhere on your Python path, or symlink to it from
+somewhere on your Python path; this is useful if you're working from a
+Subversion checkout.
+
+Note that this application requires Python 2.3 or later, and a recent
+Subversion checkout of Django. You can obtain Python from
+http://www.python.org/ and Django from http://www.djangoproject.com/.
+
 
 This is a fairly simple user-registration application for Django_,
 designed to make allowing user signups as painless as possible. It
-requires a recent Subversion checkout of Django, since it uses
-newforms and a couple other post-0.95 additions. Aside from that, it
-has no external dependencies.
+requires a recent Subversion checkout of Django, but has no other
+dependencies.
 
-
-Installation notes
-==================
-
-Google Code recommends doing the Subversion checkout like so::
-
-    svn checkout http://django-registration.googlecode.com/svn/trunk/ django-registration
-
-But the hyphen in the application name can cause issues installing
-into a DB, so it's really better to do this::
-
-    svn checkout http://django-registration.googlecode.com/svn/trunk/ registration
-
-If you've already downloaded, rename the directory before installing.
-
-Then just add ``registration`` to the ``INSTALLED_APPS`` setting of
-your project, and you should be good to go.
-
-Note that one of the templates included with this app uses the
-``humanize`` library, so you'll want to have
-``django.contrib.humanize`` installed if you don't already.
-
-
-The short and sweet instructions
-================================
-
-Here's the workflow for user signup:
-
-1. User signs up for account.
-2. User gets emailed an activation link.
-3. User clicks the activation link before it expires.
-4. User becomes a happy and productive contributor to your site.
-
-To make this work, start by putting this app into your
-``INSTALLED_APPS`` setting and running ``syncdb``. Then, add a new
-setting in your settings file: ``ACCOUNT_ACTIVATION_DAYS``. This
-should be a number, and will be used as the number of days before an
-activation key expires.
-
-Next, either edit the included templates (see below) to suit your
-site, or create your own templates which integrate with your site's
-look and feel.
-
-Finally, drop this line into your root URLConf::
-
-    (r'^accounts/', include('registration.urls')),
-
-And point people at the URL ``/accounts/register/``. Things should
-just work.
-
-
-If emails never get sent
-========================
-
-Welcome to the world of spam filtering! Assuming your server settings
-are correct and Django is otherwise able to send email, the most
-likely problem is overzealous filtering on the receiving end. Many
-spam filtering solutions are depressingly overactive and love to eat
-account-registration emails.
-
-If you know how to solve this, you will make millions of dollars.
-
-
-How it works under the hood
-===========================
-
-This app defines one model -- ``RegistrationProfile`` -- which is tied
-to the ``User`` model via a unique foreign key (so there can only ever
-be one ``RegistrationProfile`` per ``User``), and which stores an
-activation key and the date/time the key was generated.
-
-There's a custom manager on ``RegistrationProfile`` which has two
-important methods:
-
-1. ``create_inactive_user`` takes a username, email address and
-   password, and first creates a new ``User``, setting the
-   ``is_active`` field to ``False``. Then it generates an activation
-   key and creates a ``RegistrationProfile`` for that
-   ``User``. Finally, it sends an email to the new user with an
-   activation link to click on.
-2. ``activate_user`` takes an activation key, looks up the
-   ``RegistrationProfile`` it goes with, and sets ``is_active`` to
-   ``True`` on the corresponding ``User``.
-
-The views and form defined in this app basically exist solely to
-expose this functionality over the Web. The registration form, used in
-the initial sign-up view, does a little checking to make sure that the
-username isn't taken and that the user types a password twice without
-typos, but once that validation is taken care of everything gets
-handed off to ``RegistrationProfile.objects.create_inactive_user``.
-
-Similarly, the activation view doesn't do a whole lot other than call
-``RegistrationProfile.objects.activate_user``.
-
-
-Clearing out inactive accounts
-==============================
-
-Since activation keys do eventually expire (after however many days
-you've specified in the ``ACCOUNT_ACTIVATION_DAYS`` setting), there's
-a possibility that you'll end up with people who signed up but never
-activated their accounts. And that's bad, because it clutters up your
-database and it keeps the username they signed up with from ever
-actually being used.
-
-So there's also a third method defined on ``RegistrationProfile``'s
-custom manager: ``delete_expired_users``. All it does is loop through
-the DB, looking for inactive accounts with expired activation keys,
-and deletes them. It's recommended that you run it every once in a
-while (ideally, just set up a cron job to do it periodically) so you
-can clear out any inactive accounts and free up those usernames.
-
-The only time this isn't desirable is when you use the ``is_active``
-field as a way to keep troublesome users under control -- when you set
-``is_active`` to ``False``, they can't log in, which is pretty
-handy. But that means you _want_ to have an inactive account in your
-DB and you *don't* want ``delete_expired_users`` to delete it -- if
-that happened, the troublemaker could just re-create the account and
-start all over again.
-
-For this reason, ``delete_expired_users`` looks first at the
-``RegistrationProfile`` table, and only goes into the ``User`` table
-when it finds expired profiles. So to keep a ``User`` around and
-permanently inactive, just manually delete their
-``RegistrationProfile`` instance and ``delete_inactive_users`` will
-never touch their account.
-
-
-A note on templates
-===================
-
-The download includes a set of example templates to give you an idea
-of how to use the app, but please note that they are **examples** and
-almost certainly will not work "out of the box" with your site; the
-example templates are copied directly from a site which uses this
-application, which means that they include assumptions about the
-existence of that site's base templates and page structure. If you try
-to use them as-is, you will most likely receive errors about
-"base.html" not existing, or run into a mismatch between the blocks
-defined in your site's base template and the blocks used in the
-example templates.
-
-**As a result, it is assumed that you will look at, and edit, the
-included templates before trying to use them on your own site**. If
-you like, you can copy them into your site's template directory and
-edit them there, or edit them in-place; Django's "app directories"
-template loader, which is active by default, will be able to find them
-if you do so.
-
-If you're unsure of how to work with Django templates, consult `the
-Django template documentation`_.
-
-The included template for activation emails requires the ``humanize``
-library, so if you use it as-is, be sure to add
-``django.contrib.humanize`` to your ``INSTALLED_APPS`` setting.
-
-Questions? Problems?
-====================
-
-If you've got a question that isn't covered here or in the comments
-and docstrings in the code, or if you run into a bug, swing on over to
-`this app's Google Code project page`_ and file a new "issue". I'll do
-my best to respond promptly.
-
-
-.. _Django: http://www.djangoproject.com/
-.. _the Django template documentation: http://www.djangoproject.com/documentation/templates/
-.. _this app's Google Code project page: http://code.google.com/p/django-registration/
- 
+For installation instructions, see the file "INSTALL.txt" in this
+directory; for instructions on how to use this application, and on
+what it provides, see the file "overview.txt" in the "docs/"
+directory.

docs/overview.txt

+===================
+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/
+
+
+Dependencies
+============
+
+The only dependency for this application is a recent **SVN checkout**
+of Django; this application is tracking Django's development trunk,
+and has evolved to accomodate some changes which happened after the
+Django 0.96 release, so a stock copy of 0.96 will not work. If you
+need to use this application with Django 0.96, replace all uses of
+``cleaned_data`` with ``clean_data``.
+
+Due to use of the ``newforms`` library, this application cannot work
+with Django 0.95.
+
+
+Basic use
+=========
+
+This application enables a fairly common workflow for user signups:
+
+1. User signs up for account.
+2. User gets emailed an activation link.
+3. User clicks the activation link before it expires.
+4. User becomes a happy and productive contributor to your site.
+
+To make this work, start by putting this app into your
+``INSTALLED_APPS`` setting and running ``manage.py syncdb``. Then, add
+a new setting in your settings file: ``ACCOUNT_ACTIVATION_DAYS``. This
+should be a number, and will be used as the number of days before an
+activation key expires.
+
+Next, either edit the included templates (see below) to suit your
+site, or create your own templates which integrate with your site's
+look and feel.
+
+Finally, drop this line into your root URLConf::
+
+    (r'^accounts/', include('registration.urls')),
+
+And point people at the URL ``/accounts/register/``. Things should
+just work.
+
+
+Templates
+=========
+
+The download includes a set of **example** templates, which are meant
+to give you an idea of how things work. However, they're taken
+directly from a site which uses this application, and so they make
+assumptions about that site's template structure that probably aren't
+true of your site. So **it is expected that you will edit these
+templates before using them**, or use them as guides to create your
+own set of templates. Either way, you'll want to make sure you have a
+set of templates that works with your site, and with its look and
+feel.
+
+The default template included for the activation email makes use of
+the ``humanize`` template tag library, so if you use that template
+"as-is" you'll need to have ``django.contrib.humanize`` in your
+``INSTALLED_APPS`` setting.
+
+
+Models
+======
+
+This app includes one model: ``RegistrationProfile``, which is tied to
+the ``User`` model in ``django.contrib.auth`` via a unique foreign
+key. ``RegistrationProfile`` simply stores the user's activation key
+and the date/time when the key was generated.
+
+``RegistrationProfile`` has one custom method,
+``activation_key_expired``, which returns ``True`` if the key has
+expired and ``False`` otherwise.
+
+There's also a custom manager on ``RegistrationProfile`` which defines
+a few useful methods:
+
+    ``activate_user``
+        Takes an activation key, looks up the ``RegistrationProfile``
+        for that key, and sets the ``is_active`` field to ``True`` on
+        the ``User`` associated with it. If this is successful, it
+        returns the ``User``. If the key was expired, or if the key
+        didn't correspond to any ``RegistrationProfile``, this method
+        returns ``False``.
+
+    ``create_inactive_user``
+        Takes a username, email address and password, and first
+        creates a new ``User`` with those values, setting the
+        ``is_active`` field to ``False``. Then it generates an
+        activation key and stores a ``RegistrationProfile`` for the
+        ``User``. Finally, it sends an email to the user containing
+        the activation key. The email is generated by rendering the
+        template ``registration/activation_email.txt``, so edit that
+        template to customize the text of the email. This method
+        returns the new ``User`` object, in case you want to do
+        something with it afterwards.
+
+    ``delete_inactive_users``
+        Clears out accounts which were never activated; it does this
+        by finding accounts which still have ``is_active`` set to
+        ``False`` but have a ``RegistrationProfile`` with an expired
+        key, and deleting them. This is intended to keep your database
+        uncluttered and free up inactive usernames for registration,
+        but if for some reason you need to deactivate an account while
+        keeping the ``User`` in the database (say, to disable a
+        troublesome user's login), you can manually delete that
+        account's ``RegistrationProfile`` and this method will leave
+        it alone.
+
+Most of the time you won't need to manually write code which calls
+these methods, though; the included views (see below) will take care
+of them for you.
+
+
+Forms
+=====
+
+One form is included, because it's really all that's needed to handle
+user signups.
+
+``registration.forms.RegistrationForm``
+---------------------------------------
+
+This form collects a username, email address and password from a
+prospective user, and does a little bit of validation:
+
+* It checks that the username is not already in use.
+
+* It requires the user to enter the password twice (to avoid typos),
+  and checks that both versions match.
+
+This is really the minimal level of validation that most people seem
+to want; more advanced schemes like requiring that usernames or
+passwords be at least a certain number of characters long, or also
+validating the uniqueness of the email address, are best handled by
+customizing the form to your own needs.
+
+
+Views
+=====
+
+Two views are included, and between them they handle all the actual
+work of registering and activating users.
+
+
+``registration.views.activate``
+-------------------------------
+
+This view accepts an activation key, and calls
+``RegistrationProfile.objects.activate_user`` (see above) to activate
+the account associated with that key.
+
+The template used is ``registration/activate.html``, and it receives
+two context variables:
+
+    ``account``
+        The ``User`` who was activated, if activation was successful,
+        or ``False`` if the key was expired or didn't match any
+        existing account.
+
+    ``expiration_days``
+        The number of days activation keys last before they expire;
+        this is useful for displaying a "perhaps the account expired"
+        message on an unsuccessful activation.
+
+
+``registration.views.register``
+-------------------------------
+
+This view signs up a new user account, by displaying and validating a
+``RegistrationForm``, and calling
+``RegistrationProfile.objects.create_inactive_user`` (see above) once
+it gets valid data.
+
+The template used is ``registration/registration_form.html``, and it
+receives a context variable named ``form``, which is the
+``RegistrationForm`` instance. It also uses ``RequestContext``, so any
+context processors you've enabled on your site will be applied as
+well.
+
+On successful registration, this view issues a redirect; the default
+URL of the redirect is ``/accounts/register/complete/``, but you can
+override this by passing the keyword argument ``success_url`` into the
+view.
+
+URLs
+====
+
+The default URLConf included with this application maps the following
+URL fragments to the following views:
+
+    ``activate/<activation key>/``
+        Maps to ``registration.views.activate``. Note that this URL
+        will match any string as ``activation_key``; the pattern will
+        be checked to see if it matches the format of a SHA1 hash
+        before any database lookup happens, but allowing anything to
+        match here means you can show a useful "this key is invalid"
+        message instead of a confusing 404 when the format isn't
+        correct.
+    
+    ``register/``
+        Maps to ``registration.views.register``.
+
+    ``register/complete/``
+        Maps to ``django.views.generic.simple.direct_to_template``,
+        using the template
+        ``registration/registration_complete.html``.
+
+    ``login/``
+        Maps to ``django.contrib.auth.views.login``.
+
+    ``logout/``
+        Maps to ``django.contrib.auth.views.logout``.
+
+A good place to include this URLConf if you use it directly is at
+``accounts/``.
+
+
+Troubleshooting
+===============
+
+There are two problems you're likely to run into: one is not editing
+the default template set (see above for why you need to do that), and
+will lead either to errors about a base template not existing, or to a
+mismatch between names of blocks in your site's base template and
+names of blocks in the default template set.
+
+The other problem you're likely to see is users complaining that they
+didn't get their activation emails. This is most likely due to
+overzealous spam filtering by their ISP or email provider;
+unfortunately, many spam filters eat account registration emails for
+breakfast. If you can solve that problem, you will make millions of
+dollars.
+
+
+What this application does not do
+=================================
+
+This application does not take custom user profiles (as specified in
+the ``AUTH_PROFILE_MODULE`` setting) into account, and will neither
+look for them nor try to create instances of them for you. If you're
+using a custom profile model, you'll want to either write your own
+registration view which can create an instance of it on
+registration/activation, or else use Django's dispatcher to hook into
+the ``post_save`` signal of ``User`` or ``RegistrationProfile`` and
+automatically create an instance of your profile model.
+
+This application also 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 on every
+site they want to use :)
+
+
+If you spot a bug
+=================
+
+Head over to this application's `project page on Google Code`_ 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 Google Code: http://code.google.com/p/django-registration/
+.. _the issues list: http://code.google.com/p/django-registration/issues/list
+
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.