Django 1.0 Template Development

In some development platforms, such as PHP and ASP, the programming code and the HTML markup is all contained in a single file that gets processed and returned by the web server. In complex pages, this approach can become difficult to develop and maintain because there isn't a separation between the presentation and the programming logic used to render it.

Having programming logic mixed in with your markup code also limits the ability for designers to work in the files, unless they also understand the bits of programming logic sprinkled within. This makes changing the markup both tedious and time-consuming because the developer usually has to do the updates.

This clearly isn't a productive way to develop applications. We end up with a number of requirements that need to be addressed:

Instead of mixing programming code and presentation markup (such as HTML) in the same files, we create templates that have placeholders where the data will go. When the template engine renders the templates, these placeholders are replaced with their appropriate values. By the time the output is returned to the web browser, all traces of the template have been removed, leaving only the resulting output.

As we have seen, Django templates, typically, are files loaded by the template engine and rendered into output that will be sent back to the browser. This loading and rendering takes place in the view, the function that Django calls to fulfill requests.

In order to accomplish basic output logic, such as looping through records and creating table rows, some programming code needs to exist in the template files. The amount of programming you can do in your template depends on your programming language or framework; Django allows basic looping and conditional logic. The process of rendering executes this template logic and replaces placeholders with data.

By separating templates out of framework code into their own files, developers and designers can work simultaneously on the same project without stepping on each other's work. This approach has the added benefit that there is a clear differentiation between design and development; coders stay out of the design arena and designers stay out of the programming arena—we can live in harmony! (Well, maybe...)

Keeping the template clear of code also makes it easier to work in WYSIWYG (What You See Is What You Get) editors such as Dreamweaver and Homesite. We're not going to cover that in the book, but it's worth mentioning.

The template files are usually located in their own folders nested somewhere in the Django project. The templates can include other templates in them, and so common page elements such as menus, headers, and footers can be kept in their own files. Including common elements from single files increases the maintainability of our application by reducing the amount of common output markup that is duplicated in different files. Instead of hunting around for all the occurrences of some HTML to replace, we can make the change in one place and all templates that include the content will be updated automatically.

Templates can also have parent templates that simplify the development of sections of a site. For example, if we have a calendar listing in the events section of a website, we might use three templates:

This prevents the duplication of site- and section-wide HTML by keeping them in single files. We'll explore the parent-child relationship and inheritance of templates in great detail in a later chapter.

The syntax of the template system is intentionally clean, simple, and elegant. With a minimal understanding of programming concepts, you can make powerful and flexible templates to output your data.

We'll cover these concepts and the syntax of the template language later in this chapter.

Django ships with many built-in template elements that we can use to control and format the output of our templates. You can also write your own template elements, if you have a need that isn't met by the default libraries, or use ones that other developers have written. Sites such as DjangoSnippets.org contain many template libraries that developers have shared and can be easily incorporated into your own site.

In a later chapter, we'll cover writing your own template element libraries and how to install and use libraries that others have written.

The template system is flexible enough so that we can output any kind of data that we want. It doesn't assume (or require) that you are going to produce HTML. We can dynamically generate PDF documents, CSV files, HTML files, microformats, and text documents. It also doesn't require you to write your templates in any specific format (such as XML) the way some other Python templating languages do.

Even though you can extend the template system with custom elements to fit your needs, the Django creators gave us the ultimate back door—You don't have to use their template system! You are free to implement any Python template system and libraries of your choice, and you can do it on an as-needed basis in only the places you desire. For example, if you want to use the Django template system for half of your views and the open-source Genshi templating system for the other half, there's no penalty.

The elegance and simplicity of the Django template system comes at a price; there are a few limitations to be aware of. In a nutshell, only the processing of simple presentation logic is supported in templates. You can loop over sets of data and check the value of objects and variables to perform conditional logic, but you cannot perform complex logic and execute raw Python code.

Here are a few things you cannot do using the Django template system syntax:

