Crash Course - Web Dev with Django, Heroku, Bootstrap

We have now got our Django project up and running. Now we need an app. We already have several default apps enabled, see them in $SITENAME/settings.py.

Some apps have a web front-end, others are frameworks which can support other apps. The django.contrib.admin app does have a web front-end. View it with your dev server by adding /admin to the end of the URL.

If you want to try out the admin interface now; make a user to login as:

python manage.py createsuperuser

In the future you will want to familiarize yourself with Django Packages for getting off-the-shelf apps so I recommend bookmarking that.

We need to make our app for our poll application.

We'll create our poll app in the same directory as our manage.py file so that it can be imported as it's own top-level module, rather than a submodule of $SITENAME.

Django provides a command to template out an app. Use it to create an app named "polls":

python manage.py startapp polls

Take a look inside the polls directory it just created.

So that Django knows to include our app, edit $SITENAME/settings.py and add 'polls.apps.PollsConfig', to the INSTALLED_APPS array.

Remember the default app our project has called "admin"?

This app is very useful and you will likely use it with most of your projects, so we will now learn how to configure and use it properly.

If you didn't already, make a user to login as:

python manage.py createsuperuser

Now load up the admin at /admin/ and login. As you can see; Groups and Users are editable by default. But as our polls app isn't authenticated yet these are just used for the admin app itself.

Let's add our Question table to the admin interface.

Edit polls/admin.py thus:

from django.contrib import admin

# Register your models here.
from .models import Question, Choice

admin.site.register(Question)
admin.site.register(Choice)

You can now add questions and choices in the front-end. Try it out by adding an extra question with three choices.

You'll notice it's a bad user experience because it lists the choices for all questions mixed up together and there's no way to actually add a choice to a question, you have to add a choice and select which question it belongs to.

So basically we can define our own classes. Edit like this:

from django.contrib import admin

# Register your models here.
from .models import Question, Choice

class ChoiceInline(admin.TabularInline):
    model = Choice
    extra = 3

class QuestionAdmin(admin.ModelAdmin):
    fields = ['question_text', 'pub_date']
    inlines = [ChoiceInline]

admin.site.register(Question, QuestionAdmin)

Now, instead of it listing the choices seperately, the choices are listed and added as part of the Question.

Let's make a few more enhancements just to show off the available features. Add these lines to QuestionAdmin():

    # Make the list of questions include date and was_​published_​recently:
    list_display = ('question_text', 'pub_date', 'was_published_recently')

    # Add the ability to filter based on date:
    list_filter = ['pub_date']

    # Add the ability to search based on the question names:
    search_fields = ['question_text']

The Django admin interface has many features so please bookmark the Django admin site docs.

This concludes the Quickstart. But I hope you will read on because there is lots more to learn.

If you are using off-the-shelf apps (such as the admin app), you may want to customize how they look. Here you will learn how to do this by making modified copies of the templates.

Firstly we edit $SITENAME/settings.py. In the TEMPLATES section edit the 'DIRS' list, like this:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [os.path.join(BASE_DIR, 'templates')],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

That DIRS list is basically a search path for finding templates.

Create your new templates directory at the base of your project (the directory containing manage.py):

mkdir -p templates/polls

Now any template you put in there will override the one within the app. Copy polls/templates/polls/index.html to templates/polls. Now edit it by adding <h1>My poll site</h1> at the top.

🛈 if you want to customize the admin interface like this you'll have to find where the django source-code lives on your system and copy the template out of there.

Template inheritance allows us to have a HTML skeleton that is used by multiple pages (potentially accross multiple apps). This is useful both to keep the HTML boilerplate out of our other templates, and to apply persistent elements to all pages (such as a header or navigation).

Please bookmark the official template inheritance docs.

Edit all your templates with this at the beginning and end:

{% extends "base.html" %}
{% block content %}

...

{% endblock %}

🛈 delete the extra index.html you made in the last section, or just edit it as above

Now create your base.html in templates/ (or polls/templates/). Either way it's not namespaced which makes it available to all apps.

<!doctype html>
  
