← Back to branch summary

~ubuntu-branches/ubuntu/quantal/python-django/quantal

« back to all changes in this revision

Viewing changes to docs/intro/tutorial03.txt

  • Committer: Bazaar Package Importer
  • Author(s): Chris Lamb
  • Date: 2009-07-29 11:26:28 UTC
  • mfrom: (1.1.8 upstream) (4.1.5 sid)
  • Revision ID: james.westby@ubuntu.com-20090729112628-pg09ino8sz0sj21t
Tags: 1.1-1
http://bugs.debian.org/538863
* New upstream release.
* Merge from experimental:
  - Ship FastCGI initscript and /etc/default file in python-django's examples
    directory (Closes: #538863)
  - Drop "05_10539-sphinx06-compatibility.diff"; it has been applied
    upstream.
  - Bump Standards-Version to 3.8.2.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/intro/tutorial03.txt
16
16
application, you might have the following views:
17
17
 
18
18
    * Blog homepage -- displays the latest few entries.
19
 
    
 
19
 
20
20
    * Entry "detail" page -- permalink page for a single entry.
21
 
    
 
21
 
22
22
    * Year-based archive page -- displays all months with entries in the
23
23
      given year.
24
 
      
 
24
 
25
25
    * Month-based archive page -- displays all days with entries in the
26
26
      given month.
27
 
      
 
27
 
28
28
    * Day-based archive page -- displays all entries in the given day.
29
 
    
 
29
 
30
30
    * Comment action -- handles posting comments to a given entry.
31
31
 
32
32
In our poll application, we'll have the following four views:
33
33
 
34
34
    * Poll "archive" page -- displays the latest few polls.
35
 
    
 
35
 
36
36
    * Poll "detail" page -- displays a poll question, with no results but
37
37
      with a form to vote.
38
 
    
 
38
 
39
39
    * Poll "results" page -- displays results for a particular poll.
40
 
    
 
40
 
41
41
    * Vote action -- handles voting for a particular choice in a particular
42
42
      poll.
43
43
 
71
71
:ref:`ref-request-response`. For more details on URLconfs, see the
72
72
:ref:`topics-http-urls`.
73
73
 
74
 
When you ran ``python django-admin.py startproject mysite`` at the beginning of
 
74
When you ran ``django-admin.py startproject mysite`` at the beginning of
75
75
Tutorial 1, it created a default URLconf in ``mysite/urls.py``. It also
76
76
automatically set your :setting:`ROOT_URLCONF` setting (in ``settings.py``) to
77
77
point at that file::
82
82
 
83
83
    from django.conf.urls.defaults import *
84
84
 
 
85
    from django.contrib import admin
 
86
    admin.autodiscover()
 
87
 
85
88
    urlpatterns = patterns('',
86
89
        (r'^polls/$', 'mysite.polls.views.index'),
87
90
        (r'^polls/(?P<poll_id>\d+)/$', 'mysite.polls.views.detail'),
88
91
        (r'^polls/(?P<poll_id>\d+)/results/$', 'mysite.polls.views.results'),
89
92
        (r'^polls/(?P<poll_id>\d+)/vote/$', 'mysite.polls.views.vote'),
 
93
        (r'^admin/', include(admin.site.urls)),
90
94
    )
91
95
 
92
96
This is worth a review. When somebody requests a page from your Web site -- say,
94
98
the :setting:`ROOT_URLCONF` setting. It finds the variable named ``urlpatterns``
95
99
and traverses the regular expressions in order. When it finds a regular
96
100
expression that matches -- ``r'^polls/(?P<poll_id>\d+)/$'`` -- it loads the
97
 
associated Python package/module: ``mysite.polls.views.detail``. That
98
 
corresponds to the function ``detail()`` in ``mysite/polls/views.py``. Finally,
 
101
function ``detail()`` from ``mysite/polls/views.py``. Finally,
99
102
it calls that ``detail()`` function like so::
100
103
 
101
104
    detail(request=<HttpRequest object>, poll_id='23')
117
120
 
118
121
Note that these regular expressions do not search GET and POST parameters, or
119
122
the domain name. For example, in a request to ``http://www.example.com/myapp/``,
120
 
the URLconf will look for ``/myapp/``. In a request to
121
 
``http://www.example.com/myapp/?page=3``, the URLconf will look for ``/myapp/``.
 
123
the URLconf will look for ``myapp/``. In a request to
 
124
``http://www.example.com/myapp/?page=3``, the URLconf will look for ``myapp/``.
122
125
 
123
126
If you need help with regular expressions, see `Wikipedia's entry`_ and the
124
127
`Python documentation`_. Also, the O'Reilly book "Mastering Regular Expressions"
302
305
The new concept here: The view raises the :exc:`~django.http.Http404` exception
303
306
if a poll with the requested ID doesn't exist.
304
307
 
 
308
We'll discuss what you could put in that ``polls/detail.html`` template a bit
 
309
later, but if you'd like to quickly get the above example working, just::
 
310
 
 
311
    {{ poll }}
 
312
 
 
313
will get you started for now.
 
314
 
305
315
A shortcut: get_object_or_404()
306
316
-------------------------------
307
317
 
316
326
        return render_to_response('polls/detail.html', {'poll': p})
317
327
 
318
328
The :func:`~django.shortcuts.get_object_or_404` function takes a Django model
319
 
module as its first argument and an arbitrary number of keyword arguments, which
320
 
it passes to the module's :meth:`~django.db.models.QuerySet.get` function. It
 
329
as its first argument and an arbitrary number of keyword arguments, which it
 
330
passes to the module's :meth:`~django.db.models.QuerySet.get` function. It
321
331
raises :exc:`~django.http.Http404` if the object doesn't exist.
322
332
 
323
333
.. admonition:: Philosophy
355
365
in ``django/conf/urls/defaults.py``, ``handler404`` is set to
356
366
:func:`django.views.defaults.page_not_found` by default.
357
367
 
358
 
Three more things to note about 404 views:
 
368
Four more things to note about 404 views:
 
369
 
 
370
    * If :setting:`DEBUG` is set to ``True`` (in your settings module) then your
 
371
      404 view will never be used (and thus the ``404.html`` template will never
 
372
      be rendered) because the traceback will be displayed instead.
359
373
 
360
374
    * The 404 view is also called if Django doesn't find a match after checking
361
375
      every regular expression in the URLconf.
362
 
      
 
376
 
363
377
    * If you don't define your own 404 view -- and simply use the default, which
364
378
      is recommended -- you still have one obligation: To create a ``404.html``
365
379
      template in the root of your template directory. The default 404 view will
366
380
      use that template for all 404 errors.
367
 
      
368
 
    * If :setting:`DEBUG` is set to ``True`` (in your settings module) then your
369
 
      404 view will never be used, and the traceback will be displayed instead.
 
381
 
 
382
    * If :setting:`DEBUG` is set to ``False`` (in your settings module) and if
 
383
      you didn't create a ``404.html`` file, an ``Http500`` is raised instead.
 
384
      So remember to create a ``404.html``.
370
385
 
371
386
Write a 500 (server error) view
372
387
===============================
452
467
``mysite/urls.py`` to remove the poll-specific URLs and insert an
453
468
:func:`~django.conf.urls.defaults.include`::
454
469
 
455
 
    (r'^polls/', include('mysite.polls.urls')),
 
470
    ...
 
471
    urlpatterns = patterns('',
 
472
        (r'^polls/', include('mysite.polls.urls')),
 
473
        ...
456
474
 
457
475
:func:`~django.conf.urls.defaults.include`, simply, references another URLconf.
458
476
Note that the regular expression doesn't have a ``$`` (end-of-string match
470
488
      further processing.
471
489
 
472
490
Now that we've decoupled that, we need to decouple the 'mysite.polls.urls'
473
 
URLconf by removing the leading "polls/" from each line::
 
491
URLconf by removing the leading "polls/" from each line, and removing the
 
492
lines registering the admin site::
474
493
 
475
494
    urlpatterns = patterns('mysite.polls.views',
476
495
        (r'^$', 'index'),