In this chapter we’ll build, test, and deploy a Pages app that has a homepage and an about page. We’ll also learn about Django’s class-based views and templates which are the building blocks for the more complex web applications built later on in the book.

Initial Setup

As in Chapter 2, our initial set up involves the following steps:

  • create a directory for our code
  • install Django in a new virtual environment
  • create a new Django project
  • create a new pages app
  • update settings.py

On the command line make sure you’re not working in an existing virtual environment. You can tell if there’s anything in parentheses before your command line prompt. If you are simply type exit to leave it.

We will again create a new directory pages for our project on the Desktop but you can put your code anywhere you like on your computer. It just needs to be in its own directory.

Within a new command line console start by typing the following:

$ cd ~/Desktop
$ mkdir pages
$ cd pages
$ pipenv install django==2.2.5
$ pipenv shell
(pages) $ django-admin startproject pages_project .
(pages) $ python manage.py startapp pages

Open your text editor and navigate to the file settings.py. Add the pages app at the bottom of our project under INSTALLED_APPS:

# pages_project/settings.py
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'pages.apps.PagesConfig', # new
]

Start the local web server with runserver.

(pages) $ python manage.py runserver

And then navigate to http://127.0.0.1:8000/.

Django welcome page

Templates

Every web framework needs a convenient way to generate HTML files and in Django, the approach is to use templates so that individual HTML files can be served by a view to a web page specified by the URL.

Recall that in the previous chapter our “Hello, World” site had the phrase hardcoded into a views.py file as a string. That technically works but doesn’t scale well! A better approach is to link a view to a template, thereby separating the information contained in each.

In this chapter we’ll learn how to use templates to more easily create our desired homepage and about page. And in future chapters, the use of templates will support building websites that can support hundreds, thousands, or even millions of webpages with a minimal amount of code.

The first consideration is where to place templates within the structure of a Django project. There are two options. By default, Django’s template loader will look within each app for related templates. However the structure is somewhat confusing: each app needs a new templates directory, another directory with the same name as the app, and then the template file.

Therefore in our pages app, Django would expect the following layout:

└── pages
    ├── templates
        ├── pages
            ├── home.html

This means we would need to create a new templates directory, a new directory with the name of the app, pages, and finally our template itself.

Why this seemingly repetitive approach? The short answer is that the Django template loader wants to be really sure it finds the correct template! What happens if there are home.html files within two separate apps? This structure makes sure there are no such conflicts.

There is, however, another approach which is to instead create a single project-level templates directory and place all templates within there. By making a small tweak to our settings.py file we can tell Django to also look in this directory for templates. That is the approach we’ll use.

First quit our server with the Control-c command. Then create a project-level folder called templates and an HTML file called home.html.

(pages) $ mkdir templates
(pages) $ touch templates/home.html

Next we need to update settings.py to tell Django the location of our new templates directory. This is a one-line change to the setting 'DIRS' under TEMPLATES.

# pages_project/settings.py
TEMPLATES = [
    {
        ...
        'DIRS': [os.path.join(BASE_DIR, 'templates')], # new
        ...
    },
]

Then we can add a simple headline to our home.html file.

<!-- templates/home.html -->
<h1>Homepage</h1>

Ok, our template is complete! The next step is to configure our url and view files.

Class-Based Views

Early versions of Django only shipped with function-based views, but developers soon found themselves repeating the same patterns over and over again. Write a view that lists all objects in a model. Write a view that displays only one detailed item from a model. And so on.

Function-based generic views were introduced to abstract these patterns and streamline development of common patterns. However there was no easy way to extend or customize these views. As a result, Django introduced class-based generic views that make it easy to use and also extend views covering common use cases.

Classes are a fundamental part of Python but a thorough discussion of them is beyond the scope of this book. If you need an introduction or refresher, I suggest reviewing the official Python docs which have an excellent tutorial on classes and their usage.

In our view we’ll use the built-in TemplateView to display our template. Update the pages/views.py file.

# pages/views.py
from django.views.generic import TemplateView


class HomePageView(TemplateView):
    template_name = 'home.html'

Note that we’ve capitalized our view, HomePageView, since it’s now a Python class. Classes, unlike functions, should always be capitalized. The TemplateView already contains all the logic needed to display our template, we just need to specify the template’s name.

