I'm a web developer in Norfolk. This is my blog...

At work I use the Skeleton boilerplate a lot - my boss, who handles most of the design work, likes it and generally uses it for his designs. I’ve also been using Grunt a lot lately, so it was inevitable that I’d probably start to look for a Yeoman generator for working with it.

There was an existing Yeoman generator for Skeleton, but it didn’t really do what I wanted. I wanted something that:

Included jQuery and Modernizr

Automatically concatenates and minifies all the JavaScript and CSS

Will automatically rebuild on changes

Includes LiveReload and a development server

Includes automatic deployment via FTP

After looking through the documentation for Yeoman, it was actually quick and easy to throw together my own generator and put it up. It’s available here, and the GitHub repository is here.

Future plans for it include:

Adding auto-prefixing for CSS

Removing redundant CSS rules automatically

Possibly, alternate deployment methods

Frustratingly, NPM seems to be playing up at present - it’s not picking up the README file, and the Yeoman site isn’t pulling it in. Any idea why, anyone?

Flat pages

Django ships with a number of useful apps - we’ve already used the admin interface. The flat pages app is another very handy app that comes with Django, and we’ll use it to allow the blog author to create a handful of flat pages.

First of all, you’ll need to install the flatpages app. Edit the INSTALLED_APPS setting as follows:

INSTALLED_APPS = (

'django.contrib.admin',

'django.contrib.auth',

'django.contrib.contenttypes',

'django.contrib.sessions',

'django.contrib.messages',

'django.contrib.staticfiles',

'south',

'blogengine',

'django.contrib.sites',

'django.contrib.flatpages',

)

Note that we needed to enable the sites framework as well. You’ll also need to set the SITE_ID setting:

SITE_ID = 1

With that done, run python manage.py syncdb to create the required database tables. Now, let’s use the sqlall command to take a look at the database structure generated for the flat pages:

As mentioned previously, all models in Django have an id attribute by default. Each flat page also has a URL, title, and content.

Also note the separate django_flatpage_sites table, which maps sites to flat pages. Django can run multiple sites from the same web app, and so flat pages must be allocated to a specific site. This relationship is a many-to-many relationship, so one flat page can appear on more than one site.

The other fields are hidden by default in the admin and can be ignored. Let’s have a go with Django’s handy shell to explore the flatpage. Run python manage.py shell and you’ll be able to interact with your Django application interactively:

Type "help", "copyright", "credits" or "license" for more information.

(InteractiveConsole)

>>> from django.contrib.flatpages.models import *

>>> FlatPage

<class 'django.contrib.flatpages.models.FlatPage'>

>>> from django.contrib.sites.models import Site

>>> Site.objects.all()

[<Site: example.com>]

As you can see, flatpages is a Django app similar to the blogengine one, with its own models, as is sites. You can see that the FlatPage class is a model. We can create an instance of it and save it interactively:

>>> f = FlatPage()

>>> f.url = '/about/'

>>> f.title = 'About me'

>>> f.content = 'All about me'

>>> f.save()

>>> f.sites.add(Site.objects.all()[0])

>>> f.save()

Note that because the relationship between the site and the flat page is a many-to-many relationship, we need to save it first, then use the add method to add the site to the list of sites.

We can retrieve it:

>>> FlatPage.objects.all()

[<FlatPage: /about/ -- About me>]

>>> FlatPage.objects.all()[0]

<FlatPage: /about/ -- About me>

>>> FlatPage.objects.all()[0].title

u'About me'

This command is often handy for debugging problems with your models interactively. If you now run the server and visit the admin, you should notice that the Flatpages app is now visible there, and the ‘About me’ flat page is now shown in there.

Let’s also take a look at the SQL required for the Site model. Run python manage.py sqlall sites:

BEGIN;

CREATETABLE"django_site" (

"id"integerNOTNULL PRIMARY KEY,

"domain"varchar(100) NOTNULL,

"name"varchar(50) NOTNULL

)

;

COMMIT;

Again, very simple - just a domain and a name.

So, now that we have a good idea of how the flat page system works, we can write a test for it. We don’t need to write unit tests for the model because Django already does that, but we do need to write an acceptance test to ensure we can create flat pages and they will be where we expect them to be. Add the following to the top of the test file:

from django.contrib.flatpages.models import FlatPage

from django.contrib.sites.models import Site

Now, before we write this test, there’s some duplication to resolve. We have two tests that subclass LiveServerTestCase, and both have the same method, setUp. We can save ourselves some hassle by creating a new class containing this method and having both these tests inherit from it. We’ll do that now because the flat page test can also be based on it. Create the following class just after PostTest:

classBaseAcceptanceTest(LiveServerTestCase):

defsetUp(self):

self.client = Client()

Then remove the setUp method from each of the two tests based on LiveServerTestCase, and change their parent class to BaseAcceptanceTest:

classAdminTest(BaseAcceptanceTest):

classPostViewTest(BaseAcceptanceTest):

With that done, run the tests and they should pass. Commit your changes:

Our test still fails, but we can easily see why - the template flatpages/default.html doesn’t exist. So we create it:

{% extends "blogengine/includes/base.html" %}

{% load custom_markdown %}

{% block content %}

<divclass="post">

<h1>{{ flatpage.title }}</h1>

{{ flatpage.content|custom_markdown }}

</div>

{% endblock %}

This template is based on the blog post one, and just changes a handful of variable names. Note that it can still inherit from the blogengine base template, and in this case we’re using that for the sake of consistency.

If you run your tests, you should now see that they pass, so we’ll commit our changes:

$ git add templates/ django_tutorial_blog_ng/ blogengine/

$ git commit -m 'Implemented flat page support'

Multiple authors

Next we’ll add support for multiple authors. Now, Django already has a User model, and we’ll leverage that to represent the authors. But first we’ll write our test:

Here we create a User object to represent the author. Note the create_user convenience method for creating new users quickly and easily.

We’re going to exclude the author field from the admin - instead it’s going to be automatically populated based on the session data, so that when a user creates a post they are automatically set as the author. We therefore don’t need to make any changes for the acceptance tests for posts - our changes to the unit tests for the Post model are sufficient.

