The easiest way to organize your Django code when you are starting out is to use what Django calls a project:A directory of files that constitute, usually, a single Web site. Django comes with a utility called django-admin.py to streamline tasks such as the creation of these project directories. On Unix, it has a default installation into the /usr/bin directory, and if you’re on Win32, it goes into the Scripts folder right in your Python installation, for example, C:Python25Scripts. In either case, you need to make sure that django-admin.py is in your PATH so it can be executed from the command line.

To create the project directory for your blog project, issue this django-admin.py command:

django-admin.py startproject mysite

On a Win32 box, you need to open a DOS Command window first. It can be accessed via Start -> Programs -> Accessories -> Command Prompt. Also, instead of a $, you see something like C:WINDOWSsystem32> as a shell prompt.

Now take a look at the contents of the directory to see what this command has created for you. It should look something like this on Unix:

$ cd mysite
$ ls -l
total 24
-rw-r--r--    1 pbx  pbx     0 Jun 26 18:51 __init__.py
-rwxr-xr-x    1 pbx  pbx   546 Jun 26 18:51 manage.py
-rw-r--r--    1 pbx  pbx  2925 Jun 26 18:51 settings.py
-rw-r--r--    1 pbx  pbx   227 Jun 26 18:51 urls.py

If you were developing on a Win32 platform, opening an Explorer window to that folder looks something like Figure 2.1, if we created a folder named C:pydjango with the intention of putting our project there.

Figure 2.1. mysite folder on Win32

Besides __init__.py, the startproject command has created three other files.

At this point, you haven’t built your blog application yet, but nonetheless there are some Django conveniences in place for your use. One of the handiest is Django’s built-in Web server. It’s a server designed not for deploying public sites, but for quick development. Advantages of using it include

Running the development (or “dev”) server is as simple as issuing a single command. We’re going to use our project’s manage.py utility, a thin wrapper script that saves us the work of telling django-admin.py to use our specific project settings file. The command to run the dev server is

./manage.py runserver       # or ".manage.py runserver" on win32

You should see something like the following with a slight difference for Win32 platforms where the quit key combination is CTRL-BREAK instead of CONTROL-C:

Validating models...
0 errors found.

Django version 1.0, using settings 'mysite.settings'
Development server is running at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Open that link in your browser, and you should see Django’s “It Worked!” screen, as shown in Figure 2.2.

Figure 2.2. Django’s initial It worked! screen

Meanwhile, if you look in your terminal session, you see the dev server has logged your GET request.

[07/Dec/2007 10:26:37] "GET / HTTP/1.1" 404 2049

The four chunks of the log line are from left to right: timestamp, request, HTTP response code, and byte count. (Your byte count is likely to be slightly different.) The response code is 404 (“Not Found”) because your project has no URLs defined yet. The It Worked! page is Django’s friendly way of telling you that.

When you’ve successfully got the server running, we can move on to setting up your first Django application.

Now that we have a project, we can create applications (or “apps” in Django-speak) within it. To create our blog app, we’ll use manage.py again.

./manage.py startapp blog   # or ".manage.py startapp blog" on win32

It’s just as simple as starting a project. Now we have a blog directory inside our project directory. Here’s what’s in it, first in Unix format, and then in a screenshot of Windows Explorer (see Figure 2.3).

$ ls -l blog/
total 16
-rw-r--r--   1 pbx  pbx   0 Jun 26 20:33 __init__.py
-rw-r--r--   1 pbx  pbx  57 Jun 26 20:33 models.py
-rw-r--r--   1 pbx  pbx  26 Jun 26 20:33 views.py

Figure 2.3. mysitelog folder on Win32

Like your project, your app is a package too. The models.py and views.py files have no real code in them; they’re merely placeholders. For our simple blog, in fact, we don’t need to touch the dummy views.py file at all.

To tell Django this new app is part of your project, you need to edit settings.py (which we can also refer to as your “settings file”). Open your settings file in your editor and find the INSTALLED_APPS tuple near the bottom. Add your app in dotted module form to that tuple in a line that looks like this (note the trailing comma):

'mysite.blog',