If you need to perform these kinds of actions, you can often write your own extensions to the template system. We will fully cover these limitations and their implications later in the book.

Some critics argue that the Django template system is too simple and isn't robust enough to perform complex formatting or outputting. This may be true, but remember that these limitations are intentional to achieve the design goals we discussed earlier. You're also free not to use Django's template system and use a more liberal template library if you choose.

If you recall the request-handling overview, we said the context was a special object that contained the values available to the template when it is rendered. We'll work through a practical example later in the chapter. For now, just think of it as a dictionary of variables that the template will be able to see (see the upcoming code note if you don't know what a Python dictionary is).

Variables are the basic placeholders in a Django template. They are identified by two curly brackets on each side:

My favorite color is {{ color }}.

When the Django template engine renders this page, it will see {{ color }} as a placeholder for the real value it is supposed to put in its place. It looks in the context for a key named color and finds the value associated. If our context has a key named color and an associated value of blue, the output would look like this:

My favorite color is blue.

Filters can format the output of variables in Django templates. They are identified by the use of a pipe symbol immediately following a template variable:

My favorite color is {{ color|upper }}.

In this example, upper is the filter we are using to modify the variable color. (Notice there is no space between the variable, the pipe, and the filter.) The upper filter will take the value of the variable and convert all the letters to upper case. (Specifically, it applies the Python string function upper() to the value.) Here is the resulting output:

My favorite color is BLUE.

Django ships with a number of default filters that cover many common presentation-formatting needs. You can find them listed in the Django documentation at DjangoProject.com.

Template tags instruct the template rendering engine to perform some kind of action. They are identified by a curly bracket and percentage symbol, and often have an accompanying closing tag:

{% ifequal color 'blue' %}
  Wow, you like blue!
{% else %}
  Why don't you like blue?
{% endifequal %}

In this example, we are using the template tag ifequal. It takes two arguments, which means the values to be compared. Unlike Python code, we don't use parentheses or commas around the arguments. We just use a space between the template tag and each of the arguments. The tag also has a corresponding closing tag endifequal that tells the template engine we are done.

In this example, since the value of the variable is blue, we get this output:

Wow, you like blue!

Like filters, Django ships with a number of default tags that perform common logic in templates such as looping through sets of data. We'll be covering tags and filters in more depth in later chapters as well as writing our own custom tags.

When the templates are rendered, the tags are removed by the template engine. If you view the source of your output, you will not see your tags, though you will probably see a blank space where the tag was.

There are two kinds of comments we can use in Django templates: single-line and multi-line. Like comments in Python, you can leave yourself notes in a template or use comments to prevent a chunk of template code from being rendered by the template engine. Single-line comments are identified by a curly bracket and a hash mark (also known as the number sign or pound symbol):

