This repo is an accompaniment to a presentation at DjangoCon USA 2016, called "Sign Me Up: Choosing & using a registration package for your Django project". It was given in Philadelphia, PA on July 18, 2016.
This talk was designed with the novice Django user in mind (some basic familiarity, has completed a tutorial or done a small project) but it could be useful for anyone who has not set up user registration for a site before.
If you have any questions, or see any errors in this repo, please open an issue or email me.
This repo uses the following languages, frameworks & libraries:
- Python 3
- Django 1.9
- django-registration-redux 1.4
- Google Fonts I use a Mac so all of the directions are written from that perspective (sorry, Windows users!).
Getting started with this repo
While this talk was inspired by stuggles I had with a side project of mine called valeez
Registration is a common component of most web applications, so knowing how to implement it is a useful skill. After working through the process for a personal project in 2015 (available at valeez.com), I submitted this talk to DjangoCon in order to share:
- Criteria and resources for choosing a registration package
- How the pieces of a registration package fit into the Django framework
- Some ‘gotchas’ that aren’t clear in or absent from documentation
Choosing a registration package
This repo and tutorial use django-registration-redux, but there are many other options out there!
Some key considerations are:
Matching product requirements: To pick the right tools, you need to know what your end goals are. Do your requirements call for social media login? OAuth? Email validation? Sounds obvious, but this is an often overlooked step. Addressing those now and understanding the benefits and limitations of your choice will save you headaches down the road, I promise!
Compatibility: Keep in mind you may need to upgrade your version of Django (for example) to use a package, or certain packages may not be compatible with newer versions (probably not a great sign...). I advocate using the latest stable release of software for an application that will be available to real users.
Maintenance & Usage: As a rule of thumb, good maintenance and a decent user base go hand in hand. Maybe you'll find an undiscovered gem, feel like experimenting, etc. but if you need things to be reliable, I recommend sticking with the tried and true.
Quality of documentation and tutorials: Good documentation is important. If the official write ups for the package you want to use are confusing, look for online tutorials (I'm a big fan of YouTube), Stack Overflow Q&As, meetups or other gatherings where you might find people who can help you. If there's a derth of information, and the package creators aren't responsive, might be better to choose something else.
I love the site http://djangopackages.com to evaluate my options, even if it doesn't answer all of your questions, it's a great starting point.
Now, let's get to the nitty gritty.
Fitting django-registration-redux in the django framework
If you've already cloned the repo, you have some project files, but if not, this will walk you through what to create.
Start by creating a project and an app. If you need help with this, I highly recommend the Django Girls tutorial.
Then if you go into your top-level project folder, you should see:
- manage.py file
- App folder (
reviewsin this example)
- Project folder (
djangoconin this example)
First, an overview of what we'll need to do here to add user registration.
Things to add
Here are the files and folders that we need to add in the app folder (again, that's
reviews in this example).
forms.py file: We'll use this to create a user registration form, based on Django's built in User model, which you can learn about here: https://docs.djangoproject.com/en/1.9/ref/contrib/auth/#django.contrib.auth.models.User
templates folder: This will hold all of your templates. In most cases, these are the HTML files that display between your navigation bar and footer (if you have one). If you have an app that displays some views in the browser, you've already done this.
templates folder, you should have:
base.html: This is what the templates will extend (a fancy way of saying display under/inside of)
Application templates folder (
reviewsin this example): This folder holds all of the application templates that are not part of the registration flow. Again, if you have an app that displays some views in the browser, you've already got this.
registration folder: This is where you will put all of the templates you'll need for the registration flow, for registering, logging in and out, resetting a password. More on those in a minute.
Files that will be modified
In addition to the files and folders listed above, we will need to make changes to two files in the project folder:
settings.py: Add the registration app and some settings to control its behavior, from the login page we show to how we deliver account verification messages.
urls.py: Code to point Django to the registration templates.
Now that we have an overview of what's going on, let's get coding.
Making it work
Step 0: Install in venv & update requirements
I'm going to use
pip a bunch here. In your virtual environment, in your root, type `pip install django-registration-redux'. And it's installed! Magical.
Next, you want to update your requirements.txt file by typing `pip freeze > requirements.txt'. If you don't already have a requirements file, it's a good idea to create one in case you or someone else wants to clone and run your project on another machine.
Step 1: Create a form for the User in forms.py
You need to make a form for the user to add their data. Fortunately, we can leverage the Django User model to accomplish this.
The only two fields that are required are username and password, but if you want to have a step where the user validates their account with an email link, you should have email in there as well. First and last name are built in, and you can extend the User model to add more fields, although that's beyond the scope of this talk.
Head on over to your
forms.py and add/make sure you have these lines of code:
from django import forms from django.contrib.auth.models import User class UserForm(forms.ModelForm): class Meta: model = User fields = ('username', 'email', 'password')
For the fields variable, add the built in attributes of the User model that you want to include, per the documentation.
Step 2: Install the app in settings.py, migrate
Head over to your
settings.py file and add
'registration', to the list in the
At this point, you should make sure that you have
in that list as well. In the slides and the documentation for this package, there are other variables you can set that are really important for user experience, like how long the authorization link is valid for, if they are automatically signed in when they enroll, etc. You could definitely set
LOGIN_URL = 'accounts/login/' and the
LOGIN_REDIRECT_URL to the path that you want.
Step 3: Get the registration templates
You can write all of these yourself, but why do that when a nice person has already done it for us! Visit this repo where you can download the whole set! Add this to the
registration folder in the
Step 4: Add the url pattern to the urls.py that's NOT in your app
urlpatterns list, add this line, to tell django to use the registration urls:
url(r'^accounts/', include('registration.backends.default.urls')),. This instructs Django to use the 'standard' registration urls, so you don't need to add one for each template individually, which is a big headache.
That's it -- almost! Here are a couple of other things you might want to do that tripped me up
These two issues are documented, but I had a hard time tracking down these problems.
Issue #1: Custom registration templates did not show up!
This was one of the more frustrating problems I had -- I made beautiful customizations on my registration templates and none of them showed up.
To fix this, you need to be sure that the 'registration' app shows up in the
settings.py file in the
INSTALLED_APPS list before
django.contrib.admin, and your app before that.
Issue #2: Errors when trying to test the email on my local machine
Before you've set up an email server, Django knows it must send an email, but doesn't know where to send it.
Before you have all of that set up, you can test that the email verification works by printing it into the console. This requires a single line of code in your
EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'. Easy, right??
- You need to set your SITE_ID variable, either by opening the shell (
python manage.py shell) and instantiating a class, like so: ''' from django.contrib.sites.models import Site Site.objects.create(name='localhost:8000', domain='localhost:8000') '''
localhost:8000 because this is the easiest way to check locally (substituting whatever port you use for the 8000 if applicable) -- you would definitely want to update this in the shell or the admin panel before putting it in production.
- Remember to update your
EMAIL_BACKENDvariable before you test with an email server. This is easy to forget, but will cause errors if you set the rest of the variables needed in your
settings.py. You will need to change
smtpin most cases.
THATS IT! Thanks for reading, and please don't hesitate to contact me if you have any questions or suggestions about this tutorial.