Now, if you want to use the Django comment system, you can do so, and it shouldn’t be too hard to puzzle out how to implement it using the documentation and my prior post. However, in my humble opinion, using a third-party comment system is the way to go for blog comments - they make it extremely easy for people to log in with multiple services without you having to write lots of additional code. They also make it significantly easier to moderate comments, and they’re generally pretty good at handling comment spam.

Now, the Facebook comment system requires that you pass through the absolute page URL when initialising the comments. At present we can’t do that without hard-coding the domain name in our template, which we want to avoid. So, we need to add a site field to each post to identify the site it’s associated with.

All we’ve done here is to add the site attribute when creating a new post using the Django database API, and when we create one via the admin, we add an additional site aparameter to the HTTP POST request with a value of 1. Run the tests and they should fail:

Welcome back! In this lesson, we’ll use Twitter Bootstrap to make our blog look nicer, and we’ll implement individual pages for each post.

Now, before we get started, don’t forget to switch into your virtualenv. From within the directory for the project, run the following command:

$ source venv/bin/activate

If you haven’t used Bootstrap before, you’re in for a treat. With Bootstrap, it’s easy to make a good-looking website quickly that’s responsive and mobile-friendly. We’ll also use HTML5 Boilerplate to get a basic HTML template in place.

Now, to install these easily, we’ll use Bower, which requires Node.js. Install Node.js first. On most Linux distros, you’ll also need to set NODE_PATH, which can be done by pasting the following into your .bashrc:

NODE_PATH="/usr/local/lib/node_modules"

With that done, run the following command to install Bower:

$ sudo npm install -g bower

Next we need to create a Bower config. First, create the folder blogengine/static. Then create a new file called .bowerrc and paste in the following content:

{

"directory": "blogengine/static/bower_components"

}

This tells Bower where it should put downloaded libraries. Next, run the following command to gener Bower:

$ bower init

Answer all the questions it asks you - for those with defaults, these should be fine, and everything else should be easy enough. Next, run the following command to install Bootstrap and HTML5 Boilerplate:

$ bower install bootstrap html5-boilerplate --save

Note that as jQuery is a dependency of Bootstrap, it will also be installed automatically. Now, we need to keep our Bower-installed files out of version control - the bower.json file keeps track of them for us. So add the following to your .gitignore file:

blogengine/static/bower_components/

All done? Let’s commit our changes:

$ git add .gitignore .bowerrc bower.json

$ git commit -m 'Added Bower config'

Now, let’s make our template nicer. Django’s templating system is very powerful and lets one template inherit from another. We’re going to create a base template, using HTML5 Boilerplate as a starting point, that all of our web-facing pages will use. First, create a directory to hold the base template:

$ mkdir templates/blogengine/includes

Then copy the index.html file from HTML5 Boilerplate to this directory as base.html:

We need to use {% load staticfiles %} to be able to load any static files.

We use the {% static %} template tag to load static files such as CSS and HTML

We define blocks called title and content. Any template that extends this one can override whatever is inside this template.

Please note that HTML5 Boilerplate may conceivable change in future, so bear in mind that all you really need to do is load the staticfiles app, use the static tag for any static files that need to be loaded, and define the blocks in the appropriate places.

Next, let’s amend our existing template to inherit from this one:

{% extends "blogengine/includes/base.html" %}

{% block content %}

{% for post in object_list %}

<h1>{{ post.title }}</h1>

<h3>{{ post.pub_date }}</h3>

{{ post.text }}

{% endfor %}

{% endblock %}

Now fire up the server with python manage.py runserver and check everything is working OK. You should see that your new base template is now in use and the CSS and JS files are being loaded correctly. Let’s commit again:

Note the footer copyright section. Here we output the current year using now. Also note the addition of the header block. This will let us override the page header if necessary.

We’ll also wrap the posts in a div:

{% extends "blogengine/includes/base.html" %}

{% block content %}

{% for post in object_list %}

<divclass="post">

<h1>{{ post.title }}</h1>

<h3>{{ post.pub_date }}</h3>

{{ post.text }}

</div>

{% endfor %}

{% endblock %}

Let’s commit our changes:

$ git add templates/

$ git commit -m 'Amended templates'

Formatting our content

As it stands right now, we can’t do much to format our posts. It is possible to include HTML in our posts with Django, but by default it will strip it out. Also, we don’t want users to have to write HTML manually - we want to make our blog user friendly!

There are two possible approaches. One is to embed a rich text editor like TinyMCE in the admin and use that for editing the files, but I’ve found things like that to be cumbersome. The alternative is to use some other form of lightweight markup, and that’s the approach we’ll take here. We’re going to use Markdown for editing our posts.

Django has actually dropped support for Markdown, but it’s not hard to implement your own version. First, install Markdown and add it to your requirements.txt:

$ pip install markdown

$ pip freeze > requirements.txt

Now, we shouldn’t write any production code before writing a test, so let’s amend our existing post test to check to see that Markdown is working as expected:

What we do here is we convert our post text to include a link using Markdown. We also need to render that post in markdown within the test so that what we have in the test matches what will be produced - otherwise our test will be broken. We also check that the link is marked up correctly.

Save the file and run the tests - they should fail. Now, create the following directory and file:

$ mkdir blogengine/templatetags

$ touch blogengine/templatetags/__init__.py

Note that the __init__.py file is meant to be blank.

Then create the following file and edit it to look like this:

import markdown

from django import template

from django.template.defaultfilters import stringfilter

from django.utils.encoding import force_unicode

from django.utils.safestring import mark_safe

register = template.Library()

@register.filter(is_safe=True)

@stringfilter

defcustom_markdown(value):

extensions = ["nl2br", ]

return mark_safe(markdown.markdown(force_unicode(value),

extensions,

safe_mode=True,

enable_attributes=False))

Then just amend the post list template to use it:

{% extends "blogengine/includes/base.html" %}

{% load custom_markdown %}

{% block content %}

{% for post in object_list %}

<divclass="post">

<h1>{{ post.title }}</h1>

<h3>{{ post.pub_date }}</h3>

{{ post.text|custom_markdown }}

</div>

{% endfor %}

{% endblock %}

It’s that easy to use a custom markup system with your blog!

Let’s commit the changes:

$ git add requirements.txt templates/ blogengine/

$ git commit -m 'Added Markdown support'

Pagination