URLs

The last step is to update our URLConfs. Recall from Chapter 2 that we need to make updates in two locations. First, we update the pages_project/urls.py file to point at our pages app and then within pages we match views to URL routes.

Let’s start with the project-level urls.py file.

# pages_project/urls.py
from django.contrib import admin
from django.urls import path, include # new

urlpatterns = [
    path('admin/', admin.site.urls),
    path('', include('pages.urls')), # new
]

The code here should be review at this point. We add include on the second line to point the existing URL to the pages app. Next create an app-level urls.py file.

(pages) $ touch pages/urls.py

And add the following code.

# pages/urls.py
from django.urls import path

from .views import HomePageView

urlpatterns = [
    path('', HomePageView.as_view(), name='home'),
]

This pattern is almost identical to what we did in Chapter 2 with one major difference: when using Class-Based Views, you always add as_view() at the end of the view name.

And we’re done! If you start up the web server with python manage.py runserver and navigate to http://127.0.0.1:8000/ you can see our new homepage.

Homepage

Add an About Page

The process for adding an about page is very similar to what we just did. We’ll create a new template file, a new view, and a new url route.

Quit the server with Control+c and create a new template called about.html.

(pages) $ touch templates/about.html

Then populate it with a short HTML headline.

<!-- templates/about.html -->
<h1>About page</h1>

Create a new view for the page.

# pages/views.py
from django.views.generic import TemplateView


class HomePageView(TemplateView):
    template_name = 'home.html'


class AboutPageView(TemplateView): # new
    template_name = 'about.html'

And then connect it to a url at about/.

# pages/urls.py
from django.urls import path

from .views import HomePageView, AboutPageView # new

urlpatterns = [
    path('about/', AboutPageView.as_view(), name='about'), # new
    path('', HomePageView.as_view(), name='home'),  
]

Start up the web server with python manage.py runserver, navigate to http://127.0.0.1:8000/about, and you can see our new “About page”.

About page

Extending Templates

The real power of templates is their ability to be extended. If you think about most web sites, there is content that is repeated on every page (header, footer, etc). Wouldn’t it be nice if we, as developers, could have one canonical place for our header code that would be inherited by all other templates?

Well we can! Let’s create a base.html file containing a header with links to our two pages. Type Control+c and then create the new file.

(pages) $ touch templates/base.html

Django has a minimal templating language for adding links and basic logic in our templates. You can see the full list of built-in template tags here in the official docs. Template tags take the form of {% something %} where the “something” is the template tag itself. You can even create your own custom template tags, though we won’t do that in this book.

To add URL links in our project we can use the built-in url template tag which takes the URL pattern name as an argument. Remember how we added optional URL names to our two routes in pages/urls.py? This is why. The url tag uses these names to automatically create links for us.

The URL route for our homepage is called home therefore to configure a link to it we would use the following: {% url 'home' %}.

<!-- templates/base.html -->
<header>
  <a href="{% url 'home' %}">Home</a> | <a href="{% url 'about' %}">About</a>
</header>

{% block content %}
{% endblock %}

At the bottom we’ve added a block tag called content. Blocks can be overwritten by child templates via inheritance. While it’s optional to name our closing endblock–you can just write {% endblock %} if you prefer–doing so helps with readability, especially in larger template files.

Let’s update our home.html and about.html files to extend the base.html template. That means we can reuse the same code from one template in another template. The Django templating language comes with an extends method that we can use for this.

<!-- templates/home.html -->
{% extends 'base.html' %}

{% block content %}
<h1>Homepage</h1>
{% endblock content %}

<!-- templates/about.html -->
{% extends 'base.html' %}

{% block content %}
<h1>About page</h1>
{% endblock %}

Now if you start up the server with python manage.py runserver and open up our web pages again at http://127.0.0.1:8000/ and http://127.0.0.1:8000/about you’ll see the header is magically included in both locations.

Nice, right?

Homepage with header

About page with header

There’s a lot more we can do with templates and in practice you’ll typically create a base.html file and then add additional templates on top of it in a robust Django project. We’ll do this later on in the book.

Tests