Django uses INSTALLED_APPS to determine the configuration of various parts of the system, including the automatic admin application and the testing framework.

We’ve now arrived at the core of your Django-based blog application: the models.py file. This is where we’ll define the data structures of the blog. Following the principle of Don’t Repeat Yourself (DRY), Django gets a lot of mileage out of the model information you provide for your application. Let’s create a basic model, and then see all the stuff Django does for us using that information.

Open up models.py in your favorite text editor (bonus points if it has a Python mode with syntax coloring). You see this placekeeper text:

from django.db import models

# Create your models here.

Delete the comment, and then add the following lines:

class BlogPost(models.Model):
    title = models.CharField(max_length=150)
    body = models.TextField()
    timestamp = models.DateTimeField()

That’s a complete model, representing a “BlogPost” object with three fields. (Actually, strictly speaking it has four fields—Django automatically creates an auto-incrementing, unique id field for each model by default.)

You can see our newly minted class, BlogPost, is a subclass of django.db.models.Model. That’s Django’s standard base class for data models, which is the core of Django’s powerful object-relational mapping system. Also, you notice our fields are defined like regular class attributes with each one being an instance of a particular field class. Those field classes are also defined in django.db.models, and there are many more types—ranging from BooleanField to XMLField—than the three we’re using here.

If you don’t have a database server installed and running, we recommend SQLite as the fastest and easiest way to get going. It’s fast, widely available, and stores its database as a single file in the filesystem. Access controls are simply file permissions. For more on how to set up a a database for use with Django, see Appendix B.

If you do have a database server—PostgreSQL, MySQL, Oracle, MSSQL—and want to use it rather than SQLite, then use your database’s administration tools to create a new database for your Django project. We name this database “djangodb” in our examples, but you can name it whatever you like.

Either way, with your (empty) database in place, all that remains is to tell Django how to use it. This is where your project’s settings.py file comes in.

DATABASE_ENGINE = "mysql"
DATABASE_NAME = "djangodb"
DATABASE_HOST = "localhost"
DATABASE_USER = "paul"
DATABASE_PASSWORD = "pony"  # secret!

DATABASE_ENGINE = "sqlite3"
DATABASE_NAME = "/var/db/django.db"

DATABASE_ENGINE = 'sqlite3'
DATABASE_NAME = r'C:pydjangodbdjango.db'

./manage.py syncdb          # or ".manage.py syncdb" on win32

Creating table auth_message
Creating table auth_group
Creating table auth_user
Creating table auth_permission
Creating table django_content_type
Creating table django_session
Creating table django_site
Creating table blog_blogpost

You just installed Django's auth system, which means you don't have any superusers
defined.
Would you like to create one now? (yes/no): yes
Username (Leave blank to use 'pbx'):
E-mail address: [email protected]
Password:
Password (again):
Superuser created successfully.
Installing index for auth.Message model
Installing index for auth.Permission model

Loading 'initial_data' fixtures...
No fixtures found.

The automatic back-end application, or admin, has been described as Django’s “crown jewel.” For anyone who has tired of creating simple “CRUD” (Create, Read, Update, Delete) interfaces for Web applications, it’s a godsend. We get much deeper into the admin in “Customizing the Admin” in Chapter 11, “Advanced Django Programming.” For now, let’s just turn it on and poke around.

Because it’s an optional part of Django, you need to specify in your settings.py file you’re using it—just like you did with your own blog app. Open settings.py and add the following line to the INSTALLED_APPS tuple, just underneath 'django.contrib.auth'.

'django.contrib.admin',

Every time you add a new application to your project, you should run the syncdb command to make sure the tables it needs have been created in your database. Here we can see adding the admin app to INSTALLED_APPS and running syncdb triggers the creation of one more table in our database:

$ ./manage.py syncdb
Creating table django_admin_log
Installing index for admin.LogEntry model
Loading 'initial_data' fixtures...
No fixtures found.

Now that the app is set up, all we need to do is give it a URL so we can get to it. You should have noticed these two lines in your automatically generated urls.py.

# Uncomment this for admin:
#    (r'^admin/', include('django.contrib.admin.urls')),

