From 4445d36d471aae81086ed785536687a92e5aaa6d Mon Sep 17 00:00:00 2001 From: Tim Graham Date: Tue, 3 Jun 2014 07:30:14 -0400 Subject: Fixed #22384 -- Deprecated reversing URLs by dotted path. --- docs/topics/http/urls.txt | 76 ++++++++++------------------------------------- 1 file changed, 15 insertions(+), 61 deletions(-) (limited to 'docs/topics/http') diff --git a/docs/topics/http/urls.txt b/docs/topics/http/urls.txt index 3833021956..39c96b2e02 100644 --- a/docs/topics/http/urls.txt +++ b/docs/topics/http/urls.txt @@ -555,7 +555,7 @@ Consider again this URLconf entry:: urlpatterns = [ #... - url(r'^articles/([0-9]{4})/$', 'news.views.year_archive'), + url(r'^articles/([0-9]{4})/$', 'news.views.year_archive', name='news-year-archive'), #... ] @@ -566,11 +566,11 @@ You can obtain these in template code by using: .. code-block:: html+django - 2012 Archive + 2012 Archive {# Or with the year in a template context variable: #} @@ -583,7 +583,7 @@ Or in Python code:: # ... year = 2006 # ... - return HttpResponseRedirect(reverse('news.views.year_archive', args=(year,))) + return HttpResponseRedirect(reverse('news-year-archive', args=(year,))) If, for some reason, it was decided that the URLs where content for yearly article archives are published at should be changed then you would only need to @@ -599,65 +599,19 @@ URLs. Read the next section to know about the solution Django provides for this. Naming URL patterns =================== -It's fairly common to use the same view function in multiple URL patterns in -your URLconf. For example, these two URL patterns both point to the ``archive`` -view:: - - from django.conf.urls import url - from mysite.views import archive - - urlpatterns = [ - url(r'^archive/([0-9]{4})/$', archive), - url(r'^archive-summary/([0-9]{4})/$', archive, {'summary': True}), - ] - -This is completely valid, but it leads to problems when you try to do reverse -URL matching (through the :func:`~django.core.urlresolvers.reverse` function -or the :ttag:`url` template tag). Continuing this example, if you wanted to -retrieve the URL for the ``archive`` view, Django's reverse URL matcher would -get confused, because *two* URL patterns point at that view. - -To solve this problem, Django supports **named URL patterns**. That is, you can -give a name to a URL pattern in order to distinguish it from other patterns -using the same view and parameters. Then, you can use this name in reverse URL -matching. - -Here's the above example, rewritten to use named URL patterns:: - - from django.conf.urls import url - from mysite.views import archive - - urlpatterns = [ - url(r'^archive/([0-9]{4})/$', archive, name="full-archive"), - url(r'^archive-summary/([0-9]{4})/$', archive, {'summary': True}, name="arch-summary"), - ] - -With these names in place (``full-archive`` and ``arch-summary``), you can -target each pattern individually by using its name: - -.. code-block:: html+django - - {% url 'arch-summary' 1945 %} - {% url 'full-archive' 2007 %} - -Even though both URL patterns refer to the ``archive`` view here, using the -``name`` parameter to :func:`django.conf.urls.url` allows you to tell them -apart in templates. - -The string used for the URL name can contain any characters you like. You are -not restricted to valid Python names. - -.. note:: +In order to perform URL reversing, you'll need to use **named URL patterns** +as done in the examples above. The string used for the URL name can contain any +characters you like. You are not restricted to valid Python names. - When you name your URL patterns, make sure you use names that are unlikely - to clash with any other application's choice of names. If you call your URL - pattern ``comment``, and another application does the same thing, there's - no guarantee which URL will be inserted into your template when you use - this name. +When you name your URL patterns, make sure you use names that are unlikely +to clash with any other application's choice of names. If you call your URL +pattern ``comment``, and another application does the same thing, there's +no guarantee which URL will be inserted into your template when you use +this name. - Putting a prefix on your URL names, perhaps derived from the application - name, will decrease the chances of collision. We recommend something like - ``myapp-comment`` instead of ``comment``. +Putting a prefix on your URL names, perhaps derived from the application +name, will decrease the chances of collision. We recommend something like +``myapp-comment`` instead of ``comment``. .. _topics-http-defining-url-namespaces: -- cgit v1.3