As at right now, all of our posts are displayed on the index page. We want to fix that by implementing pagination. Fortunately, that’s very easy for us because we’re using Django’s generic views. Go into blogengine/urls.py and amend it as follows:

from django.conf.urls import patterns, url

from django.views.generic import ListView

from blogengine.models import Post

urlpatterns = patterns('',

# Index

url(r'^(?P<page>\d+)?/?$', ListView.as_view(

model=Post,

paginate_by=5,

)),

)

That will automatically paginate our posts by 5 - feel free to change the value of paginate_by if you wish. However, we need to place the links in our template as well:

{% extends "blogengine/includes/base.html" %}

{% load custom_markdown %}

{% block content %}

{% for post in object_list %}

<divclass="post">

<h1>{{ post.title }}</h1>

<h3>{{ post.pub_date }}</h3>

{{ post.text|custom_markdown }}

</div>

{% endfor %}

{% if page_obj.has_previous %}

<ahref="/{{ page_obj.previous_page_number }}/">Previous Page</a>

{% endif %}

{% if page_obj.has_next %}

<ahref="/{{ page_obj.next_page_number }}/">Next Page</a>

{% endif %}

{% endblock %}

Try adding a few more blog posts, and you’ll see the pagination links. But give them a try, and they won’t work. Why not? Well, as it turns out there was a bug in the project-wide urls.py file (my bad!). Let’s fix that:

from django.conf.urls import patterns, include, url

from django.contrib import admin

admin.autodiscover()

urlpatterns = patterns('',

# Examples:

# url(r'^$', 'django_tutorial_blog_ng.views.home', name='home'),

# url(r'^blog/', include('blog.urls')),

url(r'^admin/', include(admin.site.urls)),

# Blog URLs

url(r'', include('blogengine.urls')),

)

If you try again, you’ll see that the blogengine app now happily deals with the paginated posts. Let’s commit our changes:

$ git add blogengine/ django_tutorial_blog_ng/ templates/

$ git commit -m 'Implemented pagination'

Viewing individual posts

As our last task for today, we’ll implement individual pages for each post. We want each post to have a nice, friendly URL that is as human-readable as possible, and also includes the date the post was created.

Add this method to the PostViewTest class, after test_index. It’s very similar to test_index, since it’s testing much the same content. However, not that we fetch the post-specific URL using the method get_absolute_url, and we then fetch that page.

Now, if you run the test, it will fail because get_absolute_url isn’t implemented. It’s often a good idea to have a get_absolute_url method for your models, which defines a single URL scheme for that type of object. So let’s create one. However, to implement our URL scheme we need to make some changes. Right now we have the date, but we don’t have a text string we can use, known in Django as a slug. So we’ll add a slug field, which will be prepopulated based on the post title. Edit your model as follows:

Here we’ve added a slug field to the model, as well as implementing our get_absolute_url method. Note we’ve limited the date to year and month, but you can include days if you wish.

While we’re in here, we’ve also implemented the __unicode__ method. Essentially, this sets how Django describes the object in the admin - in this case, the post title is a logical way of describing that Post object, so it returns the post title.

We’ve also added the class Meta, with the ordering field. This tells Django that by default any list of posts should return them ordered by pub_date in reverse - in other words, latest first.

To have the slug filled in automatically, we need to customise the admin interface a little as well:

import models

from django.contrib import admin

classPostAdmin(admin.ModelAdmin):

prepopulated_fields = {"slug": ("title",)}

admin.site.register(models.Post, PostAdmin)

Now, I recommend at this stage going into the admin and deleting all of your posts, because otherwise you’ll have problems in migrating them. The issue is that each slug is compulsory and must be unique, and it’s not practical to use South to automatically generate new slugs from the title on the fly, so by deleting them at this stage you’ll avoid problems. Once that’s done, run this command:

$ python manage.py schemamigration --auto blogengine

You’ll be prompted to specify a one-off default value - enter any string you like, such as “blah”. Then run the migration:

Whoops! Our tests are broken, because the slug field isn’t being filled in. If you take a look at the page for adding a post, you’ll notice that the slug is filled in using JavaScript, so our test fails because the test client doesn’t interpret JavaScript. So in the tests we have to fill in the slug field manually.

Also, for the unit tests, the slug attribute isn’t being created at all, so it can’t be saved. Let’s remedy that. First, edit the test_create_post method of PostTest:

What we’re doing here is that every time we create a Post object programmatically, we add the post.slug atttribute to it. Also, when submitting a post via the admin, we pass the slug parameter via HTTP POST, thus emulating how a form would submit this data.

If you run the tests again, you’ll see that test_post_page still fails. This is because we haven’t yet up the URLs, templates and views to do so. Let’s fix that. We’ll use another generic view, called a DetailView, to display the posts. Amend blogengine/urls.py as follows:

My series of Django tutorials for building a blogging engine are by far the most popular posts I’ve ever written on here. I’ve had a lot of people contact me with questions or just to express their thanks, for which I’m very grateful!

However, these tutorials haven’t really aged well. I’ve since had the opportunity to use Django in a professional capacity, which has significantly improved my understanding of the framework and the whole Python ecosystem, and there’s a lot of best practices that I didn’t follow and now wish I had. There’s also been a few gotchas that have hindered a few people in the past that I’d like to have the opportunity to correct.

So, I’m therefore creating a brand new series of tutorials to remedy this situation. This series will cover exactly the same basic idea of using Django to build a blogging engine, but will expand on what the original series did in many ways. We will cover such additional topics as:

Using Twitter Bootstrap to make your blog look good without too much hassle

Using Virtualenv to sandbox your blog application

Using South to effectively manage changes to your database structure

Writing some simple unit tests

Deploying the finished application to Heroku

Ready? Let’s get started!

Getting everything set up

Now, first of all, I’m going to assume you’re using some variant of Unix, such as Linux or Mac OS X. I’m not saying you can’t follow this tutorial with Windows, but you’ll have a harder time, because Windows just isn’t as developer-friendly as Unix in general. A modern Linux distro like Ubuntu is generally pretty easy to use, and you can easily run it in Virtualbox, so if you use Windows I would recommend you use that to make things easier.

You should also have at least a basic grasp of the command line, such as how to create and navigate directories. You don’t have to be a wizard with it, though.