<html lang="en">
  <head>
    <meta charset="utf-8">
  
    <title>{% block title %}My poll site{% endblock %}</title>

    <meta name="description" content="What the animals on the farm eat.">
  
    <!-- Bootstrap CSS -->
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-EVSTQN3/azprG1Anm3QDgpJLIm9Nao0Yz1ztcQTwFspd3yD65VohhpuuCOmLASjC" crossorigin="anonymous">
  </head>
  <body>
    <header>
    </header>
    <main class="container">
        {% block content %}
        {% endblock %}
    </main>
    <footer>
    </footer>
      
    <!-- Bootstrap JS bundle -->
    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.0.2/dist/js/bootstrap.bundle.min.js" integrity="sha384-MrcW6ZMFYlzcLA8Nl+NtUVF0sA7MsXsP1UyJoMp4YLEuNSfAP+JcXn/tWtIaxVXM" crossorigin="anonymous"></script>
  </body>
</html>

We call this our skeleton. Things to note:

• the {% block %} sections may be overwritten by the child template
• we have added bootstrap's CSS and JS as per the bootstrap docs
• by applying the container class to our main, bootstrap will center our page

Now load your app in the browser. You will see that the source code now contains real HTML. And bootstrap is applying fonts and margins.

🛈 bootstrap allows you to apply all sorts of formatting with little effort. See some bootstrap examples.

We'll add our own stylesheet and have it apply a background image. This way you will learn not only how to insert static files into HTML but how static files can reference each-other.

The static directory needs to be namespaced just like the templates. Run this command to make it:

mkdir -p polls/static/polls/images

Create our CSS file at polls/static/polls/style.css:

body {
    background: white url("images/background.png") repeat;
}

Now put an image at polls/static/polls/images/background.png. If you like you may use this one checker background.

Open your base.html. Add this to the top of the file:

{% load static %}

And this to the <head> section

<link rel="stylesheet" type="text/css" href="{% static 'polls/style.css' %}">

🛈 you may need to restart your dev server for this to take effect

Now when you reload your site you should see your background.

So authentication support is included with Django and enabled by default in settings.py

• INSTALLED_APPS: django.contrib.auth & django.contrib.contenttypes
• MIDDLEWARE: SessionMiddleware & AuthenticationMiddleware

When you ran manage.py migrate, the Django auth app created the necessary database tables, and ensures that four default permissions – add, change, delete, and view – are created for each Django model defined in one of your installed applications.

Check that those are there:

python manage.py dbshell
select * from auth_permission;

Django provides several default views that you can use for handling login, logout, and password management. There are no default templates though. The template context is documented in each view, see the docs here.

We can easily include all the default views just by adding this to the list in projectname/urls.py.

path('accounts/', include('django.contrib.auth.urls')),

This gives us a whole bunch of url patterns such as:

• accounts/login
• accounts/logout
• accounts/password_​change
• accounts/password_​reset

The default template for /accounts/login/ is registration/login.html. See the url docs for more details on that.

Install this example login template at templates/registration/login.html (the templates directory at the root of your repo that we made when we learned how to overwrite an apps templates).

{% extends "base.html" %}
{% block content %}

{% if form.errors %}
<p>Your username and password didn't match. Please try again.</p>
{% endif %}

{% if next %}
    {% if user.is_authenticated %}
    <p>Your account doesn't have access to this page. To proceed,
    please login with an account that has access.</p>
    {% else %}
    <p>Please login to see this page.</p>
    {% endif %}
{% endif %}

<form method="post" action="{% url 'login' %}">
{% csrf_token %}
<table>
<tr>
    <td>{{ form.username.label_tag }}</td>
    <td>{{ form.username }}</td>
</tr>
<tr>
    <td>{{ form.password.label_tag }}</td>
    <td>{{ form.password }}</td>
</tr>
</table>

<input type="submit" value="login">
<input type="hidden" name="next" value="{{ next }}">
</form>

