Ticket 18715: Revisions to page 3 of the Django tutorial #248

Closed
wants to merge 10 commits into
from

Conversation

Projects
None yet
7 participants
Contributor

pydanny commented Aug 5, 2012

  • Changing the order of instructions. Views and Urls are 'tightly coupled' in the code and should be so in the tutorial.
  • Views and Templates changed to be taught to work from the beginning rather than taught via throwing errors and then fixing them.
  • Good practices on URLconf are taught from the beginner per Jessica McKellar's keynote at DjangoCon US. For example, we begin with polls/urls.py in place rather than adding them at the end.
  • Editing provided by @dgouldin
  • Added template namespacing
  • Additional suggestions by @roguelynn, and @zedshaw
docs/intro/tutorial03.txt
-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.
+This is the simplest view possible in Django. Now we have a problem, how do we
@ptone

ptone Aug 5, 2012

Member

maybe "how does this view get called" as even in the urlconf - we don't actually call the view from our code anywhere.

@pydanny

pydanny Aug 7, 2012

Contributor

Cleaned up the text.

@jezdez

jezdez Aug 8, 2012

Owner

Double spaces?

docs/intro/tutorial03.txt
-that matches.
+This is the simplest view possible in Django. Now we have a problem, how do we
+call the view? For that we need to map it to a URL,
+in Django this is done in a confirguration file called a URLconf. In the polls
@ptone

ptone Aug 5, 2012

Member

I'm sure it is explained later, but at this point I'm left wondering (from a beginner's perspective) 'what is a URLconf. Maybe just a parenthetical (explained below - assuming it is)

@anthonydb

anthonydb Aug 5, 2012

I agree. One of the things that confused me while learning Django was repeated references to URLconf when what I really needed to locate was urls.py

@ptone

ptone Aug 5, 2012

Member

after reading this all the way through - I do think some very brief intro to the concept of URL routing is needed around here somewhere.

@pydanny

pydanny Aug 7, 2012

Contributor

Added a note on URLconfs that points to docs.

docs/intro/tutorial03.txt
-But, don't do that. It's silly.
+The term `regex` is a commonly used psuedonym for regular expressions, which is
@ptone

ptone Aug 5, 2012

Member

nit: s/psuedonym/short form meaning

@anthonydb

anthonydb Aug 5, 2012

I'll just point out that it's spelled "pseudonym".

@pydanny

pydanny Aug 7, 2012

Contributor

Changed to short form meaning

docs/intro/tutorial03.txt
- ViewDoesNotExist at /polls/
+When Django finds a regex match, Django calls the Python specified view
@ptone

ptone Aug 5, 2012

Member

When Django finds a regex that matches the URL of the current request, the specified view function is called.

"Python specified view" - not sure what that means here

@kezabelle

kezabelle Aug 5, 2012

Contributor

Everywhere else, regex is expanded to the long form. If, in this instance , it is an allusion to the kwarg, it might be prudent to mark it up, or denote it in some way.

@pydanny

pydanny Aug 7, 2012

Contributor

Corrected.

docs/intro/tutorial03.txt
- ViewDoesNotExist at /polls/
+When Django finds a regex match, Django calls the Python specified view
+function, with an HttpRequest object as the first argument, any “captured”
@ptone

ptone Aug 5, 2012

Member

no introduction to regex capturing as there was on the old version here: around https://github.com/django/django/pull/248/files#L0L105

@pydanny

pydanny Aug 7, 2012

Contributor

Thanks! New I had missed something! Added back in!

docs/intro/tutorial03.txt
-This error happened because you haven't written a function ``index()`` in the
-module ``polls/views.py``.
+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.
@ptone

ptone Aug 5, 2012

Member

If you aren't explaining it, or showing how to use it, then its just a distraction - and should be left out.

@pydanny

pydanny Aug 7, 2012

Contributor

I wanted to leave it out, but was instructed by higher powers that it had to remain. :P

docs/intro/tutorial03.txt
-Time to write the first view. Open the file ``polls/views.py``
-and put the following Python code in it::
+Naming URL patterns allows you to fully utilize a number of Django's reverse URL
@ptone

ptone Aug 5, 2012

Member

This is really tricky to introduce clearly here - not sure if I have an improvement - maybe something a bit handwavy like:

Naming your URL lets you refer to it unambiguously from elsewhere in Django especially templates

@pydanny

pydanny Aug 7, 2012

Contributor

Merged our text for the betterment of Djangosphere.

docs/intro/tutorial03.txt
@@ -180,6 +164,40 @@ captured by the regular expression in the URLconf)::
def vote(request, poll_id):
return HttpResponse("You're voting on poll %s." % poll_id)
+Wire these news views into the polls/urls.py module by adding the following
+``url`` calls as demonstrated below::
@ptone