You also need a proper programmer’s text editor. I use Vim, but I freely admit that Vim has a very steep learning curve and you may have trouble picking it up at the same time as following this tutorial. Emacs is also a very powerful text editor, and if you like it, feel free to use it. If you haven’t yet found a programmer’s text editor you like, I suggest you check out Sublime Text, which is easy to get started with, but also very powerful, and can be used without purchasing a license. Don’t worry too much about your text editor - it’s not vitally import that you use what I use, just find one that works for you. That said, I will say one thing - DON’T use an IDE. IDE’s hide too many details from new users and make it harder to figure out what’s going on.

You will also need to ensure you have the following installed:

Python. I recommend installing Python 2.7, because you may have issues with Python 2.6, and Python 3 isn’t universally supported yet so you might have some issues with that

Virtualenv

Pip

Git

On most Linux distros, you can find packages for all of these items easily enough using your package manager. On Mac OS X, I recommend using Homebrew to install them, though if you have another package manager installed you can use that too. If you have issues with installing any of these, a quick Google search should be sufficient to resolve the issue.

Beginning work

With all that done, we’re ready to get started. Create a folder in a suitable place on your file system and switch into it. I generally keep a dedicated folder in my home directory called Projects to use for all of my projects, and give each project a folder within it - in this case the project is called django_tutorial_blog_ng.

Now, we’ll use Git to keep track of our source code. If you prefer Mercurial, feel free to use that, but this tutorial will assume use of Git, so you’ll want to adapt the commands used accordingly. Start tracking your project with the following command from the shell, when you’re in the project directory:

Every time you come back to work on this project, you’ll need to run the previous command to make sure you’re running the version of Python installed under venv/ rather than your system Python. You can tell it’s using this because your shell prompt will be prefixed with (venv).

Why do this? Well, it means you can install whatever version of a Python module you like, without having root access, and means the Python install you’re using will only have those modules you explicitly install, rather than all of those ones available with your operating system. For instance, you could have multiple projects using different versions of Django, rather than having to update a global installation of Django and potentially break existing applications.

Now that our virtualenv is set up, we’ll install Django, as well as several other useful Python modules. Run the following command:

$ pip install django-toolbelt South

A little explanation is called for here. The package django-toolbelt includes a number of packages we’ll be using, including Django, as well as Gunicorn (a simple web server we’ll use when the time comes to deploy the app to Heroku). South is a migration tool that is commonly used with Django - basically, if you make changes to existing models, Django doesn’t natively have the capacity to apply those changes (yet - native migrations are planned at some point in the future), so South can be used to apply those changes for you without having to either manually change the database structure or dump the database and rebuild it.

Please note that one of the packages, psycopg2, may fail if you don’t have PostgreSQL installed, but don’t worry about installing it. We’ll be using SQLite for developing the application locally, and we’ll be deploying the finished product to Heroku, which does have it installed.

Once the installation is complete, run the following command to record the new modules installed:

$ pip freeze > requirements.txt

The file requirements.txt will be created, which stores the packages and versions you have installed so that they can be easily recreated. If you had issues installing psycopg2, then here’s what your requirements.txt should look like - feel free to edit it manually to look like this, as when we deploy it to Heroku, it will need to be correct to ensure that our application can be deployed successfully:

Django==1.6.1

South==0.8.4

dj-database-url==0.2.2

dj-static==0.0.5

django-toolbelt==0.0.1

gunicorn==18.0

psycopg2==2.5.1

static==0.4

wsgiref==0.1.2

Next, we’ll commit these changes with Git:

$ git add requirements.txt

$ git commit -m 'Committed requirements'

Next we’ll add a .gitignore file to ignore our virtualenv - we want to keep this out of version control because it’s something specific to that install. We have all we need to recreate it so we don’t want to store it. In addition, we also want to ignore any compiled Python files (identifiable by the .pyc suffix):

venv/

*.pyc

Let’s commit that too:

$ git add .gitignore

$ git commit -m 'Added a gitignore file'

Now, let’s generate our project’s basic skeleton:

$ django-admin.py startproject django_tutorial_blog_ng .

This application skeleton includes a basic configuration which will be sufficient for now, but you will also want to add the SQLite database file to your .gitignore:

env/

*.pyc

db.sqlite3

Let’s commit what we’ve done:

$ git add .gitignore django_tutorial_blog_ng/ manage.py

$ git commit -m 'Created project skeleton'

Now, before we create our database, we need to ensure we are using South. Go into django_tutorial_blog_ng/settings.py and find INSTALLED_APPS. Edit it to look like this:

INSTALLED_APPS = (

'django.contrib.admin',

'django.contrib.auth',

'django.contrib.contenttypes',

'django.contrib.sessions',

'django.contrib.messages',

'django.contrib.staticfiles',

'south',

)

Now, you can create your database. Run the following command:

$ python manage.py syncdb

You’ll be prompted to create a superuser - go ahead and fill in the details. Now, run the following command:

$ python manage.py runserver

This will run Django’s built-in web server on port 8000, and if you click here, you should see a page congratulating you on your first Django-powered page. Once you’re finished with it, you can stop the web server with Ctrl-C.

Don’t forget to commit your changes:

$ git add django_tutorial_blog_ng/settings.py

$ git commit -m 'Added South to installed apps'

Your first app

Django distinguishes between the concepts of projects and apps. A project is a specific project that may consist of one or more apps, such as a web app, whereas an app is a set of functionality within a project. For instance, one website might include some flat pages, an admin interface, and a blogging engine, and these could easily be different apps. By encouraging you to separate different types of functionality into different apps, Django makes it easier for you to reuse existing content elsewhere.

We’re going to create our first app, which is the blogging engine. Run the following command to create a basic skeleton for this app:

$ python manage.py startapp blogengine

Next, we need to amend our settings to install this app:

INSTALLED_APPS = (

'django.contrib.admin',

'django.contrib.auth',

'django.contrib.contenttypes',

'django.contrib.sessions',

'django.contrib.messages',

'django.contrib.staticfiles',

'south',

'blogengine',

)

Now, before we can use this app, we want to let South know about it so that changes to your database structure will be managed right from the start by South. Run the following command to create your initial migration:

$ python manage.py schemamigration --initial blogengine

That creates the file for your first migration,but doesn’t run it. To migrate your database structure to the latest version, run the following:

$ python manage.py migrate