Remove the # character from the second line (and you can remove the first, comment-only line at the same time) and save the file. You’ve told Django to load up the default admin site, which is a special object used by the contrib admin application.

Finally, your applications need to tell Django which models should show up for editing in the admin screens. To do so, you simply need to define the default admin site mentioned previously and register your BlogPost model with it. Open the mysite/blog/models.py file, make sure the admin application is imported, and then add a line registering your model at the bottom.

from django.db import models
from django.contrib import admin

class BlogPost(models.Model):
    title = models.CharField(max_length=150)
    body = models.TextField()
    timestamp = models.DateTimeField()

admin.site.register(BlogPost)

This simple use of the admin is the tip of the iceberg; it’s possible to specify many different admin-related options by making a special Admin class for a given model, and then registering the model with that class. We do this shortly, and you also see examples of advanced admin use in later chapters, especially in Parts III, “Django Applications by Example,” and IV, “Advanced Django Techniques and Features.”

Now that we’ve set up our Django site with the admin app and registered our model with it, we can take it for a spin. Issue the manage.py runserver command again. Now, go to http://127.0.0.1:8000/admin/ in your Web browser. (Don’t worry if your dev server address is different; just add an admin/ onto it, whatever it is.) You should see a login screen, as shown in Figure 2.4.

Figure 2.4. The admin login screen

Type the “superuser” name and password you created earlier. Once you’ve logged in, you see the admin home page, as shown in Figure 2.5.

Figure 2.5. The admin home page

We’ll tour this interface later in the book; for now, just confirm your application, Blog, is showing up as seen in the screenshot. If it’s not, recheck the previous steps.

What’s a blog without content? Click the Add button to the right of Blog Posts. The admin presents a form for adding a new post, as shown in Figure 2.6.

Figure 2.6. Adding new content via the admin

Give your post a title and some scintillating content. For the timestamp, you can click the Today and Now shortcut links to fill in the current date and time. You can also click the calendar or clock icons to pull up handy date and time pickers.

When you’re done writing your masterpiece, click the Save button. You see a screen with a confirmation message (“The blog post ‘BlogPost object’ was added successfully”) and a list of all your blog posts—a grand total of one at this point, as shown in Figure 2.7.

Figure 2.7. Successfully saving your first blog entry

Why is the post given the awkward name of “BlogPost object”? Django is designed to flexibly handle an infinite variety of content types, so it doesn’t take guesses about what field can be the best handle for a given piece of content. Throughout Part 3’s example applications, you see examples of defining how to specify a particular field, or specially constructed string, to be used for your objects’ default labels.

Now go ahead and add a second post with different content by clicking on the Add Blog Post + button to the upper-right. When you are returned to the list view, you just see another BlogPost row added to the page. If you refresh the page or go away and come back to your application, the output has not improved any—you just do not feel satisfied with seeing all the entries generically labeled as “BlogPost object,” as shown in Figure 2.8. You are not alone if you’re thinking, “There has got to be a way to make it look more useful!”

Figure 2.8. Not the most useful summary page

However, we don’t have to wait until then to clean up the list display in our admin view. Previously, we enabled the admin tool with the bare minimum of configuration, namely registering our model with the admin app all by itself. However, with an extra two lines of code and a modification of the registration call, we can make the presentation of the listing much nicer and more usable. Update your mysite/blog/models.py file with a new BlogPostAdmin class and add it to the registration line, so your models.py looks like this:

from django.db import models
from django.contrib import admin

class BlogPost(models.Model):
    title = models.CharField(max_length=150)
    body = models.TextField()
    timestamp = models.DateTimeField()

class BlogPostAdmin(admin.ModelAdmin):
    list_display = ('title', 'timestamp')

admin.site.register(BlogPost, BlogPostAdmin)

The development server notices your changes and reloads your models file. If you are monitoring your command shell, you see some output to this effect.

If you refresh the page, you now see much more useful output based on the new list_display variable you added to your BlogPostAdmin class (see Figure 2.9).

Figure 2.9. Much better

Try clicking on the Title and Timestamp column headers that have appeared—each one affects how your items are sorted. For example, click once on Title to sort in ascending order by title; click the Title header a second time to change to descending order.

