create models

Projects vs. apps

What's the difference between a project and an app? An app is a Web application that does something -- e.g., a Weblog system, a database of public records or a simple poll app. A project is a collection of configuration and apps for a particular Web site. A project can contain multiple apps. An app can be in multiple projects.

To create your app, make sure you're in the mysite directory and type this command:

python manage.py startapp polls

That'll create a directory polls, which is laid out like this:

polls/ __init__.py models.py tests.py views.py

This directory structure will house the poll application.

The first step in writing a database Web app in Django is to define your models -- essentially, your database layout, with additional metadata.

In our simple poll app, we'll create two models: polls and choices. A poll has a question and a publication date. A choice has two fields: the text of the choice and a vote tally. Each choice is associated with a poll.

These concepts are represented by simple Python classes. Edit the polls/models.py file so it looks like this:

from django.db import models class Poll(models.Model): question = models.CharField(max_length=200) pub_date = models.DateTimeField('date published') class Choice(models.Model): poll = models.ForeignKey(Poll) choice = models.CharField(max_length=200) votes = models.IntegerField()

The code is straightforward. Each model is represented by a class that subclasses . Each model has a number of class variables, each of which represents a database field in the model.

Each field is represented by an instance of a Field class -- e.g., for character fields and for datetimes. This tells Django what type of data each field holds.

The name of each Field instance (e.g. question or pub_date ) is the field's name, in machine-friendly format. You'll use this value in your Python code, and your database will use it as the column name.

You can use an optional first positional argument to a Field to designate a human-readable name. That's used in a couple of introspective parts of Django, and it doubles as documentation. If this field isn't provided, Django will use the machine-readable name. In this example, we've only defined a human-readable name for Poll.pub_date. For all other fields in this model, the field's machine-readable name will suffice as its human-readable name.

Some Field classes have required elements. , for example, requires that you give it a max_length. That's used not only in the database schema, but in validation, as we'll soon see.

Finally, note a relationship is defined, using . That tells Django each Choice is related to a single Poll. Django supports all the common database relationships: many-to-ones, many-to-manys and one-to-ones.

Activating models

That small bit of model code gives Django a lot of information. With it, Django is able to:

• Create a database schema (CREATE TABLE statements) for this app.
• Create a Python database-access API for accessing Poll and Choice objects.

But first we need to tell our project that the polls app is installed.

dit the settings.py file again, and change the setting to include the string 'polls'. So it'll look like this:

INSTALLED_APPS = ( 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', 'django.contrib.sites', 'polls' )

Now Django knows to include the polls app. Let's run another command:

python manage.py sql polls

python manage.py syncdb

The command runs the sql from 'sqlall' on your database for all apps in that don't already exist in your database. This creates all the tables, initial data and indexes for any apps you have added to your project since the last time you ran syncdb. can be called as often as you like, and it will only ever create the tables that don't exist.

Read the django-admin.py documentation for full information on what the manage.py utility can do.