{# Assumes you set up the password_reset view in your URLconf #}
<p><a href="{% url 'password_reset' %}">Lost password?</a></p>

{% endblock %}

Check you can see that by running your development server and hitting accounts/login.

Now we simply add a decorator to the views we want to be authenticated. Edit your polls/views.py, adding the import and a decorator before your detail and vote views:

from django.contrib.auth.decorators import login_required

...

@login_required
def detail(request, question_id):

...

@login_required
def vote(request, question_id):

You need to restart your development server for these changes to take effect. Now try to vote on a poll. It will redirect you to the login page \o/

🛈 if you don't get redirected to the login page, likely you are already logged in. go to /admin/ and logout.

You can make yourself a user to login as using the admin app.

As I said authentication is a big topic and Django provides lots of stuff and I can't cover all of it here. But I give you some tasters of the cool stuff you can do:

Example: Use two decorators to restrict access to certain users:

from django.contrib.auth.decorators import login_required, permission_required

@login_required
@permission_required('polls.add_choice', raise_exception=True)
def my_view(request):
    ...

Example: Define a function to perform your own check:

from django.contrib.auth.decorators import user_passes_test

def email_check(user):
    return user.email.endswith('@example.com')

@user_passes_test(email_check)
def my_view(request):
    ...

Example: check permissions against the model:

user.has_perm('foo.add_bar')
user.has_perm('foo.change_bar')
user.has_perm('foo.delete_bar')
user.has_perm('foo.view_bar')

Example: by default our settings.py has django.contrib.auth.context_processors.auth, which means variables user and perms are available in templates:

{% if user.is_authenticated %}
    <p>Welcome, {{ user.username }}. Thanks for logging in.</p>
{% else %}
    <p>Welcome, new user. Please log in.</p>
{% endif %}

Or:

{% if perms.foo %}
    <p>You have permission to do something in the foo app.</p>
    {% if perms.foo.add_vote %}
        <p>You can vote!</p>
    {% endif %}
    {% if perms.foo.add_driving %}
        <p>You can drive!</p>
    {% endif %}
{% else %}
    <p>You don't have permission to do anything in the foo app.</p>
{% endif %}

In addition to local testing you will want a staging environment. A test environment in Heroku to validate your app works as expected before pushing changes to production.

This is managed by adding extra git remotes, linked to different sites.

First rename the remote we made before to have a less generic name. I use "prod" for "production". And turn of debug.

git remote rename heroku prod
heroku config:set DEBUG=false

Create the new site. It's a staging env so I call it $HEROKUNAME-stage, with a git remote called "stage".

heroku create $HEROKUNAME-stage -r stage
git remote -v
heroku config:set SECRET_KEY="$(openssl rand -base64 32)" -a $HEROKUNAME-stage
heroku config:set DEBUG=true -a $HEROKUNAME-stage
heroku addons:create heroku-postgresql:hobby-dev -a $HEROKUNAME-stage
git push stage main:main
heroku run python manage.py migrate -a $HEROKUNAME-stage
heroku run python manage.py createsuperuser -a $HEROKUNAME-stage

Cool so we now have two remotes, one called "prod" and one called "stage". Remember these as you will use these names to push all future changes like so:

git push stage main:main
git push prod main:main

Henceforth, when running heroku commands, you will need to identify which app you are refering to with -a, for example:

heroku config -a $HEROKUNAME
heroku config -a $HEROKUNAME-stage

You will want to be able to pull data back from prod to dev so you can work with realistic data.

Before you try this, make sure you have some unique data in your prod environment to pull down.

First, we get the database details of our staging environment:

heroku config:get DATABASE_URL -a $HEROKUNAME-stage

OK good now you know the deets please use them in this command:

DEETS=

# empty staging db
heroku pg:reset -a $HEROKUNAME-stage

# copy prod db to staging db
heroku pg:pull DATABASE_URL $DEETS -a $HEROKUNAME

DATABASE_URL will automatically refer to your app's live database because you only have one.

Now we will pull that down to a database on the local Postgres installation. Decide on a name for your local database and use it in the below command.

LOCALDBNAME=
heroku pg:pull DATABASE_URL $LOCALDBNAME -a $HEROKUNAME

Please bookmark the Heroku Postgres CLI docs for future reference.

For when you havn't worked on your app for a few weeks and forget how everything works.

Activate your environment:

cd $SITENAME
pipenv shell
heroku login

Start your local development server:

heroku local

Push it to your heroku staging environment:

git commit
git push stage localbranch:main

If you edit your models:

python manage.py migrate
python manage.py migrate -a $HEROKUNAME-stage

So you want to add your friend so they can contribute too?

First setup a repository on GitHub or Gitlab as remote origin for your code and push it. Then send your friend a Heroku invite using the docs.

Now your friend needs to: