Contributing Back to the Community - Django Cookbook

In the early beginning of year 2014, the IT book publishing company "Packt Publishing" contacted me with an interesting offer: to share my Django experience in a form of a book. I thought it might be a good challenge for me and also value for the Django community, as I had been working with Django for 7 years or so, and during that time there was quite a lot of knowledge gathered and used practically. So for the next 9 months on late evenings and weekends I was adapting some of the most useful code snippets and describing them in the book. The great staff from the Packt Publishing helped me to structure the content, make everything clear and understandable, and get the grammar correct. Finally, the book was released and it's called "Web Development with Django Cookbook".

This book is written for intermediate or advanced Django web developers. When writing the book, my own purpose was not to fully cover every possible web development task, but rather to have enough useful bits of knowledge for those who seek information about web development with Django. The book was written in the format of recipes. There are over 70 recipes giving you instructions how to deal with different challenges of web development. The code mentioned in the book is optimized for Django 1.6, but most of it should also work with older Django versions as well as with Django 1.7.

The cookbook consists of 10 chapters:

1. Getting started with Django 1.6. This chapter will guide you through the basic configuration which is necessary to start any Django project. It will cover topics like virtual environment, version control, and project settings.
2. Database Structure. When you create a new app, the first thing to do is to define your models. In this chapter you will learn how to write reusable pieces of code to use in your models. You will learn how to deal with multilingual data in your database. Also you will be told how to manage database schema changes using South migrations.
3. Forms and Views. To show your data or let one create it, you need views and forms. This chapter will show you some patterns for creating them.
4. Templates and JavaScript. Information is presented to the user by rendered templates. In modern websites, JavaScript is a must for richer user experience. This chapter shows practical examples of using templates and JavaScript together.
5. Custom Template Filters and Tags. The default Django template system is quite extensive, but there are more things to add for different cases. This chapter shows you how to create and use own template tags and filters.
6. Model Administration. Django framework comes with a handy pre-build administration. This chapter shows how to extend the default administration with your own functionality.
7. Django CMS. Django CMS is the most popular open source content management system made in Django. This chapter deals with best practices using Django CMS and extending it for your needs.
8. Hierarchical Structures. When you need to create a tree-like structure in Django, django-mptt module comes to hand. This chapter shows you how to use it and how to set administration for hierarchical structures.
9. Data Import and Export. Very often there are cases when you need to transfer data from and to different formats, retrieve it from and provide it to different sources. This chapter deals with management commands for data import and also APIs for data export.
10. Bells and Whistles. There is more to Django. This chapter shows additional snippets and tricks useful in web development with Django. Also you will learn about deployment of Django projects.

Get a copy of this book at Packt Publishing and tell me what you think about it in the comments below. Which recipes did you find the most useful? What would you like to read more in this blog or another edition of the cookbook?

Initial Data Using South Migrations

Usually when starting a new project with commonly used apps, you will need some default data for the database, for example, default categories. Django provides fixtures for that. A fixture is a collection of data that Django knows how to import into a database.

They say:

If you create a fixture named initial_data.[xml/yaml/json], that fixture will be loaded every time you run syncdb.

There is one problem with this approach. It is very likely that you will need to run syncdb in the future when adding new apps (without south migrations). In such cases the modified data will be overwritten with the initial data from fixtures.

But there is a solution for that problem. You need to name your fixtures differently and then import them by south migrations. If you don't use south, you should start doing that, because it is a very handy way to modify database schema and data automatically. :)

So this is how you can prepare south migration with the default fixture:

1. Create a fixture from existing models.

python manage.py dumpdata --format=json --indent=4 myapp.Category > /path/to/myapp/fixtures/myapp_categories.json

2. Create data migration

python manage.py datamigration myapp load_default_data

3. Edit data migration

class Migration(DataMigration):
    
    def forwards(self, orm):
        from django.core.management import call_command
        call_command("loaddata", "myapp_categories.json")
    
    def backwards(self, orm):
        pass

4. Migrate

python manage.py migrate myapp

Weather App Tutorial. Part 4 of 5. Template Tag

If you followed the first parts of the tutorial, you should have basic understanding how to create an app with models, set up administration, and retrieve data from third-party services. This part is about displaying collected data in any template using custom template tag.

At first, we need to create a directory templatetags containing an empty __init__.py file in the climate_change directory.

mkdir -p climate_change/templatetags
touch climate_change/templatetags/__init__.py

I will call the template library weather. So I have to create a file weather.py in climate_change/templatetags and define and register the template tag in that file. The template tag get_current_weather should display the current weather for a chosen location. To define what location you choose, you could refer to id, name or location_id, but none of them is appropriate for this reason. id and location_id are not remember-able and not informative enough, whereas the name might be changed to translate the city to another language or to add some more specifics and this change would detach the template tag from the location. For those reasons, it is best to create a new field sysname for the location model which would have a unique non-changeable value as a textual humanized identifier for templates.

But wait! It's such a pain to add new fields and modify database schema... Not, if you are using south! Let's quickly install it and then put it under INSTALLED_APPS.

easy_install south

#...
INSTALLED_APPS = (
    # django core
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.sites",
    "django.contrib.admin",
    # third-party
    "south",
    # project-specific
    "climate_change",
    )
#...

Note that south was installed in the virtual environment not spoiling the global python namespace. Now we will syncronize the database to create south_history table, create the initial migration for climate_change and apply it.

