diff options
Diffstat (limited to 'docs/intro/tutorial03.txt')
| -rw-r--r-- | docs/intro/tutorial03.txt | 149 |
1 files changed, 6 insertions, 143 deletions
diff --git a/docs/intro/tutorial03.txt b/docs/intro/tutorial03.txt index cf0d4dedf5..5b6c3e5ce7 100644 --- a/docs/intro/tutorial03.txt +++ b/docs/intro/tutorial03.txt @@ -6,8 +6,8 @@ This tutorial begins where :doc:`Tutorial 2 </intro/tutorial02>` left off. We're continuing the Web-poll application and will focus on creating the public interface -- "views." -Philosophy -========== +Overview +======== A view is a "type" of Web page in your Django application that generally serves a specific function and has a specific template. For example, in a blog @@ -58,130 +58,6 @@ URLconf maps URL patterns (described as regular expressions) to views. This tutorial provides basic instruction in the use of URLconfs, and you can refer to :mod:`django.core.urlresolvers` for more information. -Write your first view -===================== - -Let's write the first view. Open the file ``polls/views.py`` -and put the following Python code in it: - -.. snippet:: - :filename: polls/views.py - - from django.http import HttpResponse - - - def index(request): - return HttpResponse("Hello, world. You're at the polls index.") - -This is the simplest view possible in Django. To call the view, we need to map -it to a URL - and for this we need a URLconf. - -To create a URLconf in the polls directory, create a file called ``urls.py``. -Your app directory should now look like:: - - polls/ - __init__.py - admin.py - models.py - tests.py - urls.py - views.py - -In the ``polls/urls.py`` file include the following code: - -.. snippet:: - :filename: polls/urls.py - - from django.conf.urls import url - - from . import views - - urlpatterns = [ - url(r'^$', views.index, name='index'), - ] - -The next step is to point the root URLconf at the ``polls.urls`` module. In -``mysite/urls.py`` insert an :func:`~django.conf.urls.include`, leaving you -with: - -.. snippet:: - :filename: mysite/urls.py - - from django.conf.urls import include, url - from django.contrib import admin - - urlpatterns = [ - url(r'^polls/', include('polls.urls')), - url(r'^admin/', include(admin.site.urls)), - ] - -.. admonition:: Doesn't match what you see? - - If you're seeing ``admin.autodiscover()`` before the definition of - ``urlpatterns``, you're probably using a version of Django that doesn't - match this tutorial version. You'll want to either switch to the older - tutorial or the newer Django version. - -You have now wired an ``index`` view into the URLconf. Go to -http://localhost:8000/polls/ in your browser, and you should see the text -"*Hello, world. You're at the polls index.*", which you defined in the -``index`` view. - -The :func:`~django.conf.urls.url` function is passed four arguments, two -required: ``regex`` and ``view``, and two optional: ``kwargs``, and ``name``. -At this point, it's worth reviewing what these arguments are for. - -:func:`~django.conf.urls.url` argument: regex ---------------------------------------------- - -The term "regex" is a commonly used short form meaning "regular expression", -which is a syntax for matching patterns in strings, or in this case, url -patterns. Django starts at the first regular expression and makes its way down -the list, comparing the requested URL against each regular expression until it -finds one that matches. - -Note that these regular expressions do not search GET and POST parameters, or -the domain name. For example, in a request to -``http://www.example.com/myapp/``, the URLconf will look for ``myapp/``. In a -request to ``http://www.example.com/myapp/?page=3``, the URLconf will also -look for ``myapp/``. - -If you need help with regular expressions, see `Wikipedia's entry`_ and the -documentation of the :mod:`re` module. Also, the O'Reilly book "Mastering -Regular Expressions" by Jeffrey Friedl is fantastic. In practice, however, -you don't need to be an expert on regular expressions, as you really only need -to know how to capture simple patterns. In fact, complex regexes can have poor -lookup performance, so you probably shouldn't rely on the full power of regexes. - -Finally, a performance note: these regular expressions are compiled the first -time the URLconf module is loaded. They're super fast (as long as the lookups -aren't too complex as noted above). - -.. _Wikipedia's entry: http://en.wikipedia.org/wiki/Regular_expression - -:func:`~django.conf.urls.url` argument: view --------------------------------------------- - -When Django finds a regular expression match, Django calls the specified view -function, with an :class:`~django.http.HttpRequest` object as the first -argument and any “captured” values from the regular expression as other -arguments. If the regex uses simple captures, values are passed as positional -arguments; if it uses named captures, values are passed as keyword arguments. -We'll give an example of this in a bit. - -:func:`~django.conf.urls.url` argument: kwargs ----------------------------------------------- - -Arbitrary keyword arguments can be passed in a dictionary to the target view. We -aren't going to use this feature of Django in the tutorial. - -:func:`~django.conf.urls.url` argument: name ---------------------------------------------- - -Naming your URL lets you refer to it unambiguously from elsewhere in Django -especially templates. This powerful feature allows you to make global changes -to the url patterns of your project while only touching a single file. - Writing more views ================== @@ -287,7 +163,7 @@ you want, using whatever Python libraries you want. All Django wants is that :class:`~django.http.HttpResponse`. Or an exception. Because it's convenient, let's use Django's own database API, which we covered -in :doc:`Tutorial 1 </intro/tutorial01>`. Here's one stab at a new ``index()`` +in :doc:`Tutorial 2 </intro/tutorial02>`. Here's one stab at a new ``index()`` view, which displays the latest 5 poll questions in the system, separated by commas, according to publication date: @@ -318,20 +194,7 @@ Your project's :setting:`TEMPLATES` setting describes how Django will load and render templates. The default settings file configures a ``DjangoTemplates`` backend whose :setting:`APP_DIRS <TEMPLATES-APP_DIRS>` option is set to ``True``. By convention ``DjangoTemplates`` looks for a "templates" -subdirectory in each of the :setting:`INSTALLED_APPS`. This is how Django -knows to find the polls templates even though we didn't modify the -:setting:`DIRS <TEMPLATES-DIRS>` option, as we did in :ref:`Tutorial 2 -<ref-customizing-your-projects-templates>`. - -.. admonition:: Organizing templates - - We *could* have all our templates together, in one big templates directory, - and it would work perfectly well. However, this template belongs to the - polls application, so unlike the admin template we created in the previous - tutorial, we'll put this one in the application's template directory - (``polls/templates``) rather than the project's (``templates``). We'll - discuss in more detail in the :doc:`reusable apps tutorial - </intro/reusable-apps>` *why* we do this. +subdirectory in each of the :setting:`INSTALLED_APPS`. Within the ``templates`` directory you have just created, create another directory called ``polls``, and within that create a file called @@ -390,8 +253,8 @@ context. The context is a dictionary mapping template variable names to Python objects. Load the page by pointing your browser at "/polls/", and you should see a -bulleted-list containing the "What's up" question from Tutorial 1. The link points -to the question's detail page. +bulleted-list containing the "What's up" question from :doc:`Tutorial 2 +</intro/tutorial02>`. The link points to the question's detail page. A shortcut: :func:`~django.shortcuts.render` -------------------------------------------- |