Learn Django

Understanding the URL Dispatcher

Now it's time for an introduction to Django's URL functionality. As a web user, you know that when you open your browser, type in a URL and press enter, a web page appears on your screen. URLs are entry points to web applications. In effect, URLs are a key user experience element. Designing URLs and what they do is an important part to web application design.

If a user accesses the www.example.com/contact-us/ URL, it's a good idea to show a "contact us" form. URLs should make sense to your users so it's easier for them to remember what they do, or remind them where they are on your site. Luckily Django comes with a URL dispatcher that allows you to create clean and elegant schemes.

What follows is an explanation of the basics of Django's URL dispatcher. You can also refer to the Django project's URL dispatcher page for more information.

The URL Configuration File

URL patterns are defined in the project urls.py file, or are imported into that file using a special statement. This file is created when the django-admin.py startproject command is executed. The default contents of this file are as follows.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
from django.conf.urls import patterns, include, url

# Uncomment the next two lines to enable the admin:
# from django.contrib import admin
# admin.autodiscover()

urlpatterns = patterns('',
    # Examples:
    # url(r'^$', 'crmapp.views.home', name='home'),
    # url(r'^crmapp/', include('crmapp.foo.urls')),

    # Uncomment the admin/doc line below to enable admin documentation:
    # url(r'^admin/doc/', include('django.contrib.admindocs.urls')),

    # Uncomment the next line to enable the admin:
    # url(r'^admin/', include(admin.site.urls)),
)

Defining URL Patterns

A URL patter has at least two parts. It first defines the actual URL to be used is e.g. /contact-us/. It then points to a view that is to be executed when the URL is accessed. The following URL pattern specifies that when /contact-us/ is accessed, the ContactUs view function is passed the request.

1
2
3
4
5
6
from django.conf.urls import patterns, include, url
from example.views import ContactUs

urlpatterns = patterns('',
    url(r'^contact-us/$', ContactUs.as_view()),
)

Passing Values to Views

The URL system is much more powerful than simply calling views. It also allows you to capture values from the URL and pass it into the view.

Here's an example of how to capture values from the URL. Let's say for example we wanted to allow the URL to define what language to display the page in. If a user accesses /contact-us/en/, the page will display in English. If /contact-us/cn/ is accessed, the page will render Mandarin. Therefore we want our URL pattern to capture the second segment of the URL and pass it to the view for analysis. Here's what the configuration would look like.

1
2
3
4
5
6
from django.conf.urls import patterns, include, url
from example.views import ContactUs

urlpatterns = patterns('',
    url(r'^contact-us/(?P<lang>[\w-]+)/$', ContactUs.as_view()),
)

Looking at line 5, the (?P<lang>[\w-]+) segment will capture whatever text value is there and pass it to the view as an object named lang.

That concludes the short intro to Django's awesome URL dispatcher. Now onto the fun part - creating the URL configuration for the home page.

Track your progress with a free account