ptone Aug 5, 2012

Member

nit: following calls to url() - as it reminds people that url is a function

docs/intro/tutorial03.txt
@@ -10,7 +10,7 @@ Philosophy
==========
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 Weblog
+a specific function and has a specific template. For example, in a Blog
@anthonydb

anthonydb Aug 5, 2012

I don't believe there's any stylistic reason to capitalize blog.

@pydanny

pydanny Aug 7, 2012

Contributor

relic of another time.

+ kwargs={},
+ name='vote')
+ )
+
@ptone

ptone Aug 5, 2012

Member

maybe useful for the regex lines to append a comment showing # ex: /polls/5/vote/

@pydanny

pydanny Aug 7, 2012

Contributor

Done.

@@ -205,45 +223,27 @@ in :doc:`Tutorial 1 </intro/tutorial01>`. Here's one stab at the ``index()``
view, which displays the latest 5 poll questions in the system, separated by
commas, according to publication date::
- from polls.models import Poll
+ from __future__ import absolute_import
@ptone

ptone Aug 5, 2012

Member

these future imports may need a "note" box?

@pydanny

pydanny Aug 7, 2012

Contributor

I'm want to focus on the Django. I think this should be something raised in an article outside the tutorial.

docs/intro/tutorial03.txt
@@ -264,11 +264,31 @@ Put the following code in that template:
<p>No polls are available.</p>
{% endif %}
+Now let's call that html template from the index view::
@ptone

ptone Aug 5, 2012

Member

Maybe I'm lost in the diff - but I don't think you said anything about creating the template file yet.

and you probably wouldn't say "call" the template, maybe just let's use that html template

@pydanny

pydanny Aug 7, 2012

Contributor

Fixed.

docs/intro/tutorial03.txt
+
+ def index(request):
+ latest_poll_list = Poll.objects.order_by('-pub_date')[:5]
+ t = loader.get_template('polls/index.html')
@ptone

ptone Aug 5, 2012

Member

generally not a fan of single letter variables - especially in a tutorial - a verbose variable name here will be more readable later

template_object
template_context

@pydanny

pydanny Aug 7, 2012

Contributor

Point taken! I was copying old code and adopted a pattern I can't stand myself. :P

docs/intro/tutorial03.txt
+The problem with this hardcoded, tightly-coupled approach is that it becomes
+challenging to change URLs on projects with a lot of templates. However, since
+you defined the name argument in the :func:`~django.conf.urls.url` functions in
+the ``polls/urls.py`` module, you can decouple the URLs via the ``{% url %}``
@ptone

ptone Aug 5, 2012

Member

"...you can remove a reliance on specific URL paths defined in your url configurations by using the {% url %} templatetag

@pydanny

pydanny Aug 7, 2012

Contributor

done.

docs/intro/tutorial03.txt
- from django.conf.urls import patterns, include, url
+The way this works is by calling the URL definition as specified in the
@ptone

ptone Aug 5, 2012

Member

"is by calling the URL definition"
maybe
"is by looking up the URL definition"

@pydanny

pydanny Aug 7, 2012

Contributor