Finally we come to tests. Even in an application this basic, it’s important to add tests and get in the habit of always adding them to our Django projects. In the words of Jacob Kaplan-Moss, one of Django’s original creators, “Code without tests is broken as designed.”

Writing tests is important because it automates the process of confirming that the code works as expected. In an app like this one, we can manually look and see that the home page and about page exist and contain the intended content. But as a Django project grows in size there can be hundreds if not thousands of individual web pages and the idea of manually going through each page is not possible. Further, whenever we make changes to the code–adding new features, updating existing ones, deleting unused areas of the site–we want to be sure that we have not inadvertently broken some other piece of the site. Automated tests let us write one time how we expect a specific piece of our project to behave and then let the computer do the checking for us.

And fortunately Django comes with robust, built-in testing tools for writing and running tests.

If you look within our pages app, Django already provided a tests.py file we can use. Open it and add the following code:

# pages/tests.py
from django.test import SimpleTestCase


class PagesTests(SimpleTestCase):
    def test_home_page_status_code(self):
        response = self.client.get('/')
        self.assertEqual(response.status_code, 200)

    def test_about_page_status_code(self):
        response = self.client.get('/about/')
        self.assertEqual(response.status_code, 200)

We’re using SimpleTestCase here since we aren’t using a database. If we were using a database, we’d instead use TestCase. Then we perform a check if the status code for each page is 200, which is the standard response for a successful HTTP request. That’s a fancy way of saying it ensures that a given web page actually exists, but says nothing about the content of said page.

To run the tests quit the server Control+c and type python manage.py test on the command line:

(pages) $ python manage.py test
Creating test database for alias 'default'...
System check identified no issues (0 silenced).
..
----------------------------------------------------------------------
Ran 2 tests in 0.014s

OK
Destroying test database for alias 'default'...

Success! We’ll do much more with testing in the future, especially once we start working with databases. For now, it’s important to see how easy it is to add tests each and every time we add new functionality to our Django project.

Git and GitHub

It’s time to track our changes with git and push them up to GitHub. We’ll start by initializing our directory.

(pages) $ git init

Use git status to see all our code changes then git add -A to add them all. Finally we’ll add our first commit message.

(pages) $ git status
(pages) $ git add -A
(pages) $ git commit -m 'initial commit'

Over on GitHub create a new repo. Its repository name will be pages-app and make sure to select the “Private” radio button and then click on the “Create repository” button.

On the next page scroll down to where it says “…or push an existing repository from the command line.” Copy and paste the two commands there into your terminal.

It should look like the below albeit instead of wsvincent as the username it will be your GitHub username.

(pages) $ git remote add origin https://github.com/wsvincent/pages-app.git
(pages) $ git push -u origin master

Local vs Production

Up to this point we’ve been using Django’s own internal web server to power our Pages application locally on our computer. But you can’t share a localhost address with someone else. To make our site available on the Internet where everyone can see it, we need to deploy our code to an external server that anyone can use to see our site. This is called putting our code into production. Local code lives only on our computer; production code lives on an external server available to everyone.

There are many server providers available but we will use Heroku because it is free for small projects, widely-used, and has a relatively straightforward deployment process.

Heroku

You can sign up for a free Heroku account on their website. After you confirm your email Heroku will redirect you to the dashboard section of the site.

Heroku dashboard

Now we need to install Heroku’s Command Line Interface (CLI) so we can deploy from the command line. We want to install Heroku globally so it is available across our entire computer. Open up a new command line tab: Command+t on a Mac, Control+t on Windows. If we installed Heroku within our virtual environment, it would only be available there.

Within this new tab, on a Mac use Homebrew to install Heroku:

$ brew install heroku/brew/heroku

On Windows, see the Heroku CLI page to correctly install either the 32-bit or 64-bit version. If you are using Linux there are specific install instructions available on the Heroku website.

Once installation is complete you can close our new command line tab and return to the initial tab with the pages virtual environment active.

Type the command heroku login and use the email and password for Heroku you just set.

(pages) $ heroku login
Enter your Heroku credentials:
Email: will@wsvincent.com
Password: *********************************
Logged in as will@wsvincent.com

Additional Files

We need to make the following four changes to our Pages project so it’s ready to deploy online with Heroku:

  • update Pipfile.lock
  • make a new Procfile file
  • install Gunicorn as our web server
  • make a one-line change to settings.py file

