Matthew Daly's Blog

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

2nd January 2014 11:28 am

Django Blog Tutorial - the Next Generation - Part 2

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:

$ cp blogengine/static/bower_components/html5-boilerplate/index.html templates/blogengine/includes/base.html

Now amend this file to look like this:

<!DOCTYPE html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js"> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<title>{% block title %}My Django Blog{% endblock %}</title>
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<!-- Place favicon.ico and apple-touch-icon.png in the root directory -->
{% load staticfiles %}
<link rel="stylesheet" href="{% static 'bower_components/html5-boilerplate/css/normalize.css' %}">
<link rel="stylesheet" href="{% static 'bower_components/html5-boilerplate/css/main.css' %}">
<link rel="stylesheet" href="{% static 'bower_components/bootstrap/dist/css/bootstrap.min.css' %}">
<link rel="stylesheet" href="{% static 'bower_components/bootstrap/dist/css/bootstrap-theme.min.css' %}">
<script src="{% static 'bower_components/html5-boilerplate/js/vendor/modernizr-2.6.2.min.js' %}"></script>
</head>
<body>
<!--[if lt IE 7]>
<p class="browsehappy">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/">upgrade your browser</a> to improve your experience.</p>
<![endif]-->
<!-- Add your site or application content here -->
{% block content %}{% endblock %}
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
<script>window.jQuery || document.write('<script src="{% static 'bower_components/html5-boilerplate/js/vendor/jquery-1.10.2.min.js' %}"><\/script>')</script>
<script src="{% static 'bower_components/html5-boilerplate/js/plugins.js' %}"></script>
<script src="{% static 'bower_components/bootstrap/dist/js/bootstrap.min.js' %}"></script>
<!-- Google Analytics: change UA-XXXXX-X to be your site's ID. -->
<script>
(function(b,o,i,l,e,r){b.GoogleAnalyticsObject=l;b[l]||(b[l]=
function(){(b[l].q=b[l].q||[]).push(arguments)});b[l].l=+new Date;
e=o.createElement(i);r=o.getElementsByTagName(i)[0];
e.src='//www.google-analytics.com/analytics.js';
r.parentNode.insertBefore(e,r)}(window,document,'script','ga'));
ga('create','UA-XXXXX-X');ga('send','pageview');
</script>
</body>
</html>

Note the following:

  • 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:

$ git add templates/
$ git commit -m 'Now use Bootstrap and HTML5 Boilerplate for templates'

Now, let’s use Bootstrap to style our blog a little. First we’ll add a navigation bar at the top of our blog. Edit the base template as follows:

<div class="navbar navbar-static-top navbar-inverse">
<div class="navbar-inner">
<div class="container">
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
<a class="brand" href="/">My Django Blog</a>
<div class="nav-collapse collapse">
</div>
</div>
</div>
</div>
<div class="container">
{% block header %}
<div class="page-header">
<h1>My Django Blog</h1>
</div>
{% endblock %}
<div class="row">
{% block content %}{% endblock %}
</div>
</div>
<div class="container footer">
<div class="row">
<div class="span12">
<p>Copyright &copy; {% now "Y" %}</p>
</div>
</div>
</div>

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 %}
<div class="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:

class PostViewTest(LiveServerTestCase):
def setUp(self):
self.client = Client()
def test_index(self):
# Create the post
post = Post()
post.title = 'My first post'
post.text = 'This is [my first blog post](http://127.0.0.1:8000/)'
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(markdown.markdown(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)
# Check the link is marked up properly
self.assertTrue('<a href="http://127.0.0.1:8000/">my first blog post</a>' in response.content)

You’ll also need to add the following at the top:

import markdown

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
def custom_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 %}
<div class="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 %}
<div class="post">
<h1>{{ post.title }}</h1>
<h3>{{ post.pub_date }}</h3>
{{ post.text|custom_markdown }}
</div>
{% endfor %}
{% if page_obj.has_previous %}
<a href="/{{ page_obj.previous_page_number }}/">Previous Page</a>
{% endif %}
{% if page_obj.has_next %}
<a href="/{{ 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.