This won’t actually make any changes, but it will ensure that all future changes to your models for the blogengine app are handled by South. Let’s commit our app skeleton:

$ git add django_tutorial_blog_ng/settings.py blogengine/

$ git commit -m 'Added blogengine app skeleton'

So, we now have our first app set up, but it doesn’t do anything much.

Remember that I mentioned how Django differentiates between projects and apps? Well, Django actually ships with a number of useful apps, and one of those is the admin interface. I consider the Django admin to be one of the framework’s killer features because it’s easy to use and customise, and saves you a lot of grief.

In the past, the admin interface needed a little work to get it working, but in Django 1.6 it’s configured to work out of the box, so if you click here, you should see the login screen for it. You should be able to sign in using the username and password you set when you ran syncdb.

Next, we’ll set up our first model.

An introduction to MVC

MVC is a common pattern used in web development. Many web development frameworks can be loosely described as MVC, including Django, Rails, CodeIgniter, Laravel and Symfony, as well as some client-side frameworks like Backbone.js. The basic concept is that a web app is divided into three basic components:

Models - the data managed with the application

Views - the presentation of the data

Controllers - an intermediary between the models and the views

Now, Django’s interpretation of MVC is slightly different to many other frameworks. While in most frameworks the views are HTML templates for rendering the data, in Django this role is taken by the templates, and the views are functions or objects that render data from the models using a template. Effectively, you can think of Django’s views as being like controllers in other frameworks, and Django templates as being views.

In Django, you create your models as Python classes that represent your data, and you use the Django ORM to query the database. As a result, it’s rare to have to directly query your database using SQL, making it more portable between different databases.

Now, our first model is going to be of a blog post. At least initially, each post will have the following attributes:

A title

A publication date and time

Some text

Now, we could just jump straight into creating our first model, but we’re going to make a point of following the practices of test-driven development here. The basic concept of TDD is that you write a failing test before writing any code, then you write the code to pass that test afterwards. It does make things a bit slower, but it’s all too easy to neglect writing tests at all if you leave it till later.

If you take a look in the blogengine folder you’ll notice there’s a file called tests.py. Open it up and you should see the following:

from django.test import TestCase

# Create your tests here.

It’s worth taking a little time to plan out what we want to test from our post model. Each post object will have the attributes I mentioned above, and what we want to be able to do is test that we can:

Set the title

Set the publication date and time

Set the text

Save it successfully

Retrieve it successfully

So, let’s create a test for our post model. We’ll go through the relevant sections of the test bit by bit:

from django.test import TestCase

from django.utils import timezone

from blogengine.models import Post

Here we’re importing the required functionality. TestCase is provided by Django, and is an object all of your tests should inherit from. timezone is a utility for handling dates and times correctly. Finally, Post is our model, which we have yet to implement.

# Create your tests here.

classPostTest(TestCase):

deftest_create_post(self):

# Create the post

post = Post()

Here we create the PostTest class, which represents a test for your Post model. So far it only has one method, but you can add additional ones if required.

# Set the attributes

post.title = 'My first post'

post.text = 'This is my first blog post'

post.pub_date = timezone.now()

Here we set the post’s attributes.

# Save it

post.save()

Now we save it. At this point it has been added to the database, and the rest of the test involves us ensuring it has been saved correctly and can be retrieved.

# Check we can find it

all_posts = Post.objects.all()

self.assertEquals(len(all_posts), 1)

only_post = all_posts[0]

self.assertEquals(only_post, post)

Here we use the Django database API to fetch all of the Post objects, assert that there is only 1 post object, retrieve that post object, and assert that it is the same object as the post object we just saved.

If unit testing is new to you, assertions may be new to you. Essentially you’re saying to the Python interpreter, “I assert that X is true, so please raise an error if this is not true”. Here we assert that the length of the variable all_posts is 1, and that that post is the same object as the previously saved object, so that the test will fail if that is not the case.

# Check attributes

self.assertEquals(only_post.title, 'My first post')

self.assertEquals(only_post.text, 'This is my first blog post')

self.assertEquals(only_post.pub_date.day, post.pub_date.day)

self.assertEquals(only_post.pub_date.month, post.pub_date.month)

self.assertEquals(only_post.pub_date.year, post.pub_date.year)

self.assertEquals(only_post.pub_date.hour, post.pub_date.hour)

self.assertEquals(only_post.pub_date.minute, post.pub_date.minute)

self.assertEquals(only_post.pub_date.second, post.pub_date.second)

Finally, we assert that the values of each of the post’s attributes as stored in the database match up with those in the post object we set. For the title and text fields, these are easy to validate as we can just check the values against those we set. For the pub_date field, things are a bit more complex, since this will be an object in its own right, so you need to check the day, month, year, hour, minute and second attributes separately.

The whole thing should look like this:

from django.test import TestCase

from django.utils import timezone

from blogengine.models import Post

# Create your tests here.

classPostTest(TestCase):

deftest_create_post(self):

# Create the post

post = Post()

# Set the attributes

post.title = 'My first post'

post.text = 'This is my first blog post'

post.pub_date = timezone.now()

# Save it

post.save()

# Check we can find it

all_posts = Post.objects.all()

self.assertEquals(len(all_posts), 1)

only_post = all_posts[0]

self.assertEquals(only_post, post)

# Check attributes

self.assertEquals(only_post.title, 'My first post')

self.assertEquals(only_post.text, 'This is my first blog post')

self.assertEquals(only_post.pub_date.day, post.pub_date.day)

self.assertEquals(only_post.pub_date.month, post.pub_date.month)

self.assertEquals(only_post.pub_date.year, post.pub_date.year)

self.assertEquals(only_post.pub_date.hour, post.pub_date.hour)

self.assertEquals(only_post.pub_date.minute, post.pub_date.minute)

self.assertEquals(only_post.pub_date.second, post.pub_date.second)

With that in place, the time has come to run our test with the following command:

Don’t worry about the error - this is exactly what we expect to see because we haven’t implemented our Post model yet. Now that we have a failing test in place, we can implement our model to make the test pass. Open up blogengine/models.py and enter the following:

Our test still fails, but if we take a look at this error message, we can see why - there is no database table for the posts (called blogengine_post). Using South, we can easily remedy that by creating a new migration to create this table:

Success! We now have a model in place that passes our test. Let’s commit our changes:

$ git add blogengine/

$ git commit -m 'Added post model with passing test'

Now, Django’s ORM is basically a layer on top of SQL that abstracts away differences between different relational databases, but the underlying queries are still being run. You can view the SQL created to generate the table by using the sqlall command. Just run python manage.py sqlall blogengine and you should see something like this:

BEGIN;

CREATETABLE"blogengine_post" (

"id"integerNOTNULL PRIMARY KEY,

"title"varchar(200) NOTNULL,

"pub_date" datetime NOTNULL,

"text"textNOTNULL

)

;

COMMIT;

Note the addition of the id field as the primary key. If you’re at all familiar with relational databases, you’ll know that every table must have one field, called a primary key, that is a unique reference to that row. This can be overridden, but here it’s exactly the behaviour we want.

Creating blog posts via the admin

Now, we need a way to be able to create, edit and delete blog posts. Django’s admin interface allows us to do so easily. However, before we do so, we want to create automated acceptance tests for this functionality, in order to test the ability to create posts from an end-user’s perspective. While unit tests are for testing sections of an application’s functionality from the perspective of other sections of the application, acceptance tests are testing from the user’s perspective. In other words, they test what the application needs to do to be acceptable.

First, we will test logging into the admin. Open up blogengine/tests.py and amend it as follows:

from django.test import TestCase, LiveServerTestCase, Client

from django.utils import timezone

from blogengine.models import Post

# Create your tests here.

classPostTest(TestCase):

deftest_create_post(self):

# Create the post

post = Post()

# Set the attributes

post.title = 'My first post'

post.text = 'This is my first blog post'

post.pub_date = timezone.now()

# Save it

post.save()

# Check we can find it

all_posts = Post.objects.all()

self.assertEquals(len(all_posts), 1)

only_post = all_posts[0]

self.assertEquals(only_post, post)

# Check attributes

self.assertEquals(only_post.title, 'My first post')

self.assertEquals(only_post.text, 'This is my first blog post')

self.assertEquals(only_post.pub_date.day, post.pub_date.day)

self.assertEquals(only_post.pub_date.month, post.pub_date.month)

self.assertEquals(only_post.pub_date.year, post.pub_date.year)

self.assertEquals(only_post.pub_date.hour, post.pub_date.hour)

self.assertEquals(only_post.pub_date.minute, post.pub_date.minute)

self.assertEquals(only_post.pub_date.second, post.pub_date.second)

classAdminTest(LiveServerTestCase):

deftest_login(self):

# Create client

c = Client()

# Get login page

response = c.get('/admin/')

# Check response code

self.assertEquals(response.status_code, 200)

First of all, we import two new objects from django.test, LiveServerTestCase and Client. Then we create the first part of our first test for the admin, named AdminTest. Eventually, this will test that we can log successfully into the admin interface. For now, we’re just doing the following:

Creating a Client object

Fetching the /admin/ route

Asserting that the status code for this HTTP request is 200, (in other words, that the page was fetched successfully).

If you run python manage.py test, you should see that both tests pass successfully. Now we’ll extend AdminTest - we’ll verify that the response contains the string ‘Log in’, which in the Django admin interface, appears on the login page:

classAdminTest(LiveServerTestCase):

deftest_login(self):

# Create client

c = Client()

# Get login page

response = c.get('/admin/')

# Check response code

self.assertEquals(response.status_code, 200)

# Check 'Log in' in response

self.assertTrue('Log in'in response.content)

Here response.content is a string containing the content of the HTTP response - we’re asserting that the substring ‘Log in’ appears in there. If you run python manage.py test again, it should pass.

Now, we need to actually log in. This could be fiddly, but Django has a handy convenience method to log you in when testing:

classAdminTest(LiveServerTestCase):

deftest_login(self):

# Create client

c = Client()

# Get login page

response = c.get('/admin/')

# Check response code

self.assertEquals(response.status_code, 200)

# Check 'Log in' in response

self.assertTrue('Log in'in response.content)

# Log the user in

c.login(username='bobsmith', password="password")

# Check response code

response = c.get('/admin/')

self.assertEquals(response.status_code, 200)

# Check 'Log out' in response

self.assertTrue('Log out'in response.content)

Here, we use the login method of the Client object to log into the admin interface, and then we fetch the /admin/ route again. We assert that we get a 200 status code, and we assert that the response contains the string ‘Log out’ - in other words, that we are logged in.

Try running python manage.py test and we’ll get an error., because the user details we’ve used to log in don’t exist. Let’s resolve that.

Now, you could put your own credentials in there, but that’s not a good idea because it’s a security risk. Instead, we’ll create a fixture for the test user that will be loaded when the tests are run. Run the following command:

$ python manage.py createsuperuser

Give the username as bobsmith, the email address as bob@example.com, and the password as password. Once that’s done, run these commands to dump the existing users to a fixture:

This will dump all of the existing users to blogengine/fixtures/users.json. You may wish to edit this file to remove your own superuser account and leave only the newly created one in there.

Next we need to amend our test to load this fixture:

classAdminTest(LiveServerTestCase):

fixtures = ['users.json']

deftest_login(self):

# Create client

c = Client()

# Get login page

response = c.get('/admin/')

# Check response code

self.assertEquals(response.status_code, 200)

# Check 'Log in' in response

self.assertTrue('Log in'in response.content)

# Log the user in

c.login(username='bobsmith', password="password")

# Check response code

response = c.get('/admin/')

self.assertEquals(response.status_code, 200)

# Check 'Log out' in response

self.assertTrue('Log out'in response.content)

Now, if you run python manage.py test, you should find that the test passes. Next, we’ll test that we can log out:

classAdminTest(LiveServerTestCase):

fixtures = ['users.json']

deftest_login(self):

# Create client

c = Client()

# Get login page

response = c.get('/admin/')

# Check response code

self.assertEquals(response.status_code, 200)

# Check 'Log in' in response

self.assertTrue('Log in'in response.content)

# Log the user in

c.login(username='bobsmith', password="password")

# Check response code

response = c.get('/admin/')

self.assertEquals(response.status_code, 200)

# Check 'Log out' in response

self.assertTrue('Log out'in response.content)

deftest_logout(self):

# Create client

c = Client()

# Log in

