Fixed #14389, #9666 -- Started the migration path to make the first argument to url and ssi template tags syntactically consistent with other tags. Thanks to Sean Brant for the draft patch.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14643 bcc190cf-cafb-0310-a4f2-bffc1f526a37

3 files changed, 109 insertions, 1 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 1065f8e97d..1f5758c877 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -131,6 +131,11 @@ their deprecation, as per the :ref:`Django deprecation policy
           been deprecated in favor of the
           :class:`~django.contrib.staticfiles.handlers.StaticFilesHandler`.
 
+        * The :ttag:`url` and :ttag:`ssi` template tags will be
+          modified so that the first argument to each tag is a
+          template variable, not an implied string. The new-style
+          behavior is provided in the ``future`` template tag library.
+
     * 2.0
         * ``django.views.defaults.shortcut()``. This function has been moved
           to ``django.contrib.contenttypes.views.shortcut()`` as part of the
diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index 0d66b5115b..85050cf5ee 100644
--- a/docs/ref/templates/builtins.txt
+++ b/docs/ref/templates/builtins.txt
@@ -657,6 +657,17 @@ load
 
 Load a custom template tag set.
 
+For example, the following template would load all the tags and filters registered
+in ``somelibrary`` and ``otherlibrary``::
+
+    {% load somelibrary otherlibrary %}
+
+You can also selectively load individual templates or tags from a library, using
+the ``from`` argument. In this example, the template tags/filters named ``foo``
+and ``bar`` will be loaded from ``somelibrary``::
+
+    {% load foo bar from somelibrary %}
+
 See :doc:`Custom tag and filter libraries </howto/custom-template-tags>` for more information.
 
 .. templatetag:: now
@@ -838,6 +849,30 @@ Note that if you use ``{% ssi %}``, you'll need to define
 
 See also: ``{% include %}``.
 
+.. admonition:: Forwards compatibility
+
+    .. versionchanged:: 1.3
+
+    In Django 1.5, the behavior of the :ttag:`ssi` template tag will
+    change, with the the first argument being made into a context
+    variable, rather than being a special case unquoted constant. This
+    will allow the :ttag:`ssi` tag to use a context variable as the
+    value of the page to be included.
+
+    In order to provide a forwards compatibility path, Django 1.3
+    provides a future compatibility library -- ``future`` -- that
+    implements the new behavior. To use this library, add a
+    :ttag:`load` call at the top of any template using the :ttag:`ssi`
+    tag, and wrap the first argument to the :ttag:`ssi` tag in quotes.
+    For example::
+
+        {% load ssi from future %}
+        {% ssi '/home/html/ljworld.com/includes/right_generic.html' %}
+
+    In Django 1.5, the unquoted constant behavior will be replaced
+    with the behavior provided by the ``future`` tag library.
+    Existing templates be migrated to use the new syntax.
+
 .. templatetag:: templatetag
 
 templatetag
@@ -955,10 +990,37 @@ here's what it looks like::
     {% url path.to.view arg,arg2 %}
     {% url path.to.view arg, arg2 %}
 
-This syntax doesn't support the use of literal commas, or or equals
+This syntax doesn't support the use of literal commas, or equals
 signs. Did we mention you shouldn't use this syntax in any new
 projects?
 
+.. admonition:: Forwards compatibility
+
+    .. versionchanged:: 1.3
+
+    In Django 1.5, the behavior of the :ttag:`url` template tag will
+    change, with the the first argument being made into a context
+    variable, rather than being a special case unquoted constant. This
+    will allow the :ttag:`url` tag to use a context variable as the
+    value of the URL name to be reversed.
+
+    In order to provide a forwards compatibility path, Django 1.3
+    provides a future compatibility library -- ``future`` -- that
+    implements the new behavior. To use this library, add a
+    :ttag:`load` call at the top of any template using the :ttag:`url`
+    tag, and wrap the first argument to the :ttag:`url` tag in quotes.
+    For example::
+
+        {% load url from future %}
+        {% url 'myapp:view-name' %}
+
+    The new library also drops support for the comma syntax for
+    separating arguments to the :ttag:`url` template tag.
+
+    In Django 1.5, the old behavior will be replaced with the behavior
+    provided by the ``future`` tag library. Existing templates be
+    migrated to use the new syntax.
+
 .. templatetag:: widthratio
 
 widthratio
diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt
index ed72b94ab2..d1c42496ce 100644
--- a/docs/releases/1.3.txt
+++ b/docs/releases/1.3.txt
@@ -344,3 +344,44 @@ and Ctrl-C test termination) have been made redundant. In view of this
 redundancy, :class:`~django.test.simple.DjangoTestRunner` has been
 turned into an empty placeholder class, and will be removed entirely
 in Django 1.5.
+
+Changes to :ttag:`url` and :ttag:`ssi`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Most template tags will allow you to pass in either constants or
+variables as arguments -- for example::
+
+    {% extends "base.html" %}
+
+allows you to specify a base template as a constant, but if you have a
+context variable ``templ`` that contains the value ``base.html``::
+
+    {% extends templ %}
+
+is also legal.
+
+However, due to an accident of history, the :ttag:`url` and
+:ttag:`ssi` are different. These tags use the second, quoteless
+syntax, but interpret the argument as a constant. This means it isn't
+possible to use a context variable as the target of a :ttag:`url` and
+:ttag:`ssi` tag.
+
+Django 1.3 marks the start of the process to correct this historical
+accident. Django 1.3 adds a new template library -- ``future`` -- that
+provides alternate implementations of the :ttag:`url` and :ttag:`ssi`
+template tags. This ``future`` library implement behavior that makes
+the handling of the first argument consistent with the handling of all
+other variables. So, an existing template that contains::
+
+    {% url sample %}
+
+should be replaced with::
+
+    {% load url from future %}
+    {% url 'sample' %}
+
+The tags implementing the old behavior have been deprecated, and in
+Django 1.5, the old behavior will be replaced with the new behavior.
+To ensure compatibility with future versions of Django, existing
+templates should be modified to use the new ``future`` libraries and
+syntax.