First of all, we’ll implement our test for it, however:

def test_post_page(self):
# Create the post
post = Post()
post.title = 'My first post'
post.text = 'This is [my first blog post](http://127.0.0.1:8000/)'
post.pub_date = timezone.now()
post.save()
# Check new post saved
all_posts = Post.objects.all()
self.assertEquals(len(all_posts), 1)
only_post = all_posts[0]
self.assertEquals(only_post, post)
# Get the post URL
post_url = only_post.get_absolute_url()
# Fetch the post
response = self.client.get(post_url)
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(markdown.markdown(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)
# Check the link is marked up properly
self.assertTrue('<a href="http://127.0.0.1:8000/">my first blog post</a>' in response.content)

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:

from django.db import models
# Create your models here.
class Post(models.Model):
title = models.CharField(max_length=200)
pub_date = models.DateTimeField()
text = models.TextField()
slug = models.SlugField(max_length=40, unique=True)
def get_absolute_url(self):
return "/%s/%s/%s/" % (self.pub_date.year, self.pub_date.month, self.slug)
def __unicode__(self):
return self.title
class Meta:
ordering = ["-pub_date"]

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
class PostAdmin(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:

$ python manage.py migrate

Let’s run our tests now:

(venv)Smith:django_tutorial_blog_ng matthewdaly$ python manage.py test
Creating test database for alias 'default'...
.F.F...F
======================================================================
FAIL: test_create_post (blogengine.tests.AdminTest)
----------------------------------------------------------------------
Traceback (most recent call last):
File "/Users/matthewdaly/Projects/django_tutorial_blog_ng/blogengine/tests.py", line 103, in test_create_post
self.assertTrue('added successfully' in response.content)
AssertionError: False is not true
======================================================================
FAIL: test_edit_post (blogengine.tests.AdminTest)
----------------------------------------------------------------------
Traceback (most recent call last):
File "/Users/matthewdaly/Projects/django_tutorial_blog_ng/blogengine/tests.py", line 132, in test_edit_post
self.assertTrue('changed successfully' in response.content)
AssertionError: False is not true
======================================================================
FAIL: test_post_page (blogengine.tests.PostViewTest)
----------------------------------------------------------------------
Traceback (most recent call last):
File "/Users/matthewdaly/Projects/django_tutorial_blog_ng/blogengine/tests.py", line 222, in test_post_page
self.assertEquals(response.status_code, 200)
AssertionError: 404 != 200
----------------------------------------------------------------------
Ran 8 tests in 2.180s
FAILED (failures=3)
Destroying test database for alias 'default'...

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:

class PostTest(TestCase):
def test_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.slug = 'my-first-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.slug, 'my-first-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)

Next, let’s amend AdminTest:

class AdminTest(LiveServerTestCase):
fixtures = ['users.json']
def setUp(self):
self.client = Client()
def test_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)
def test_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)
def test_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',
'slug': 'my-first-post'
},
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)
def test_edit_post(self):
# Create the post
post = Post()
post.title = 'My first post'
post.text = 'This is my first blog post'
post.slug = 'my-first-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',
'slug': 'my-second-post'
},
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')
def test_delete_post(self):
# Create the post
post = Post()
post.title = 'My first post'
post.text = 'This is my first blog post'
post.slug = 'my-first-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)

And PostViewTest:

class PostViewTest(LiveServerTestCase):
def setUp(self):
self.client = Client()
def test_index(self):
# Create the post
post = Post()
post.title = 'My first post'
post.text = 'This is [my first blog post](http://127.0.0.1:8000/)'
post.slug = 'my-first-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(markdown.markdown(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)
# Check the link is marked up properly
self.assertTrue('<a href="http://127.0.0.1:8000/">my first blog post</a>' in response.content)
def test_post_page(self):
# Create the post
post = Post()
post.title = 'My first post'
post.text = 'This is [my first blog post](http://127.0.0.1:8000/)'
post.slug = 'my-first-post'
post.pub_date = timezone.now()
post.save()
# Check new post saved
all_posts = Post.objects.all()
self.assertEquals(len(all_posts), 1)
only_post = all_posts[0]
self.assertEquals(only_post, post)
# Get the post URL
post_url = only_post.get_absolute_url()
# Fetch the post
response = self.client.get(post_url)
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(markdown.markdown(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)
# Check the link is marked up properly
self.assertTrue('<a href="http://127.0.0.1:8000/">my first blog post</a>' in response.content)

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:

rom django.conf.urls import patterns, url
from django.views.generic import ListView, DetailView
from blogengine.models import Post
urlpatterns = patterns('',
# Index
url(r'^(?P<page>\d+)?/?$', ListView.as_view(
model=Post,
paginate_by=5,
)),
# Individual posts
url(r'^(?P<pub_date__year>\d{4})/(?P<pub_date__month>\d{1,2})/(?P<slug>[a-zA-Z0-9-]+)/?$', DetailView.as_view(
model=Post,
)),
)

Running our tests again will still fail, but now because the template post_detail.html has not been found. So let’s create it:

{% extends "blogengine/includes/base.html" %}
{% load custom_markdown %}
{% block content %}
<div class="post">
<h1>{{ object.title }}</h1>
<h3>{{ object.pub_date }}</h3>
{{ object.text|custom_markdown }}
</div>
{% endblock %}

If you run your tests again, they should now pass. However, we still need to provide a hyperlink from each post in the index to the post page, so let’s do that:

{% extends "blogengine/includes/base.html" %}
{% load custom_markdown %}
{% block content %}
{% for post in object_list %}
<div class="post">
<h1><a href="{{ post.get_absolute_url }}">{{ post.title }}</a></h1>
<h3>{{ post.pub_date }}</h3>
{{ post.text|custom_markdown }}
</div>
{% endfor %}
{% if page_obj.has_previous %}
<a href="/{{ page_obj.previous_page_number }}/">Previous Page</a>
{% endif %}
{% if page_obj.has_next %}
<a href="/{{ page_obj.next_page_number }}/">Next Page</a>
{% endif %}
{% endblock %}

And that’s all for today! We now have individual post pages, we’ve styled our blog a bit, and we’ve implemented Markdown support. All that remains is to commit our changes:

$ git add blogengine/ templates/
$ git commit -m 'Implemented post pages'

As before, I’ve tagged the final commit with ‘lesson-2’, so if you’re following along, you can switch to this point with git checkout lesson-2.

Next time we’ll add support for flat pages and multiple authors, as well as adding support for comments via a third-party commenting system.

28th December 2013 3:00 pm

Django Blog Tutorial - the Next Generation - Part 1

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:

$ git init

If you haven’t used Git before, you’ll also want to configure it.

Next, we set up our virtualenv. Run the following command:

$ virtualenv venv --distribute

Followed by:

$ source venv/bin/activate

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.
class PostTest(TestCase):
def test_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.
class PostTest(TestCase):
def test_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:

$ python manage.py test

You should see something like this:

(venv)Smith:django_tutorial_blog_ng matthewdaly$ python manage.py test
Creating test database for alias 'default'...
E
======================================================================
ERROR: blogengine.tests (unittest.loader.ModuleImportFailure)
----------------------------------------------------------------------
ImportError: Failed to import test module: blogengine.tests
Traceback (most recent call last):
File "/usr/local/Cellar/python/2.7.6/Frameworks/Python.framework/Versions/2.7/lib/python2.7/unittest/loader.py", line 254, in _find_tests
module = self._get_module_from_name(name)
File "/usr/local/Cellar/python/2.7.6/Frameworks/Python.framework/Versions/2.7/lib/python2.7/unittest/loader.py", line 232, in _get_module_from_name
__import__(name)
File "/Users/matthewdaly/Projects/django_tutorial_blog_ng/blogengine/tests.py", line 3, in <module>
from blogengine.models import Post
ImportError: cannot import name Post
----------------------------------------------------------------------
Ran 1 test in 0.000s
FAILED (errors=1)
Destroying test database for alias 'default'...

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:

from django.db import models
# Create your models here.
class Post(models.Model):
title = models.CharField(max_length=200)
pub_date = models.DateTimeField()
text = models.TextField()

Save the file and run the test again:

(venv)Smith:django_tutorial_blog_ng matthewdaly$ python manage.py test
Creating test database for alias 'default'...
E
======================================================================
ERROR: test_create_post (blogengine.tests.PostTest)
----------------------------------------------------------------------
Traceback (most recent call last):
File "/Users/matthewdaly/Projects/django_tutorial_blog_ng/blogengine/tests.py", line 17, in test_create_post
post.save()
File "/Users/matthewdaly/Projects/django_tutorial_blog_ng/venv/lib/python2.7/site-packages/django/db/models/base.py", line 545, in save
force_update=force_update, update_fields=update_fields)
File "/Users/matthewdaly/Projects/django_tutorial_blog_ng/venv/lib/python2.7/site-packages/django/db/models/base.py", line 573, in save_base
updated = self._save_table(raw, cls, force_insert, force_update, using, update_fields)
File "/Users/matthewdaly/Projects/django_tutorial_blog_ng/venv/lib/python2.7/site-packages/django/db/models/base.py", line 654, in _save_table
result = self._do_insert(cls._base_manager, using, fields, update_pk, raw)
File "/Users/matthewdaly/Projects/django_tutorial_blog_ng/venv/lib/python2.7/site-packages/django/db/models/base.py", line 687, in _do_insert
using=using, raw=raw)
File "/Users/matthewdaly/Projects/django_tutorial_blog_ng/venv/lib/python2.7/site-packages/django/db/models/manager.py", line 232, in _insert
return insert_query(self.model, objs, fields, **kwargs)
File "/Users/matthewdaly/Projects/django_tutorial_blog_ng/venv/lib/python2.7/site-packages/django/db/models/query.py", line 1511, in insert_query
return query.get_compiler(using=using).execute_sql(return_id)
File "/Users/matthewdaly/Projects/django_tutorial_blog_ng/venv/lib/python2.7/site-packages/django/db/models/sql/compiler.py", line 898, in execute_sql
cursor.execute(sql, params)
File "/Users/matthewdaly/Projects/django_tutorial_blog_ng/venv/lib/python2.7/site-packages/django/db/backends/util.py", line 53, in execute
return self.cursor.execute(sql, params)
File "/Users/matthewdaly/Projects/django_tutorial_blog_ng/venv/lib/python2.7/site-packages/django/db/utils.py", line 99, in __exit__
six.reraise(dj_exc_type, dj_exc_value, traceback)
File "/Users/matthewdaly/Projects/django_tutorial_blog_ng/venv/lib/python2.7/site-packages/django/db/backends/util.py", line 53, in execute
return self.cursor.execute(sql, params)
File "/Users/matthewdaly/Projects/django_tutorial_blog_ng/venv/lib/python2.7/site-packages/django/db/backends/sqlite3/base.py", line 450, in execute
return Database.Cursor.execute(self, query, params)
OperationalError: no such table: blogengine_post
----------------------------------------------------------------------
Ran 1 test in 0.059s
FAILED (errors=1)
Destroying test database for alias 'default'...

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:

$ python manage.py schemamigration --auto blogengine

That creates the new migration. Now let’s run it:

$ python manage.py migrate

Now, let’s run our tests to check it’s working as expected:

(venv)Smith:django_tutorial_blog_ng matthewdaly$ python manage.py test
Creating test database for alias 'default'...
.
----------------------------------------------------------------------
Ran 1 test in 0.001s
OK
Destroying test database for alias 'default'...

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;
CREATE TABLE "blogengine_post" (
"id" integer NOT NULL PRIMARY KEY,
"title" varchar(200) NOT NULL,
"pub_date" datetime NOT NULL,
"text" text NOT NULL
)
;
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.
class PostTest(TestCase):
def test_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)
class AdminTest(LiveServerTestCase):
def test_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:

class AdminTest(LiveServerTestCase):
def test_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:

class AdminTest(LiveServerTestCase):
def test_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 aspassword`. Once that’s done, run these commands to dump the existing users to a fixture:

$ mkdir blogengine/fixtures
$ python manage.py dumpdata auth.User --indent=2 > blogengine/fixtures/users.json

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:

class AdminTest(LiveServerTestCase):
fixtures = ['users.json']
def test_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:

class AdminTest(LiveServerTestCase):
fixtures = ['users.json']
def test_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)
def test_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:

class AdminTest(LiveServerTestCase):
fixtures = ['users.json']
def setUp(self):
self.client = Client()
def test_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)
def test_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:

def test_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:

def test_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:

def test_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:

def test_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:

class PostViewTest(LiveServerTestCase):
def setUp(self):
self.client = Client()
def test_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:

Creating test database for alias 'default'...
......F
======================================================================
FAIL: test_index (blogengine.tests.PostViewTest)
----------------------------------------------------------------------
Traceback (most recent call last):
File "/Users/matthewdaly/Projects/django_tutorial_blog_ng/blogengine/tests.py", line 189, in test_index
self.assertTrue(post.title in response.content)
AssertionError: False is not true
----------------------------------------------------------------------
Ran 7 tests in 2.162s
FAILED (failures=1)
Destroying test database for alias 'default'...

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:

$ git clone https://github.com/matthewbdaly/django_tutorial_blog_ng.git
$ cd django_tutorial_blog_ng
$ git checkout lesson-1

That way, you can easily check that what you’ve done matches up with the repository. Future lessons will be similarly tagged to make them easy to navigate.

16th August 2013 9:49 pm

A Starting Boilerplate for PHP Development With Vagrant

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.

28th July 2013 7:20 pm

First Steps With Node.js

The idea of building an entire web app using nothing but JavaScript has always appealed to me. Despite its undoubted flaws, JavaScript is a powerful language, and chopping and changing between several different programming languages is never great. So I’ve always wanted to check out Node.js.

Lately I’ve been tinkering with Backbone.js a lot. As a web and mobile app developer, I’ve seen the benefit of server-side MVC frameworks firsthand, and I’ve also seen how bad a PhoneGap app can get without this kind of structure, so I’ve been very eager for a while to get my head around a JavaScript framework. The first one I was able to really grok was Knockout.js, thanks to its wonderful tutorial, but Backbone.js seemed to have better mindshare, and support for routing, so I knuckled down and used it for a large personal project that is still under wraps, but I hope to make available once complete. Using Backbone has made my client-side code far more organised, and I plan to use it a lot in future.

I’ve also wanted to get my head around a couple of the NoSQL databases. While the relational model is very often applicable, there are plenty of use cases where it isn’t the best choice, especially for simple data, and MongoDB seemed to be an interesting alternative. So, I decided to have a tinker around with Node.js and Backbone today, and wound up building a real-time guestbook application. Let me know what you think, but please be gentle - this is my first ever Node.js or MongoDB application.

21st April 2013 10:06 pm

My First Jquery Plugin

In my day job, I recently finished PagePooch, a tool for monitoring web pages for changes in content or prices. It’s a project that I’m immensely proud of, because it was my first big and largely solo project as a developer.

During the development of this, I initially created the user interface with jQuery Mobile, but later on added a desktop interface as well. During development of the desktop interface, I needed to recreate the functionality of the filter available for listviews in jQuery Mobile, and wound up creating a plugin for jQuery to do so.

I recently got permission to open-source this, as I figured the functionality was trivial enough that we couldn’t reasonably sell it, but by making it freely available, we’d maybe get some goodwill, and if we were really lucky, a few bugfixes and/or improvements.

It’s now available via the jQuery plugin registry. Please let me know what you think, and feel free to fork it and hack on it as you see fit.

Recent Posts

How Much Difference Does Adding An Index to a Database Table Make?

Searching Content With Fuse.js

Higher-order Components in React

Creating Your Own Dependency Injection Container in PHP

Understanding Query Objects

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, Zend Framework, Django, Phonegap and React.js.