c.login(username='bobsmith', password="password")

# Check response code

response = c.get('/admin/')

self.assertEquals(response.status_code, 200)

# Check 'Log out' in response

self.assertTrue('Log out'in response.content)

# Log out

c.logout()

# Check response code

response = c.get('/admin/')

self.assertEquals(response.status_code, 200)

# Check 'Log in' in response

self.assertTrue('Log in'in response.content)

This test works along very similar lines. We log in, verify that ‘Log out’ is in the response, then we log out, and verify that ‘Log in’ is in the response. Run the tests again, and they should pass. Assuming they do, let’s commit our changes again:

$ git add blogengine/

$ git commit -m 'Added tests for admin auth'

This code is a little repetitive. We create the client twice, when we could do so only once. Amend the AdminTest class as follows:

classAdminTest(LiveServerTestCase):

fixtures = ['users.json']

defsetUp(self):

self.client = Client()

deftest_login(self):

# Get login page

response = self.client.get('/admin/')

# Check response code

self.assertEquals(response.status_code, 200)

# Check 'Log in' in response

self.assertTrue('Log in'in response.content)

# Log the user in

self.client.login(username='bobsmith', password="password")

# Check response code

response = self.client.get('/admin/')

self.assertEquals(response.status_code, 200)

# Check 'Log out' in response

self.assertTrue('Log out'in response.content)

deftest_logout(self):

# Log in

self.client.login(username='bobsmith', password="password")

# Check response code

response = self.client.get('/admin/')

self.assertEquals(response.status_code, 200)

# Check 'Log out' in response

self.assertTrue('Log out'in response.content)

# Log out

self.client.logout()

# Check response code

response = self.client.get('/admin/')

self.assertEquals(response.status_code, 200)

# Check 'Log in' in response

self.assertTrue('Log in'in response.content)

The setUp() method is automatically run when the test runs, and ensures we only need to start up the client once. Run your tests to make sure they pass, then commit your changes:

$ git add blogengine/

$ git commit -m 'Refactored admin test'

Now, we’ll implement a test for creating a new post. The admin interface implements URLs for creating new instances of a model in a consistent format of /admin/app_name/model_name/add/, so the URL for adding a new post will be /admin/blogengine/post/add/.

Add this method to the AdminTest class:

deftest_create_post(self):

# Log in

self.client.login(username='bobsmith', password="password")

# Check response code

response = self.client.get('/admin/blogengine/post/add/')

self.assertEquals(response.status_code, 200)

Try running it and this will fail, because we haven’t registered the Post model in the Django admin. So we need to do that. To do so, open a new file at blogengine/admin.py and add the following code:

import models

from django.contrib import admin

admin.site.register(models.Post)

Now, run python manage.py test and the test should pass. If you want to confirm that the post model appears in the admin, run python manage.py runserver and click here.

So now we can reach the page for adding a post, but we haven’t yet tested that we can submit one. Let’s remedy that:

deftest_create_post(self):

# Log in

self.client.login(username='bobsmith', password="password")

# Check response code

response = self.client.get('/admin/blogengine/post/add/')

self.assertEquals(response.status_code, 200)

# Create the new post

response = self.client.post('/admin/blogengine/post/add/', {

'title': 'My first post',

'text': 'This is my first post',

'pub_date_0': '2013-12-28',

'pub_date_1': '22:00:04'

},

follow=True

)

self.assertEquals(response.status_code, 200)

# Check added successfully

self.assertTrue('added successfully'in response.content)

# Check new post now in database

all_posts = Post.objects.all()

self.assertEquals(len(all_posts), 1)

Here we submit the new post via HTTP POST, with all the data passed through. This mirrors the form created by the Django admin interface - if you take a look at the HTML generated by the admin, you’ll see that the inputs are given names that match these. Note that the pub_date field, because it represents a datetime object, is split up into a separate date and time field. Also note the parameter follow=True - this denotes that the test client should follow any HTTP redirect.

We confirm that the POST request responded with a 200 code, denoting success. We also confirm that the response included the phrase ‘added successfully’. Finally we confirm that there is now a single Post object in the database. Don’t worry about any existing content - Django creates a dedicated test database and destroys it after the tests are done, so you can be sure that no posts are present unless you explicitly load them from a fixture.

We can now test creating a post, but we also need to ensure we can test editing and deleting them. First we’ll add a test for editing posts:

deftest_edit_post(self):

# Create the post

post = Post()

post.title = 'My first post'

post.text = 'This is my first blog post'

post.pub_date = timezone.now()

post.save()

# Log in

self.client.login(username='bobsmith', password="password")

# Edit the post

response = self.client.post('/admin/blogengine/post/1/', {

'title': 'My second post',

'text': 'This is my second blog post',

'pub_date_0': '2013-12-28',

'pub_date_1': '22:00:04'

},

follow=True

)

self.assertEquals(response.status_code, 200)

# Check changed successfully

self.assertTrue('changed successfully'in response.content)

# Check post amended

all_posts = Post.objects.all()

self.assertEquals(len(all_posts), 1)

only_post = all_posts[0]

self.assertEquals(only_post.title, 'My second post')

self.assertEquals(only_post.text, 'This is my second blog post')

Here we create a new blog post, then verify we can edit it by resubmitting it with different values, and checking that we get the expected response, and that the data in the database has been updated. Run python manage.py test, and this should pass.

Finally, we’ll set up a test for deleting posts:

deftest_delete_post(self):

# Create the post

post = Post()

post.title = 'My first post'

post.text = 'This is my first blog post'

post.pub_date = timezone.now()

post.save()

# Check new post saved

all_posts = Post.objects.all()

self.assertEquals(len(all_posts), 1)

# Log in

self.client.login(username='bobsmith', password="password")

# Delete the post

response = self.client.post('/admin/blogengine/post/1/delete/', {

'post': 'yes'

}, follow=True)

self.assertEquals(response.status_code, 200)

# Check deleted successfully

self.assertTrue('deleted successfully'in response.content)

# Check post amended

all_posts = Post.objects.all()

self.assertEquals(len(all_posts), 0)

Again, this is pretty similar to what we did before. We create a new post, verify that it is the sole post in the database, and log into the admin. Then we delete the post via the admin, and confirm that the admin interface confirmed it has been deleted, and the post is gone from the database.