# create the missing database table from south app
python manage.py syncdb
# create initial migration for climate_change app which will be used by new projects
python manage.py startmigration climate_change --initial
# fake this migration for this project
python manage.py migrate climate_change --fake

Now we can finally add the new sysname field, create migration for it and apply it.

#...
class Location(models.Model):
    sysname = models.SlugField(
        _("system name"),
        max_length=200,
        unique=True,
        blank=True,
        default="",
        help_text=_("Do not change this value"),
        )
    name = models.CharField(_("name"), max_length=200)
    location_id = models.CharField(
        _("location ID"),
        max_length=20,
        help_text=_("Location IDs can be retrieved from URLs of weather "
            "at specific cities at Yahoo! Weather, e.g. GMXX0008 from "
            "http://weather.yahoo.com/forecast/GMXX0008.html"),
        )
#...

# create a new migration called "add_sysname"
python manage.py startmigration climate_change add_sysname --auto
# apply it to the database
python manage.py migrate climate_change

I had to set the default value to empty string because otherwise south throws exception when I use sqlite3. Anyway, after running those commands, I started the built in webserver again and added the sysname "berlin" to the record of Berlin's location.

We can get back to weather.py and add the template tag there

# -*- coding: UTF-8 -*-
from django.db import models
from django import template
from django.template import loader

register = template.Library()

### TAGS ###

def do_get_current_weather(parser, token):
    """
    Returns the latest known weather information.

    Usage::

        {% get_current_weather in <location_sysname> [using <template_path>] [as <var_name>] %}
    
    Examples::

        {% get_current_weather in "berlin" using "climate_change/custom_weather.html" %}

        {% get_current_weather in "london" as current_weather %}
        var sCurrentWeather = "{{ current_weather|escapejs }}";

    """    
    bits = token.split_contents()
    tag_name = bits.pop(0)
    template_path = ""
    var_name = ""
    location_sysname = ""
    try:
        while bits:
            first_word = bits.pop(0)
            second_word = bits.pop(0)
            if first_word == "in":
                location_sysname = second_word
            elif first_word == "using":
                template_path = second_word
            elif first_word == "as":
                var_name = second_word
                    
    except ValueError:
        raise template.TemplateSyntaxError, "get_current_weather tag requires a following syntax: {% get_current_weather [using <template_path>] [as <var_name>] %}"
    return CurrentWeatherNode(tag_name, location_sysname, template_path, var_name)

class CurrentWeatherNode(template.Node):
    def __init__(self, tag_name, location_sysname, template_path, var_name):
        self.tag_name = tag_name
        self.location_sysname = location_sysname
        self.template_path = template_path
        self.var_name = var_name
    def render(self, context):
        location_sysname = template.resolve_variable(
            self.location_sysname,
            context,
            )
        template_path = ""
        if self.template_path:
            template_path = template.resolve_variable(
                self.template_path,
                context,
                )
        context.push()
        WeatherLog = models.get_model("climate_change", "WeatherLog")
        logs = WeatherLog.objects.filter(
            location__sysname=location_sysname,
            ).order_by("-timestamp")
        if logs:
            context['weather'] = logs[0]
        output = loader.render_to_string(
            [template_path, "climate_change/current_weather.html"],
            context,
            )
        context.pop()
        if self.var_name:
            context[self.var_name] = output
            return ""
        else:
            return output


register.tag("get_current_weather", do_get_current_weather)

### FILTERS ###

# none at the moment

As you might see from the code, the template tag is using a template which can be redefined by the template designer. We still need the default template itself, so I will create a directory templates/climate_change and a file current_weather.html with this content:

{% load i18n %}
<div class="current-wheather">
    <h3>{{ weather.location.name }}</h3>
    <dl>
        <dt>{% trans "Temperature" %}:</dt>
        <dd>{{ weather.temperature }}° C</dd>
        <dt>{% trans "Humidity" %}:</dt>
        <dd>{{ weather.humidity }} %</dd>
        <dt>{% trans "Wind speed" %}:</dt>
        <dd>{{ weather.wind_speed }} km/h</dd>
        <dt>{% trans "Visibility" %}:</dt>
        <dd>{{ weather.visibility }} km</dd>
    </dl>
</div>

How can I test the template tag? I will need a new page which will include it. So I will add a rule in urls.py to redirect root url to index.html which will extend from base.html.

So the base.html looks like this:

{% block doctype %}>!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN""http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">{% endblock %}

{% load i18n %}

<html>
<head>
    <meta http-equiv="Content-type" content="text/html; charset=utf-8" />
    <title>{% block title %}simple document{% endblock %}</title>
    {% block extra_head %}{% endblock %}
</head>
<body>
    <div id="header">{% block header %}{% endblock %}</div>
    <div id="content">{% block content %}{% endblock %}</div>
    <div id="footer">{% block footer %}{% endblock %}</div>
</body>
</html>

The index.html looks like this:

{% extends "base.html" %}
{% load i18n weather %}
{% block content %}
    {% get_current_weather in "berlin" %}
{% endblock %}

And also we'll need an extension in the urls.py:

from django.conf.urls.defaults import *
from django.contrib import admin

admin.autodiscover()

urlpatterns = patterns("",
    (
        r"^$",
        "django.views.generic.simple.direct_to_template",
        {'template': "index.html"},
        ),
    (r"^admin/", include(admin.site.urls)),
    )

When I run the development server and go to http://127.0.0.1:8000/, I see this:



It's time for the graphs! The end of this tutorial will be published here tomorrow.