From 0638ba5bba14a0051aa7390b6f595907957c0e12 Mon Sep 17 00:00:00 2001
From: Ramiro Morales <cramm0@gmail.com>
Date: Sun, 5 Jun 2011 23:44:34 +0000
Subject: [PATCH] Enhanced a bit the documentation and docstring for the url
 template tag. Also, added a test for it.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16331 bcc190cf-cafb-0310-a4f2-bffc1f526a37
---
 django/templatetags/future.py            | 36 +++++++++++++++++++++---
 docs/ref/templates/builtins.txt          | 12 ++++++++
 tests/regressiontests/templates/tests.py |  3 +-
 3 files changed, 46 insertions(+), 5 deletions(-)

diff --git a/django/templatetags/future.py b/django/templatetags/future.py
index cd29dc276a..3d9887939d 100644
--- a/django/templatetags/future.py
+++ b/django/templatetags/future.py
@@ -50,11 +50,15 @@ def url(parser, token):
 
         {% url "path.to.some_view" name1=value1 name2=value2 %}
 
-    The first argument is a path to a view. It can be an absolute python path
+    The first argument is a path to a view. It can be an absolute Python path
     or just ``app_name.view_name`` without the project name if the view is
-    located inside the project.  Other arguments are comma-separated values
-    that will be filled in place of positional and keyword arguments in the
-    URL. All arguments for the URL should be present.
+    located inside the project.
+
+    Other arguments are space-separated values that will be filled in place of
+    positional and keyword arguments in the URL. Don't mix positional and
+    keyword arguments.
+
+    All arguments for the URL should be present.
 
     For example if you have a view ``app_name.client`` taking client's id and
     the corresponding line in a URLconf looks like this::
@@ -71,6 +75,30 @@ def url(parser, token):
         {% url "app_name.client" client.id %}
 
     The URL will look like ``/clients/client/123/``.
+
+    The first argument can also be a named URL instead of the Python path to
+    the view callable. For example if the URLconf entry looks like this::
+
+        url('^client/(\d+)/$', name='client-detail-view')
+
+    then in the template you can use::
+
+        {% url "client-detail-view" client.id %}
+
+    There is even another possible value type for the first argument. It can be
+    the name of a template variable that will be evaluated to obtain the view
+    name or the URL name, e.g.::
+
+        {% with view_path="app_name.client" %}
+        {% url view_path client.id %}
+        {% endwith %}
+
+        or,
+
+        {% with url_name="client-detail-view" %}
+        {% url url_name client.id %}
+        {% endwith %}
+
     """
     bits = token.split_contents()
     if len(bits) < 2:
diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index b70205952a..76db1f7659 100644
--- a/docs/ref/templates/builtins.txt
+++ b/docs/ref/templates/builtins.txt
@@ -1073,8 +1073,20 @@ projects?
     For example::
 
         {% load url from future %}
+
+
+        {% url 'app_views.client' %}
+
         {% url 'myapp:view-name' %}
 
+        {% with view_path="app_views.client" %}
+        {% url view_path client.id %}
+        {% endwith %}
+
+        {% with url_name="client-detail-view" %}
+        {% url url_name client.id %}
+        {% endwith %}
+
     The new library also drops support for the comma syntax for
     separating arguments to the :ttag:`url` template tag.
 
diff --git a/tests/regressiontests/templates/tests.py b/tests/regressiontests/templates/tests.py
index f096042af0..1f065f9eb7 100644
--- a/tests/regressiontests/templates/tests.py
+++ b/tests/regressiontests/templates/tests.py
@@ -1460,7 +1460,7 @@ class Templates(unittest.TestCase):
             'old-url13': ('{% url regressiontests.templates.views.client_action id=client.id action=arg|join:"-" %}', {'client': {'id': 1}, 'arg':['a','b']}, '/url_tag/client/1/a-b/'),
             'old-url14': ('{% url regressiontests.templates.views.client_action client.id arg|join:"-" %}', {'client': {'id': 1}, 'arg':['a','b']}, '/url_tag/client/1/a-b/'),
             'old-url15': ('{% url regressiontests.templates.views.client_action 12 "test" %}', {}, '/url_tag/client/12/test/'),
-            'old-url18': ('{% url regressiontests.templates.views.client "1,2" %}', {}, '/url_tag/client/1,2/'),
+            'old-url16': ('{% url regressiontests.templates.views.client "1,2" %}', {}, '/url_tag/client/1,2/'),
 
             # Failures
             'old-url-fail01': ('{% url %}', {}, template.TemplateSyntaxError),
@@ -1501,6 +1501,7 @@ class Templates(unittest.TestCase):
             'url18': ('{% load url from future %}{% url "regressiontests.templates.views.client" "1,2" %}', {}, '/url_tag/client/1,2/'),
 
             'url19': ('{% load url from future %}{% url named_url client.id %}', {'named_url': 'regressiontests.templates.views.client', 'client': {'id': 1}}, '/url_tag/client/1/'),
+            'url20': ('{% load url from future %}{% url url_name_in_var client.id %}', {'url_name_in_var': 'named.client', 'client': {'id': 1}}, '/url_tag/named-client/1/'),
 
             # Failures
             'url-fail01': ('{% load url from future %}{% url %}', {}, template.TemplateSyntaxError),