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 new 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.1.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. 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.

It’s worth repeating this pattern since you’ll see it over and over again in Django development: Templates, Views, and URLs. The order in which you create them doesn’t much matter since all three are required and work closely together. The URLs control the initial route, the entry point into a page, such as /about, the views contain the logic or the “what”, and the template has the HTML. For web pages that rely on a database model, it is the view that does much of the work to decide what data is available to the template.

So: Templates, Views, URLs. This pattern will hold true for every Django web page you make. However it will take some repetition before you internalize it.

Ok, moving on. The question of where to place the templates directory can be confusing for beginners. By default, Django looks within each app for templates. In our pages app it will expect a home.html template to be located in the following location:

└── 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.

A common question is: Why this repetitive structure? The short answer is that the Django template loader wants to be really sure it finds the correct template and this is how it’s programmed to look for them.

Fortunately there’s another often-used approach to structuring the templates in a Django project. And that is to instead create a single, project-level templates directory that is available to all apps. This is the approach we’ll use. By making a small tweak to our settings.py file we can tell Django to also look in this project-level folder for templates.

First quit our server with Control-c. 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 to look at the project-level for templates. 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.

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 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 project-level urls.py file to point at our pages app and then within pages we match the views to 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):
    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. First Control+c and then type the following.

(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 url routers? 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 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.

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 Bitbucket

It’s time to track our changes with git and push them up to Bitbucket. 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 Bitbucket create a new repo which we’ll call pages-app.

Bitbucket Create Page

On the next page, look for the commands under “Step 2: Connect your existing repository to Bitbucket.” Copy the two commands to your command line to link the repo and then push the repository to Bitbucket.

Bitbucket Existing Project

It should look like this, replacing wsvincent with your Bitbucket username:

(pages) $ git remote add origin git@bitbucket.org: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.

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, so 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 aone-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 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.

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 here, the file is located at pages_project/wsgi.py file.

(pages) $ pipenv install gunicorn==19.9.0

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 Bitbucket so we have an online backup of our code changes.

(pages) $ git push -u origin master

Deploy

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

Now we need to add a “hook” for Heroku within git. This means that git will store both our settings for pushing code to Bitbucket and to Heroku. My Heroku app is called cryptic-oasis-40349 so my command is as follows.

(pages) $ heroku git:remote -a fathomless-hamlet-26076

You should replace fathomless-hamlet-26076 with the app name Heroku provides.

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. Because we set our “hook” previously, it will go to Heroku.

(pages) $ git push heroku master

If we just typed git push origin master then the code is pushed to Bitbucket, 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 both 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.