I think it’s now time to commit again:

$ git add blogengine/

$ git commit -m 'Post admin tests in place'

So we now know that we can create, edit and delete posts, and we have tests in place to confirm this. So our next task is to be able to display our posts.

For now, to keep things simple, we’re only going to implement the index view - in other words, all the posts in reverse chronological order. We’ll use Django’s generic views to keep things really easy.

Django’s generic views are another really handy feature. As mentioned earlier, a view is a function or class that describes how a specific route should render an object. Now, there are many tasks that recur in web development. For instance, many web pages you may have seen may be a list of objects - in this case, the index page for a blog is a list of blog posts. For that reason, Django has the ListView generic view, which makes it easy to render a list of objects.

Now, like before, we want to have a test in place. Open up blogengine/tests.py and add the following class at the end of the file:

classPostViewTest(LiveServerTestCase):

defsetUp(self):

self.client = Client()

deftest_index(self):

# Create the post

post = Post()

post.title = 'My first post'

post.text = 'This is my first blog post'

post.pub_date = timezone.now()

post.save()

# Check new post saved

all_posts = Post.objects.all()

self.assertEquals(len(all_posts), 1)

# Fetch the index

response = self.client.get('/')

self.assertEquals(response.status_code, 200)

# Check the post title is in the response

self.assertTrue(post.title in response.content)

# Check the post text is in the response

self.assertTrue(post.text in response.content)

# Check the post date is in the response

self.assertTrue(str(post.pub_date.year) in response.content)

self.assertTrue(post.pub_date.strftime('%b') in response.content)

self.assertTrue(str(post.pub_date.day) in response.content)

Here we create the post, and assert that it is the sole post object. We then fetch the index page, and assert that the HTTP status code is 200 (ie. the page exists and is returned). We then verify that the response contains the post title, text and publication date.

Note that for the month, we need to do a bit of jiggery-pokery to get the month name. By default Django will return short month names (eg Jan, Feb etc), but Python stores months as numbers, so we need to format it as a short month name using %b.

If you run this, you will get an error because the index route isn’t implemented. So let’s fix that. Open up the existing django_tutorial_blog_ng/urls.py file and amend it to look like this:

from django.conf.urls import patterns, include, url

from django.contrib import admin

admin.autodiscover()

urlpatterns = patterns('',

# Examples:

# url(r'^$', 'django_tutorial_blog_ng.views.home', name='home'),

# url(r'^blog/', include('blog.urls')),

url(r'^admin/', include(admin.site.urls)),

# Blog URLs

url(r'^.*$', include('blogengine.urls')),

)

Then, create a new file at blogengine/urls.py and edit it as follows:

from django.conf.urls import patterns, url

from django.views.generic import ListView

from blogengine.models import Post

urlpatterns = patterns('',

# Index

url('^$', ListView.as_view(

model=Post,

)),

)

A little explanation is called for. The project has its own urls.py file that handles routing throughout the project. However, because Django encourages you to make your apps reusable, we want to keep the routes in the individual apps as far as possible. So, in the project file, we include the blogengine/urls.py file.

In the app-specific urls.py, we import the Post model and the ListView generic view. We then define a route for the index page - the regular expression ^$ will match only an empty string, so that page will be the index. For this route, we then call the as_view() method of the ListView object, and set the model as Post.

Now, if you either run the tests, or run the development server and visit the index page, you’ll see that it isn’t working yet - you should see the error TemplateDoesNotExist: blogengine/post_list.html. This tells us that we need to create a template called blogengine/post_list.html, so let’s do that. First of all, add the following at the end of django_tutorial_blog_ng/settings.py:

# Template directory

TEMPLATE_DIRS = [os.path.join(BASE_DIR, 'templates')]

Next, create the folders for the templates, and a blank post_list.html file:

$ mkdir templates

$ mkdir templates/blogengine

$ touch templates/blogengine/post_list.html

Now, run your tests again, and you’ll see that the template now exists, but a new error is showing up:

To fix this, we make sure the template shows the data we want. Open up templates/blogengine/post_list.html and enter the following:

<html>

<head>

<title>My Django Blog</title>

</head>

<body>

{% for post in object_list %}

<h1>{{ post.title }}</h1>

<h3>{{ post.pub_date }}</h3>

{{ post.text }}

{% endfor %}

</body>

</html>

This is only a very basic template, and we’ll expand upon it in future.

With that done, you can run python manage.py test, and it should pass. Well done! Don’t forget to commit your changes:

$ git add django_tutorial_blog_ng/ templates/ blogengine/

$ git commit -m 'Implemented list view for posts'

And that’s all for this lesson! We’ve done a hell of a lot in this lesson - set up our project, created a comprehensive test suite for it, and implemented the basic functionality. Next time we’ll make it a bit prettier using Twitter Bootstrap, as well as implementing more of the basic functionality for the blog.

You can find the source code on Github. For your convenience, I’ve tagged this lesson as lesson-1, so you can just clone the repository and switch to the end of this lesson with the following commands:

I’ve recently started using Vagrant for PHP development. It’s an incredibly useful and convenient tool - never again will I have to faff about installing XAMPP on someone’s laptop so they can demonstrate the new site, instead I can just install Vagrant and Virtualbox, clone the repository, and run vagrant up, and nip off and make a cuppa, safe in the knowledge that when I get back the install will be, if not done, then at least in progress. Also, it means it’s easy to run the same OS for development and production.

I’ve used PuPHPet a bit, but I’ve found Puppet to be a little complex for what I wanted, so I switched to using the shell provisioner instead. As a starting point for future projects, I’ve thrown together a basic Vagrant configuration based on that provided by PuPHPet, that includes the following:

A full LAMP stack, running on Ubuntu 12.04

APC

PHPMyAdmin

Git

A blank SQL file - this is automatically run on vagrant up, so you can place any commands needed to set up your database in here.

msmtp - just amend the username and password in bootstrap.sh to point to a Gmail account and your web app should be able to send emails via that account quickly and easily

It’s available here, and if you haven’t discovered the benefits of Vagrant yet, it would be a good place to start.

About me

I'm a web and mobile app developer based in Norfolk. My skillset includes Python, PHP and Javascript, and I have extensive experience working with CodeIgniter, Laravel, Django, Phonegap and Angular.js.