{# Remember to move this down the page later #}
My favorite color is {{ color }}.

Multi-line comments are implemented as tags, and they have a corresponding endcomment tag:

{% comment %}
{% ifequal color 'blue' %}
  Wow, you like blue!
{% else %}
  Why don't you like blue?
{% endifequal %}
{% endcomment %}

In this example, the template engine ignores everything between the comment and endcomment tags. This is often used to troubleshoot and debug a section of template that isn't behaving properly.

Like template tags, single- and multi-line comments are removed from the resulting output by the template engine. They are not the same as HTML comments; you won't see them if you view the source of your output.

In case you are not familiar with Python dictionaries, here is a basic explanation.

A dictionary is one of Python's built-in data types, similar to hashes in other programming languages. It consists of keys and values. The key is the label used to identify the item, and the value is what it is equal to.

Here's an example:

>> mydictionary = {}
>> mydictionary['mykey'] = 'myvalue'
>> mydictionary['myotherkey'] = 10
>> print mydictionary
{'mykey': 'myvalue', 'myotherkey': 10}

The first line tells Python that we are creating a new dictionary called mydictionary. The empty curly brackets tell Python that we are creating a variable that is of type dictionary and not a string or integer. The next two lines add keys and values to the dictionary. The first adds a new key called mykey that has a value of myvalue. The second has a key of myotherkey and has a value of 10.

You can also create a dictionary in one step:

>> mydictionary = {'mykey': 'myvalue', 'myotherkey': 10}

This may look a little more complex, but it does the same thing the first three lines of our example above did.

Why is all of this important? It lets us keep all of our values grouped under a single variable. In the Django template language, the Context holds a dictionary of all the values we are going to make available to our template. When Django passes the dictionary to the template, the keys are what the placeholders are going to work with to be replaced with their values.

If you try to use a variable in your template that has not been made available to the context object, you will not get an error. The template system simply ignores it and keeps on going. This was a design decision by the Django developers to prevent a missing data item from "breaking" an application.

If you have an error with a template tag, however, you will get an error.

We now have an empty skeleton of a project upon which we can start building applications. The first application we are going to work with will just be a demonstration to get us warmed up.

Step 1: Create the demo project

In the mycompany directory, run this command:

$ python manage.py startapp demo

This will create a demo directory under the mycompany directory.

Step 2: Add a detail function to the demo view

In the file mycompany/demo/views.py, add these lines:

from django.http import HttpResponse

def detail(request):
    return HttpResponse('got here!')

Step 3: Add a URL pattern for our demo project

In the file mycompany/urls.py, edit the file to look like this:

from django.conf.urls.defaults import *

urlpatterns = patterns('',
    (r'^demo/$', 'mycompany.demo.views.detail'),
)

This tells the URL dispatcher that if it matches a URL of http://localhost:8000/demo/, call the detail function inside the file mycompany/demo/views.py.

Step 4: Make sure it worked

In the mycompany directory, run this command:

$ python manage.py runserver

This will start the Django development server. You should see something very similar to the following:

Validating models...
0 errors found
Django version 1.0-final-SVN-unknown, using settings 'mycompany.settings'
Development server is running at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Browse to http://localhost:8000/demo/. You should see the got here! line we wrote in our view.

Congratulations! We've created our first Django view. We've built a solid base to start from and we're ready to start playing with views, contexts, and (of course!) templates.

The app we built in the last section serves a page, but it's only a starting point for the application we are going to build. Let's use it to explore some concepts of how Django templates work.

from django.http import HttpResponse
from django.template import Context, Template, loader

def detail(request):
    dict_values = {'fav_color': 'blue'}
    template_string = "My favorite color is {{ fav_color }}."
    c = Context(dict_values)
    t = Template(template_string)
    rendered_template = t.render(c)
    return HttpResponse(rendered_template)

def detail(request):
    c = Context({'fav_color': 'blue'})
    t = Template("My favorite color is {{ fav_color }}.")
    return HttpResponse(t.render(c))

TEMPLATE_DIRS = (
    '/projects/mycompany/templates/',
)

DEBUG = True
TEMPLATE_DEBUG = True

My favorite color is {{ fav_color }}.

def detail(request):
    c = Context({ 'fav_color': 'blue' })
    t = loader.get_template('example.html')
    rendered_template = t.render(c)
    return HttpResponse(rendered_template)

My favorite color is {{ fav_color|upper }}.

{% ifequal fav_color 'blue' %}
  My favorite color is {{ fav_color }}.
{% else %}
  My favorite color is not blue.
{% endifequal %}

def detail(request):
    c = Context({ 'fav_color': ['blue','green'] })
    t = loader.get_template('example.html')
    rendered_template = t.render(c)
    return HttpResponse(rendered_template)

{% for color in fav_color %}
  My favorite color is {{ color }}.<br/>
{% endfor %}

{% for color in fav_color %}
  {# We are writing out a comment here #}
  My favorite color is {{ color }}.<br/>
{% endfor %}

{% comment %}
My comment
is more than 
one line long
{% endcomment %}