Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Edited docs/url_dispatch.txt changes from [4901]

git-svn-id: http://code.djangoproject.com/svn/django/trunk@4966 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 421be9fb2a4dd1f13023adb33a79f1bdd595d9bc 1 parent a698afe
Adrian Holovaty authored

Showing 1 changed file with 36 additions and 20 deletions. Show diff stats Hide diff stats

  1. 56  docs/url_dispatch.txt
56  docs/url_dispatch.txt
@@ -192,10 +192,11 @@ The remaining arguments should be tuples in this format::
192 192
 
193 193
 url
194 194
 ---
195  
-**New in development version**
196 195
 
197  
-The ``url()`` function can be used instead of a tuple as an argument to
198  
-``patterns()``. This is convenient if you wish to specify a name without the
  196
+**New in Django development version**
  197
+
  198
+You can use the ``url()`` function, instead of a tuple, as an argument to
  199
+``patterns()``. This is convenient if you want to specify a name without the
199 200
 optional extra arguments dictionary. For example::
200 201
 
201 202
     urlpatterns = patterns('',
@@ -498,26 +499,40 @@ the view prefix (as explained in "The view prefix" above) will have no effect.
498 499
 Naming URL patterns
499 500
 ===================
500 501
 
501  
-**New in development version**
  502
+**New in Django development version**
  503
+
  504
+It's fairly common to use the same view function in multiple URL patterns in
  505
+your URLconf. For example, these two URL patterns both point to the ``archive``
  506
+view::
  507
+
  508
+    urlpatterns = patterns('',
  509
+        (r'/archive/(\d{4})/$', archive),
  510
+        (r'/archive-summary/(\d{4})/$', archive, {'summary': True}),
  511
+    )
  512
+
  513
+This is completely valid, but it leads to problems when you try to do reverse
  514
+URL matching (through the ``permalink()`` decorator or the ``{% url %}``
  515
+template tag). Continuing this example, if you wanted to retrieve the URL for
  516
+the ``archive`` view, Django's reverse URL matcher would get confused, because
  517
+*two* URLpatterns point at that view.
502 518
 
503  
-It is fairly common to use the same view function in multiple URL patterns in
504  
-your URLConf. This leads to problems when you come to do reverse URL matching,
505  
-because the ``permalink()`` decorator and ``{% url %}`` template tag use the
506  
-name of the view function to find a match.
  519
+To solve this problem, Django supports **named URL patterns**. That is, you can
  520
+give a name to a URL pattern in order to distinguish it from other patterns
  521
+using the same view and parameters. Then, you can use this name in reverse URL
  522
+matching.
507 523
 
508  
-To solve this problem, you can give a name to each of your URL patterns in
509  
-order to distinguish them from other patterns using the same views and
510  
-parameters. You can then use this name wherever you would otherwise use the
511  
-name of the view function. For example, if you URLConf contains::
  524
+Here's the above example, rewritten to used named URL patterns::
512 525
 
513 526
     urlpatterns = patterns('',
514 527
         url(r'/archive/(\d{4})/$', archive, name="full-archive"),
515 528
         url(r'/archive-summary/(\d{4})/$', archive, {'summary': True}, "arch-summary"),
516 529
     )
517 530
 
518  
-...you could refer to either the summary archive view in a template as::
  531
+With these names in place (``full-archive`` and ``arch-summary``), you can
  532
+target each pattern individually by using its name::
519 533
 
520 534
     {% url arch-summary 1945 %}
  535
+    {% url full-archive 2007 %}
521 536
 
522 537
 Even though both URL patterns refer to the ``archive`` view here, using the
523 538
 ``name`` parameter to ``url()`` allows you to tell them apart in templates.
@@ -527,11 +542,12 @@ not restricted to valid Python names.
527 542
 
528 543
 .. note::
529 544
 
530  
-    Make sure that when you name your URLs, you use names that are unlikely to
531  
-    clash with any other application's choice of names. If you call your URL
532  
-    pattern *comment* and another application does the same thing, there is no
533  
-    guarantee which URL will be inserted into your template when you use this
534  
-    name. Putting a prefix on your URL names, perhaps derived from
535  
-    the application name, will decrease the chances of collision. Something
536  
-    like *myapp-comment* is recommended over simply *comment*.
  545
+    When you name your URL patterns, make sure you use names that are unlikely
  546
+    to clash with any other application's choice of names. If you call your URL
  547
+    pattern ``comment``, and another application does the same thing, there's
  548
+    no guarantee which URL will be inserted into your template when you use
  549
+    this name.
537 550
 
  551
+    Putting a prefix on your URL names, perhaps derived from the application
  552
+    name, will decrease the chances of collision. We recommend something like
  553
+    ``myapp-comment`` instead of ``comment``.

0 notes on commit 421be9f

Please sign in to comment.
Something went wrong with that request. Please try again.