This tutorial begins where Tutorial 2 left off. We’re\ncontinuing the Web-poll application and will focus on creating the public\ninterface – “views.”
\nA view is a “type” of Web page in your Django application that generally serves\na specific function and has a specific template. For example, in a blog\napplication, you might have the following views:
\nBlog homepage – displays the latest few entries.
Entry “detail” page – permalink page for a single entry.
Year-based archive page – displays all months with entries in the\ngiven year.
Month-based archive page – displays all days with entries in the\ngiven month.
Day-based archive page – displays all entries in the given day.
Comment action – handles posting comments to a given entry.
In our poll application, we’ll have the following four views:
\nQuestion “index” page – displays the latest few questions.
Question “detail” page – displays a question text, with no results but\nwith a form to vote.
Question “results” page – displays results for a particular question.
Vote action – handles voting for a particular choice in a particular\nquestion.
In Django, web pages and other content are delivered by views. Each view is\nrepresented by a simple Python function (or method, in the case of class-based\nviews). Django will choose a view by examining the URL that’s requested (to be\nprecise, the part of the URL after the domain name).
\nNow in your time on the web you may have come across such beauties as\n“ME2/Sites/dirmod.asp?sid=&type=gen&mod=Core+Pages&gid=A6CD4967199A42D9B65B1B”.\nYou will be pleased to know that Django allows us much more elegant\nURL patterns than that.
\nA URL pattern is simply the general form of a URL - for example:\n/newsarchive/<year>/<month>/.
To get from a URL to a view, Django uses what are known as ‘URLconfs’. A\nURLconf maps URL patterns (described as regular expressions) to views.
\nThis tutorial provides basic instruction in the use of URLconfs, and you can\nrefer to django.core.urlresolvers for more information.
Let’s write the first view. Open the file polls/views.py\nand put the following Python code in it:
polls/views.pyfrom django.http import HttpResponse\n\n\ndef index(request):\n return HttpResponse("Hello, world. You're at the polls index.")\nThis is the simplest view possible in Django. To call the view, we need to map\nit to a URL - and for this we need a URLconf.
\nTo create a URLconf in the polls directory, create a file called urls.py.\nYour app directory should now look like:
polls/\n __init__.py\n admin.py\n models.py\n tests.py\n urls.py\n views.py\nIn the polls/urls.py file include the following code:
polls/urls.pyfrom django.conf.urls import url\n\nfrom . import views\n\nurlpatterns = [\n url(r'^$', views.index, name='index'),\n]\nThe next step is to point the root URLconf at the polls.urls module. In\nmysite/urls.py insert an include(), leaving you\nwith:
mysite/urls.pyfrom django.conf.urls import include, url\nfrom django.contrib import admin\n\nurlpatterns = [\n url(r'^polls/', include('polls.urls')),\n url(r'^admin/', include(admin.site.urls)),\n]\nYou have now wired an index view into the URLconf. Go to\nhttp://localhost:8000/polls/ in your browser, and you should see the text\n“Hello, world. You’re at the polls index.”, which you defined in the\nindex view.
The url() function is passed four arguments, two\nrequired: regex and view, and two optional: kwargs, and name.\nAt this point, it’s worth reviewing what these arguments are for.
url() argument: regexLink to this heading#The term “regex” is a commonly used short form meaning “regular expression”,\nwhich is a syntax for matching patterns in strings, or in this case, url\npatterns. Django starts at the first regular expression and makes its way down\nthe list, comparing the requested URL against each regular expression until it\nfinds one that matches.
\nNote that these regular expressions do not search GET and POST parameters, or\nthe domain name. For example, in a request to\nhttp://www.example.com/myapp/, the URLconf will look for myapp/. In a\nrequest to http://www.example.com/myapp/?page=3, the URLconf will also\nlook for myapp/.
If you need help with regular expressions, see Wikipedia’s entry and the\ndocumentation of the re module. Also, the O’Reilly book “Mastering\nRegular Expressions” by Jeffrey Friedl is fantastic. In practice, however,\nyou don’t need to be an expert on regular expressions, as you really only need\nto know how to capture simple patterns. In fact, complex regexes can have poor\nlookup performance, so you probably shouldn’t rely on the full power of regexes.
Finally, a performance note: these regular expressions are compiled the first\ntime the URLconf module is loaded. They’re super fast (as long as the lookups\naren’t too complex as noted above).
\nurl() argument: viewLink to this heading#When Django finds a regular expression match, Django calls the specified view\nfunction, with an HttpRequest object as the first\nargument and any “captured” values from the regular expression as other\narguments. If the regex uses simple captures, values are passed as positional\narguments; if it uses named captures, values are passed as keyword arguments.\nWe’ll give an example of this in a bit.
url() argument: kwargsLink to this heading#Arbitrary keyword arguments can be passed in a dictionary to the target view. We\naren’t going to use this feature of Django in the tutorial.
\nurl() argument: nameLink to this heading#Naming your URL lets you refer to it unambiguously from elsewhere in Django\nespecially templates. This powerful feature allows you to make global changes\nto the url patterns of your project while only touching a single file.
\nNow let’s add a few more views to polls/views.py. These views are\nslightly different, because they take an argument:
polls/views.pydef detail(request, question_id):\n return HttpResponse("You're looking at question %s." % question_id)\n\ndef results(request, question_id):\n response = "You're looking at the results of question %s."\n return HttpResponse(response % question_id)\n\ndef vote(request, question_id):\n return HttpResponse("You're voting on question %s." % question_id)\nWire these new views into the polls.urls module by adding the following\nurl() calls:
polls/urls.pyfrom django.conf.urls import url\n\nfrom . import views\n\nurlpatterns = [\n # ex: /polls/\n url(r'^$', views.index, name='index'),\n # ex: /polls/5/\n url(r'^(?P<question_id>[0-9]+)/$', views.detail, name='detail'),\n # ex: /polls/5/results/\n url(r'^(?P<question_id>[0-9]+)/results/$', views.results, name='results'),\n # ex: /polls/5/vote/\n url(r'^(?P<question_id>[0-9]+)/vote/$', views.vote, name='vote'),\n]\nTake a look in your browser, at “/polls/34/”. It’ll run the detail()\nmethod and display whatever ID you provide in the URL. Try\n“/polls/34/results/” and “/polls/34/vote/” too – these will display the\nplaceholder results and voting pages.
When somebody requests a page from your Web site – say, “/polls/34/”, Django\nwill load the mysite.urls Python module because it’s pointed to by the\nROOT_URLCONF setting. It finds the variable named urlpatterns\nand traverses the regular expressions in order. The\ninclude() functions we are using simply reference\nother URLconfs. Note that the regular expressions for the\ninclude() functions don’t have a $ (end-of-string\nmatch character) but rather a trailing slash. Whenever Django encounters\ninclude(), it chops off whatever part of the URL\nmatched up to that point and sends the remaining string to the included\nURLconf for further processing.
The idea behind include() is to make it easy to\nplug-and-play URLs. Since polls are in their own URLconf\n(polls/urls.py), they can be placed under “/polls/”, or under\n“/fun_polls/”, or under “/content/polls/”, or any other path root, and the\napp will still work.
Here’s what happens if a user goes to “/polls/34/” in this system:
\nDjango will find the match at '^polls/'
Then, Django will strip off the matching text ("polls/") and send the\nremaining text – "34/" – to the ‘polls.urls’ URLconf for\nfurther processing which matches r'^(?P<question_id>[0-9]+)/$' resulting in a\ncall to the detail() view like so:
detail(request=<HttpRequest object>, question_id='34')\nThe question_id='34' part comes from (?P<question_id>[0-9]+). Using parentheses\naround a pattern “captures” the text matched by that pattern and sends it as an\nargument to the view function; ?P<question_id> defines the name that will\nbe used to identify the matched pattern; and [0-9]+ is a regular expression to\nmatch a sequence of digits (i.e., a number).
Because the URL patterns are regular expressions, there really is no limit on\nwhat you can do with them. And there’s no need to add URL cruft such as\n.html – unless you want to, in which case you can do something like\nthis:
url(r'^polls/latest\\.html$', views.index),\nBut, don’t do that. It’s silly.
\nEach view is responsible for doing one of two things: returning an\nHttpResponse object containing the content for the\nrequested page, or raising an exception such as Http404. The\nrest is up to you.
Your view can read records from a database, or not. It can use a template\nsystem such as Django’s – or a third-party Python template system – or not.\nIt can generate a PDF file, output XML, create a ZIP file on the fly, anything\nyou want, using whatever Python libraries you want.
\nAll Django wants is that HttpResponse. Or an exception.
Because it’s convenient, let’s use Django’s own database API, which we covered\nin Tutorial 1. Here’s one stab at a new index()\nview, which displays the latest 5 poll questions in the system, separated by\ncommas, according to publication date:
polls/views.pyfrom django.http import HttpResponse\n\nfrom .models import Question\n\n\ndef index(request):\n latest_question_list = Question.objects.order_by('-pub_date')[:5]\n output = ', '.join([p.question_text for p in latest_question_list])\n return HttpResponse(output)\n\n# Leave the rest of the views (detail, results, vote) unchanged\nThere’s a problem here, though: the page’s design is hard-coded in the view. If\nyou want to change the way the page looks, you’ll have to edit this Python code.\nSo let’s use Django’s template system to separate the design from Python by\ncreating a template that the view can use.
\nFirst, create a directory called templates in your polls directory.\nDjango will look for templates in there.
Your project’s TEMPLATES setting describes how Django will load and\nrender templates. The default settings file configures a DjangoTemplates\nbackend whose APP_DIRS option is set to\nTrue. By convention DjangoTemplates looks for a “templates”\nsubdirectory in each of the INSTALLED_APPS. This is how Django\nknows to find the polls templates even though we didn’t modify the\nDIRS option, as we did in Tutorial 2.
Within the templates directory you have just created, create another\ndirectory called polls, and within that create a file called\nindex.html. In other words, your template should be at\npolls/templates/polls/index.html. Because of how the app_directories\ntemplate loader works as described above, you can refer to this template within\nDjango simply as polls/index.html.
Put the following code in that template:
\npolls/templates/polls/index.html{% if latest_question_list %}\n <ul>\n {% for question in latest_question_list %}\n <li><a href="/polls/{{ question.id }}/">{{ question.question_text }}</a></li>\n {% endfor %}\n </ul>\n{% else %}\n <p>No polls are available.</p>\n{% endif %}\nNow let’s update our index view in polls/views.py to use the template:
polls/views.pyfrom django.http import HttpResponse\nfrom django.template import loader\n\nfrom .models import Question\n\n\ndef index(request):\n latest_question_list = Question.objects.order_by('-pub_date')[:5]\n template = loader.get_template('polls/index.html')\n context = {\n 'latest_question_list': latest_question_list,\n }\n return HttpResponse(template.render(context, request))\nThat code loads the template called polls/index.html and passes it a\ncontext. The context is a dictionary mapping template variable names to Python\nobjects.
Load the page by pointing your browser at “/polls/”, and you should see a\nbulleted-list containing the “What’s up” question from Tutorial 1. The link points\nto the question’s detail page.
\nrender()Link to this heading#It’s a very common idiom to load a template, fill a context and return an\nHttpResponse object with the result of the rendered\ntemplate. Django provides a shortcut. Here’s the full index() view,\nrewritten:
polls/views.pyfrom django.shortcuts import render\n\nfrom .models import Question\n\n\ndef index(request):\n latest_question_list = Question.objects.order_by('-pub_date')[:5]\n context = {'latest_question_list': latest_question_list}\n return render(request, 'polls/index.html', context)\nNote that once we’ve done this in all these views, we no longer need to import\nloader and HttpResponse (you’ll\nwant to keep HttpResponse if you still have the stub methods for detail,\nresults, and vote).
The render() function takes the request object as its\nfirst argument, a template name as its second argument and a dictionary as its\noptional third argument. It returns an HttpResponse\nobject of the given template rendered with the given context.
Now, let’s tackle the question detail view – the page that displays the question text\nfor a given poll. Here’s the view:
\npolls/views.pyfrom django.http import Http404\nfrom django.shortcuts import render\n\nfrom .models import Question\n# ...\ndef detail(request, question_id):\n try:\n question = Question.objects.get(pk=question_id)\n except Question.DoesNotExist:\n raise Http404("Question does not exist")\n return render(request, 'polls/detail.html', {'question': question})\nThe new concept here: The view raises the Http404 exception\nif a question with the requested ID doesn’t exist.
We’ll discuss what you could put in that polls/detail.html template a bit\nlater, but if you’d like to quickly get the above example working, a file\ncontaining just:
polls/templates/polls/detail.html{{ question }}\nwill get you started for now.
\nget_object_or_404()Link to this heading#It’s a very common idiom to use get()\nand raise Http404 if the object doesn’t exist. Django\nprovides a shortcut. Here’s the detail() view, rewritten:
polls/views.pyfrom django.shortcuts import get_object_or_404, render\n\nfrom .models import Question\n# ...\ndef detail(request, question_id):\n question = get_object_or_404(Question, pk=question_id)\n return render(request, 'polls/detail.html', {'question': question})\nThe get_object_or_404() function takes a Django model\nas its first argument and an arbitrary number of keyword arguments, which it\npasses to the get() function of the\nmodel’s manager. It raises Http404 if the object doesn’t\nexist.
There’s also a get_list_or_404() function, which works\njust as get_object_or_404() – except using\nfilter() instead of\nget(). It raises\nHttp404 if the list is empty.
Back to the detail() view for our poll application. Given the context\nvariable question, here’s what the polls/detail.html template might look\nlike:
polls/templates/polls/detail.html<h1>{{ question.question_text }}</h1>\n<ul>\n{% for choice in question.choice_set.all %}\n <li>{{ choice.choice_text }}</li>\n{% endfor %}\n</ul>\nThe template system uses dot-lookup syntax to access variable attributes. In\nthe example of {{ question.question_text }}, first Django does a dictionary lookup\non the object question. Failing that, it tries an attribute lookup – which\nworks, in this case. If attribute lookup had failed, it would’ve tried a\nlist-index lookup.
Method-calling happens in the {% for %} loop:\nquestion.choice_set.all is interpreted as the Python code\nquestion.choice_set.all(), which returns an iterable of Choice objects and is\nsuitable for use in the {% for %} tag.
See the template guide for more about templates.
\nRemember, when we wrote the link to a question in the polls/index.html\ntemplate, the link was partially hardcoded like this:
<li><a href="/polls/{{ question.id }}/">{{ question.question_text }}</a></li>\nThe problem with this hardcoded, tightly-coupled approach is that it becomes\nchallenging to change URLs on projects with a lot of templates. However, since\nyou defined the name argument in the url() functions in\nthe polls.urls module, you can remove a reliance on specific URL paths\ndefined in your url configurations by using the {% url %} template tag:
<li><a href="{% url 'detail' question.id %}">{{ question.question_text }}</a></li>\nThe way this works is by looking up the URL definition as specified in the\npolls.urls module. You can see exactly where the URL name of ‘detail’ is\ndefined below:
...\n# the 'name' value as called by the {% url %} template tag\nurl(r'^(?P<question_id>[0-9]+)/$', views.detail, name='detail'),\n...\nIf you want to change the URL of the polls detail view to something else,\nperhaps to something like polls/specifics/12/ instead of doing it in the\ntemplate (or templates) you would change it in polls/urls.py:
...\n# added the word 'specifics'\nurl(r'^specifics/(?P<question_id>[0-9]+)/$', views.detail, name='detail'),\n...\nThe tutorial project has just one app, polls. In real Django projects,\nthere might be five, ten, twenty apps or more. How does Django differentiate\nthe URL names between them? For example, the polls app has a detail\nview, and so might an app on the same project that is for a blog. How does one\nmake it so that Django knows which app view to create for a url when using the\n{% url %} template tag?
The answer is to add namespaces to your root URLconf. In the mysite/urls.py\nfile, go ahead and change it to include namespacing:
mysite/urls.pyfrom django.conf.urls import include, url\nfrom django.contrib import admin\n\nurlpatterns = [\n url(r'^polls/', include('polls.urls', namespace="polls")),\n url(r'^admin/', include(admin.site.urls)),\n]\nNow change your polls/index.html template from:
polls/templates/polls/index.html<li><a href="{% url 'detail' question.id %}">{{ question.question_text }}</a></li>\nto point at the namespaced detail view:
\npolls/templates/polls/index.html<li><a href="{% url 'polls:detail' question.id %}">{{ question.question_text }}</a></li>\nWhen you’re comfortable with writing views, read part 4 of this tutorial to learn about simple form processing and generic views.
\n