The admin has many other useful features that can be activated with just a line or two of code: searching, custom ordering, filters, and more. As we’ve mentioned a few times already, Parts III and IV cover or demonstrate many of these topics in greater detail.

With the database and admin side of our application taken care of, it’s time to turn to the public-facing pages. A page, from Django’s perspective, has three typical components:

We’ll tackle these three in that order. In a sense this is building from the inside out—when Django processes a request, it starts with the URL patterns, then calls the view, and then returns the data rendered into a template.

<h2>{{ post.title }}</h2>
<p>{{ post.timestamp }}</p>
<p>{{ post.body }}</p>

{% for post in posts %}
<h2>{{ post.title }}</h2>
<p>{{ post.timestamp }}</p>
<p>{{ post.body }}</p>
{% endfor %}

mysite/blog/templates/archive.html

from django.template import loader, Context
from django.http import HttpResponse
from mysite.blog.models import BlogPost

def archive(request):
    posts = BlogPost.objects.all()
    t = loader.get_template("archive.html")
    c = Context({ 'posts': posts })
    return HttpResponse(t.render(c))

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

from django.conf.urls.defaults import *
from mysite.blog.views import archive

urlpatterns = patterns('',
    url(r'^$', archive),
)

Using the key concepts laid out so far, you could go forward and refine this primitive blog engine in a number of ways. Let’s step through a few of them to make this project feel just a little more polished.

Template Niceties

Our template is plain to say the least. Because this is a book on Web programming not Web design, we leave the aesthetic touches to you, but template inheritance is another feature of the template system that can make your life easier, especially as your page styles proliferate.

Our simple template is completely self-contained. But what if our site had a blog, a photo archive, and a links page, and we wanted all these to be based on a common base? Experience tells you the wrong way to do this would be to copy and paste your way to three kind-of-identical self-contained templates. The right way in Django is to create a base template, and then extend this template to generate the other, specific templates. In your mysite/blog/templates directory, create a template called base.html containing the following:

<html>
<style type="text/css">
body { color: #efd; background: #453; padding: 0 5em; margin: 0 }
h1 { padding: 2em 1em; background: #675 }
h2 { color: #bf8; border-top: 1px dotted #fff; margin-top: 2em }
p { margin: 1em 0 }
</style>
<body>
<h1>mysite.example.com</h1>
{% block content %}
{% endblock %}
</body>
</html>

Not exactly valid XHTML Strict, but it’ll do. The detail to notice is the {% block ... %} tag. This defines a named area that subtemplates can change. To make your blog app use this template, change your archive.html template so it references this new base template and its “content” block.

{% extends "base.html" %}
{% block content %}
{% for post in posts %}
<h2>{{ post.title }}</h2>
<p>{{ post.timestamp }}</p>
<p>{{ post.body }}</p>
{% endfor %}
{% endblock %}

The {% extends ... %} tag tells Django to look for a template named base.html, and plug the content of any named blocks in this template into the corresponding blocks in that template. You should now see something like Figure 2.10 (hopefully your blog posts are more exciting, though).

Figure 2.10. The blog, lightly styled

class Meta:
    ordering = ('-timestamp',)

<p>{{ post.timestamp|date }}</p>

<p>{{ post.timestamp|date:"l, F jS" }}</p>

Of course, we could continue adding features to our blog engine forever (many people do!), but hopefully you’ve seen enough to give you a taste of the power of Django. In the course of building this skeletal blog app you’ve seen a number of Django’s elegant, labor-saving features:

Just to give you an idea of what’s ahead, the following are some things we could proceed to do to our blog using Django’s built-in features:

You’ve completed your whirlwind tour of Django basics. Chapter 3, fleshes out with a broad look at Django’s key components and the philosophies behind them, as well as provides a recap of some Web development principles central not only to Django itself, but to the lessons we offer in later parts of the book. Chapter 4, takes you down into the details of the framework, where you find answers to the questions of “how, why, and what about ...?” that probably arose as you walked through the previous examples. After Chapter 4, you have a solid enough understanding to follow along and build several example applications: a content management system, a pastebin, a photo gallery, and an Ajax-powered “live blog.”