Within your existing Pipfile specify the version of Python we’re using, which is 3.7. Add these two lines at the bottom of the file.

# Pipfile
[requires]
python_version = "3.7"

Then run pipenv lock to generate the appropriate Pipfile.lock.

(pages) $ pipenv lock

Heroku actually looks in our Pipfile.lock for information on our virtual environment, which is why we add the language setting here.

Next create a Procfile, which is a configuration file specific to Heroku.

(pages) $ touch Procfile

Open the Procfile with your text editor and add the following:

web: gunicorn pages_project.wsgi --log-file -

This says to use gunicorn, which is a web server suitable for production, instead of Django’s own server which is only suitable for local development. Install it using Pipenv.

(pages) $ pipenv install gunicorn==19.9.0

The configuration for the server is contained in a wsgi.py file that Django automatically creates for every new project. It resides at the top-most, project level of our code. Since our project’s name is pages_project the file is located at pages_project/wsgi.py file.

The final step is a one-line change to settings.py. Scroll down to the section called ALLOWED_HOSTS and add a '*' so it looks as follows:

# pages_project/settings.py
ALLOWED_HOSTS = ['*']

The ALLOWED_HOSTS setting represents which host/domain names our Django site can serve. This is a security measure to prevent HTTP Host header attacks, which are possible even under many seemingly-safe web server configurations. However we’ve used the wildcard asterisk * which means all domains are acceptable to keep things simple. In a production-level Django site you would explicitly list which domains were allowed.

Use git status to check our changes, add the new files, and then commit them:

(pages) $ git status
(pages) $ git add -A
(pages) $ git commit -m "New updates for Heroku deployment"

Finally push to GitHub so we have an online backup of our code changes.

(pages) $ git push -u origin master

Deployment

The last step is to actually deploy with Heroku. If you’ve ever configured a server yourself in the past, you’ll be amazed at how much simpler the process is with a platform-as-a-service provider like Heroku.

Our process will be as follows:

  • create a new app on Heroku and push our code to it
  • add a git remote “hook” for Heroku
  • configure the app to ignore static files, which we’ll cover in later chapters
  • start the Heroku server so the app is live
  • visit the app on Heroku’s provided URL

We can do the first step, creating a new Heroku app, from the command line with heroku create. Heroku will create a random name for our app, in my case fathomless-hamlet-26076. Your name will be different.

(pages) $ heroku create
Creating app... done, ⬢ fathomless-hamlet-26076
https://fathomless-hamlet-26076.herokuapp.com/ |
https://git.heroku.com/fathomless-hamlet-26076.git

We only need to do one set of Heroku configurations at this point, which is to tell Heroku to ignore static files like CSS and JavaScript which Django by default tries to optimize for us. We’ll cover this in later chapters so for now just run the following command.

(pages) $ heroku config:set DISABLE_COLLECTSTATIC=1

Now we can push our code to Heroku.

(pages) $ git push heroku master

If we just typed git push origin master, then the code would have been pushed to GitHub, not Heroku. Adding heroku to the command sends the code to Heroku. This is a little confusing the first few times.

Finally, we need to make our Heroku app live. As websites grow in traffic they need additional Heroku services but for our basic example we can use the lowest level, web=1, which also happens to be free!

Type the following command.

(pages) $ heroku ps:scale web=1

We’re done! The last step is to confirm our app is live and online. If you use the command heroku open your web browser will open a new tab with the URL of your app:

(pages) $ heroku open

Mine is at https://fathomless-hamlet-26076.herokuapp.com/. You can see the homepage is up:

Homepage on Heroku

As is the about page:

About page on Heroku

Conclusion

Congratulations on building and deploying your second Django project! This time we used templates, class-based views, explored URLConfs more fully, added basic tests, and used Heroku.

Next up we’ll move on to our first database-backed project and see where Django really shines. Continue on to Chapter 4: Message Board app.



This concludes the free sample chapters of the book. There are 12 more…

The complete book features 15 chapters and goes in-depth on how to build both a blog app with user authentication and a newspaper site with articles and comments. Additional concepts covered include custom user models, Bootstrap for styling, password change and reset, sending email, permissions, foreign keys, and more.