Done.

docs/intro/tutorial03.txt
-app is specific to the app, not to the Django installation -- so let's move the
-URLs within the app directory.
+The tutorial project has just one app, ``polls``. In real Django projects, there
+might be five, ten, eighty apps or more. How does Django differentiate the URL
@ptone

ptone Aug 5, 2012

Member

maybe eighty is a little rare and scary for the tutorial ;-)

@pydanny

pydanny Aug 7, 2012

Contributor

And for me as well.

docs/intro/tutorial03.txt
-Copy the file ``mysite/urls.py`` to ``polls/urls.py``. Then, change
-``mysite/urls.py`` to remove the poll-specific URLs and insert an
-:func:`~django.conf.urls.include`, leaving you with::
+The answer to add namespaces to your root URLconf. In the mysite/urls.py file,
@ptone

ptone Aug 5, 2012

Member

missing is - the answer is to add

@pydanny

pydanny Aug 7, 2012

Contributor

Added

docs/intro/tutorial03.txt
+=================================================================
+
+You've probably noticed by now that ``mysite/urls.py`` calls both the polls app
+and the admin app. It's what is called the root URLconf, and is important when
@ptone

ptone Aug 5, 2012

Member

strike: "and is important when building Django projects."

what does that add?

docs/intro/tutorial03.txt
+and the admin app. It's what is called the root URLconf, and is important when
+building Django projects.
+
+The :func:`~django.conf.urls.include` functions we are using in the tutorial
@ptone

ptone Aug 5, 2012

Member

strike "in the tutorial"

@pydanny

pydanny Aug 7, 2012

Contributor

Struck.

docs/intro/tutorial03.txt
+challenging to change URLs on projects with a lot of templates. However, since
+you defined the name argument in the :func:`~django.conf.urls.url` functions in
+the ``polls/urls.py`` module, you can decouple the URLs via the ``{% url %}``
+templatetag:
@kezabelle

kezabelle Aug 5, 2012

Contributor

It's not in the Django specific terminology, but it seems to be used throughout the docs as two separate words.

@pydanny

pydanny Aug 7, 2012

Contributor

What is not in the terminology? Can you specify?

@kezabelle

kezabelle Aug 8, 2012

Contributor

templatetag - it's not explicitly referenced as how it's written, but across [most of] the rest of the documentation, it's two words.

(Specifically, according to the google queries site:docs.djangoproject.com "template tag" and site:docs.djangoproject.com "templatetag"its 204 uses to 9.)

@pydanny

pydanny Aug 8, 2012

Contributor

Fixed.

docs/intro/tutorial03.txt
-own URLconf, they can be placed under "/polls/", or under "/fun_polls/", or
-under "/content/polls/", or any other path root, and the app will still work.
+About the root URLconf
+=================================================================
@jezdez

jezdez Aug 8, 2012

Owner

you probably want this to be shorter

@@ -10,7 +10,7 @@ Philosophy
==========
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 Weblog
+a specific function and has a specific template. For example, in a blog
@jdunck

jdunck Aug 15, 2012

Member

Adrian will fight you on this if he notices. :P

@pydanny

pydanny Aug 16, 2012

Contributor

I'll make sure he notices. :-)

Owner

aaugustin commented Aug 17, 2012

I've reviewed this. It's not entirely RFC.

I've commented on the ticket and uploaded an updated patch there (I don't think I can update that PR).

@aaugustin aaugustin closed this Aug 17, 2012

sztrovacsek pushed a commit to sztrovacsek/django that referenced this pull request Mar 7, 2015

Merge pull request #248 from patrickbeeson/master
Update attendees with my name

nanuxbe pushed a commit to nanuxbe/django that referenced this pull request Jul 2, 2016

nanuxbe pushed a commit to nanuxbe/django that referenced this pull request Jul 2, 2016

Merge pull request #251 from evildmp/weblogheadings
Fixed #248 - weblog heading levels are now in sequence
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment