Django (http://djangoproject.com) is a rapid application development (RAD) framework for building database-oriented web applications using Python. The Django framework is highly respected and is used to power thousands of web applications currently deployed across the internet. The major parts of Django include an object-relational mapper, an automatically generated admin interface, a flexible URL mapper, and a web templating system. Putting these elements together, Django allows you to quickly build sophisticated web applications to implement a wide variety of database-oriented systems.

In Django, you work with a project that is made up of a number of individual apps. Each app implements a specific set of functionality, for example, authenticating users, generating reports, or responding to API requests. When you create a project, you typically write one or more apps yourself and make use of a number of predefined apps that come built into Django.

One of the most useful built-in apps is the admin interface, which allows you to administer your web application, view and edit data, and so on. Other useful built-in apps implement persistent sessions, user authentication, site maps, user comments, sending emails, and viewing paginated data. A large number of user-contributed apps are also available.

Let's use Django to create a simple web application. We'll start by installing Django. The easiest way to do this is to use pip, the Python package manager. From the command line, type pip install django. If this doesn't work, for example, because you don't have pip installed, you can download a copy of Django from https://www.djangoproject.com/download.

Once it is installed, open up a terminal window and cd into the directory where you want to place your new web application's project. Then, type django-admin startproject example.

This will create a new Django project named example, which will be stored in a directory with the same name. This directory is just a container for your project; inside it, you will find the following:

manage.py
example/
    __init__.py
    settings.py
    urls.py
    wsgi.py

Let's take a closer look at these various files and folders:

Now that we have a Django project, let's create a simple app that will run within it. Our app, which we will call hello, simply displays the following message to the user:

Hello Number X.

X is a number that increases each time the page is displayed. While this example app may seem trivial, it demonstrates a number of key features of Django:

To create this app, cd into your outermost example directory and enter the following command:

python manage.py startapp hello

This will create a new sub-directory named hello within your outermost example directory. This directory is a Python package that holds the various parts of your new Django app. If you look in this directory, you will find the following items:

Our next task is to tell the example project to use our newly created hello app. To do this, edit the example/settings.py file, and look for a variable named INSTALLED_APPS. This is a list of the apps that are used by the project. As you can see, a number of built-in apps are installed by default. Edit this list so that it looks like the following:

INSTALLED_APPS = (
    #'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'hello'
)

Notice that we've commented out the django.contrib.admin app, as we won't want to use the admin interface for our simple example project. We've also added the hello app to our project.

Our next step is to set up the database model. Because our hello app needs to keep track of how often the Hello message has been displayed, we will create a model named Counter which keeps track of how often the message has been displayed. To do this, edit your hello/models.py module, and add the following to the end of it:

class Counter(models.Model):
    count = models.IntegerField()

A database model (that is, a subclass of the django.db.models.Model class) is a Python class that defines the structure of a database table. In our example, we've created a very simple database model—just one model, Counter, which has a single field named count. There's a lot more that can be done with database models, including defining relations between models, setting default behavior, adding custom methods to a model, and so on, but this is all we need for our example project.

Save the models.py file, then open up a terminal or command-line window, cd into your outermost example directory, and enter the following command:

python manage.py makemigrations hello

The makemigrations command looks at the database models you have defined for the hello app and figures out what changes have occurred to the database structure since the last time the command was run. Because this is the first time we've run this command, a new database table will be created that matches the structure of your Counter class.

If you look inside your hello/migrations directory, you'll see that a new file has been created: 0001_initial.py. This file contains the detailed instructions needed by Django to create the database table corresponding to your database model.

Now that the migration file has been created, we need to apply it. To do this, enter the following command:

python manage.py migrate

The migrate command applies all unapplied database migrations. Because a number of standard apps are included in your project, they will have their own database migrations, which will be applied at the same time.

We now have a database that includes, among other things, our new Counter model. You might be wondering where this database is. By default, Django makes use of the SQLite database engine, creating a simple database on disk which it uses to store your project's data. You can change this if you want by editing the DATABASES setting in your example/settings.py module.

Now that we have a database, let's make use of it. Since our example project needs to display a message to the user, we next have to create two things: a URL mapping that tells Django which function to call when the user attempts to access the system and a view function which will respond when that URL is accessed.

In a real system, URL mappings can get quite sophisticated, but for our program, we're going to use a very basic mapping. Edit the example/urls.py module and add the following import statement to the top of it:

from hello import views

This makes the hello app's view functions (which we will create in the hello/views.py module) available for use in our URL mappings. Next, replace the existing definition for the urlpatterns variable with the following:

urlpatterns = [
    url('^$', views.say_hello)
]

Notice that we've removed the reference to the admin interface, since we aren't using it in our project. The url() function defines a single URL mapping that maps the rather cryptic-looking '^$' URL pattern to a function named say_hello() within our hello/views.py module. The '^$' string is a regular expression that will match against the top-level URL for our project. In other words, if the user accesses the project's top-level URL, the views.say_hello() function will be called to respond to the user's request.

Save the changes you have made to the urls.py module, and then edit the hello/views.py module. This is where you will define the view functions for the hello app. We're going to create a single function named say_hello() which will respond when the user accesses our project's top-level URL.

Before we write our say_hello() function, let's think for a moment what this function is supposed to do. We need to display a message that looks like the following:

Hello Number X.

The value for X is taken from our Counter database model and is incremented each time our view is called. So, our first step is to load a Counter record, creating it if it doesn't already exist, and then increment it. We can then display the Hello Number X message based on the counter's current value.

We start by importing the Counter class into our views.py module:

from hello.models import Counter

We then define our say_hello() function. In Django, a view function takes a request object, which provides information about the HTTP request that was received from the user's web browser, and returns a response object containing the information to be sent back to the user's web browser for display. This means that the basic structure of a Django view function looks like this:

def view_function(request):
    ...
    return response

In our case, we don't really care about the request object, as we don't need to use any of the information it may contain. We do, however, have to return a response.

Let's start by defining the first part of our view function. To do this, add the following to the end of your views.py module:

def say_hello(request):

Our view function needs to load the Counter record from the database, creating it if necessary. Using Django's object-relational mapper, we can do this using the Counter class directly:

    counter = Counter.objects.first()
    if counter == None:
        counter = Counter(count=0)

We then increment the counter and save it back into the database:

    counter.count = counter.count + 1
    counter.save()

We now have the value for X that we want to include in the Hello Number X message. Our final step is to create an HTTP response object that includes this message so that we can use it as the function's return value.

While there are many ways in which we can create an HTTP response object, we will use Django's built-in templating system to create the response. Doing this is easy:

    return render(request, "say_hello.html",
                  {'count' : counter.count})

The render() function takes the HTTP request object, the name of the template file to use, and a "context" dictionary that holds values to be included in the template. In this case, we will use the say_hello.html template and supply a value named count, which will be included in the template.

We have almost completed our example project. All that's left is to create the HTML template: inside the hello app's directory, create a new directory named templates, and then create a file named say_hello.html within it. Then, enter the following into this file:

<html>
  <head>
    <title>Hello Example</title>
  </head>
  <body>
    Hello Number {{ count }}.
  </body>
</html>

You can now run your project by typing the following into the command line:

python manage.py runserver

To test your program, open up a web browser and go to http://127.0.0.1:8000. All going well, you should see the following message appear in your web browser:

Reloading the page will cause the number to increment each time.

Of course, this example project is rather basic—there are lots of details we have skipped over, and the resulting program doesn't look particularly good yet—but we have covered most of the key features of Django that you need to know about:

Now that we have seen how Django works, let's take a brief look at how GeoDjango extends the Django framework to allow you to create geospatial web applications.

The GeoDjango extension builds on Django's capabilities to add complete support for building geospatial web applications. In particular, it adds the following functionality to Django:

All told, the GeoDjango extension makes Django an excellent choice for developing geospatial web applications. In fact, ShapeEditor, the complete geospatial application we will be writing in the remainder of this book, will be built on top of the GeoDjango framework.