Django

Code

Changeset 4966

Show
Ignore:
Timestamp:
04/08/07 21:07:04 (1 year ago)
Author:
adrian
Message:

Edited docs/url_dispatch.txt changes from [4901]

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • django/trunk/docs/url_dispatch.txt

    r4903 r4966  
    193193url 
    194194--- 
    195 **New in development version** 
    196  
    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 
     195 
     196**New in Django development version** 
     197 
     198You 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 
    199200optional extra arguments dictionary. For example:: 
    200201 
    …… 
    499500=================== 
    500501 
    501 **New in development version** 
    502  
    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. 
    507  
    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:: 
     502**New in Django development version** 
     503 
     504It's fairly common to use the same view function in multiple URL patterns in 
     505your URLconf. For example, these two URL patterns both point to the ``archive`` 
     506view:: 
     507 
     508    urlpatterns = patterns('', 
     509        (r'/archive/(\d{4})/$', archive), 
     510        (r'/archive-summary/(\d{4})/$', archive, {'summary': True}), 
     511    ) 
     512 
     513This is completely valid, but it leads to problems when you try to do reverse 
     514URL matching (through the ``permalink()`` decorator or the ``{% url %}`` 
     515template tag). Continuing this example, if you wanted to retrieve the URL for 
     516the ``archive`` view, Django's reverse URL matcher would get confused, because 
     517*two* URLpatterns point at that view. 
     518 
     519To solve this problem, Django supports **named URL patterns**. That is, you can 
     520give a name to a URL pattern in order to distinguish it from other patterns 
     521using the same view and parameters. Then, you can use this name in reverse URL 
     522matching. 
     523 
     524Here's the above example, rewritten to used named URL patterns:: 
    512525 
    513526    urlpatterns = patterns('', 
    …… 
    516529    ) 
    517530 
    518 ...you could refer to either the summary archive view in a template as:: 
     531With these names in place (``full-archive`` and ``arch-summary``), you can 
     532target each pattern individually by using its name:: 
    519533 
    520534    {% url arch-summary 1945 %} 
     535    {% url full-archive 2007 %} 
    521536 
    522537Even though both URL patterns refer to the ``archive`` view here, using the 
    …… 
    528543.. note:: 
    529544 
    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*. 
    537  
     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. 
     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``.