Fixes #7817 and #9456.

- The include tag now has a 'with' option to include to provide extra context
  vairables to the included template.

- The include tag now has an 'only' option to exclude the current context
  when rendering the included template.

- The with tag now accepts multiple variable assignments.

- The with, include and blocktrans tags now use a new keyword argument format
  for variable assignments (e.g. `{% with foo=1 bar=2 %}`).

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

4 files changed, 42 insertions, 13 deletions

diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index da8cac8555..0dc0372d59 100644
--- a/docs/ref/templates/builtins.txt
+++ b/docs/ref/templates/builtins.txt
@@ -639,9 +639,19 @@ including it. This example produces the output ``"Hello, John"``:
 
     * The ``name_snippet.html`` template::
 
-        Hello, {{ person }}
+        {{ greeting }}, {{ person|default:"friend" }}!
 
-See also: ``{% ssi %}``.
+.. versionchanged:: 1.3
+   Additional context and exclusive context.
+
+You can pass additional context to the template using keyword arguments::
+
+    {% include "name_snippet.html" with person="Jane" greeting="Hello" "%}
+
+If you want to only render the context with the variables provided (or even
+no variables at all), use the ``only`` option::
+
+    {% include "name_snippet.html" with greeting="Hi" only %}
 
 .. note::
     The :ttag:`include` tag should be considered as an implementation of
@@ -650,6 +660,8 @@ See also: ``{% ssi %}``.
     This means that there is no shared state between included templates --
     each include is a completely independent rendering process.
 
+See also: ``{% ssi %}``.
+
 .. templatetag:: load
 
 load
@@ -1044,18 +1056,30 @@ with
 
 .. versionadded:: 1.0
 
+.. versionchanged:: 1.3
+   New keyword argument format and multiple variable assignments.
+
 Caches a complex variable under a simpler name. This is useful when accessing
 an "expensive" method (e.g., one that hits the database) multiple times.
 
 For example::
 
-    {% with business.employees.count as total %}
+    {% with total=business.employees.count %}
         {{ total }} employee{{ total|pluralize }}
     {% endwith %}
 
 The populated variable (in the example above, ``total``) is only available
 between the ``{% with %}`` and ``{% endwith %}`` tags.
 
+You can assign more than one context variable::
+
+    {% with alpha=1 beta=2 %}
+        ...
+    {% endwith %}
+
+.. note:: The previous more verbose format is still supported:
+   ``{% with business.employees.count as total %}``
+
 .. _ref-templates-builtins-filters:
 
 Built-in filter reference
diff --git a/docs/topics/db/optimization.txt b/docs/topics/db/optimization.txt
index fda26f1744..ec5b6fa160 100644
--- a/docs/topics/db/optimization.txt
+++ b/docs/topics/db/optimization.txt
@@ -206,7 +206,7 @@ many-to-many relation to User, the following template code is optimal:
 .. code-block:: html+django
 
    {% if display_inbox %}
-     {% with user.emails.all as emails %}
+     {% with emails=user.emails.all %}
        {% if emails %}
          <p>You have {{ emails|length }} email(s)</p>
          {% for email in emails %}
diff --git a/docs/topics/forms/index.txt b/docs/topics/forms/index.txt
index 30b09c00a9..fc19ff63ef 100644
--- a/docs/topics/forms/index.txt
+++ b/docs/topics/forms/index.txt
@@ -371,12 +371,11 @@ using the :ttag:`include` tag to reuse it in other templates::
     {% endfor %}
 
 If the form object passed to a template has a different name within the
-context, you can alias it using the :ttag:`with` tag::
+context, you can alias it using the ``with`` argument of the :ttag:`include`
+tag::
 
     <form action="/comments/add/" method="post">
-        {% with comment_form as form %}
-            {% include "form_snippet.html" %}
-        {% endwith %}
+        {% include "form_snippet.html" with form=comment_form %}
         <p><input type="submit" value="Submit comment" /></p>
     </form>
 
diff --git a/docs/topics/i18n/internationalization.txt b/docs/topics/i18n/internationalization.txt
index c2bd6eb309..cf009e4244 100644
--- a/docs/topics/i18n/internationalization.txt
+++ b/docs/topics/i18n/internationalization.txt
@@ -438,6 +438,9 @@ It's not possible to mix a template variable inside a string within ``{% trans
 ``blocktrans`` template tag
 ---------------------------
 
+.. versionchanged:: 1.3
+   New keyword argument format.
+
 Contrarily to the ``trans`` tag, the ``blocktrans`` tag allows you to mark
 complex sentences consisting of literals and variable content for translation
 by making use of placeholders::
@@ -448,18 +451,18 @@ To translate a template expression -- say, accessing object attributes or
 using template filters -- you need to bind the expression to a local variable
 for use within the translation block. Examples::
 
-    {% blocktrans with article.price as amount %}
+    {% blocktrans with amount=article.price %}
     That will cost $ {{ amount }}.
     {% endblocktrans %}
 
-    {% blocktrans with value|filter as myvar %}
+    {% blocktrans with myvar=value|filter %}
     This will have {{ myvar }} inside.
     {% endblocktrans %}
 
 If you need to bind more than one expression inside a ``blocktrans`` tag,
 separate the pieces with ``and``::
 
-    {% blocktrans with book|title as book_t and author|title as author_t %}
+    {% blocktrans with book_t=book|title author_t=author|title %}
     This is {{ book_t }} by {{ author_t }}
     {% endblocktrans %}
 
@@ -474,7 +477,7 @@ This tag also provides for pluralization. To use it:
 
 An example::
 
-    {% blocktrans count list|length as counter %}
+    {% blocktrans count counter=list|length %}
     There is only one {{ name }} object.
     {% plural %}
     There are {{ counter }} {{ name }} objects.
@@ -482,7 +485,7 @@ An example::
 
 A more complex example::
 
-    {% blocktrans with article.price as amount count i.length as years %}
+    {% blocktrans with amount=article.price count years=i.length %}
     That will cost $ {{ amount }} per year.
     {% plural %}
     That will cost $ {{ amount }} per {{ years }} years.
@@ -494,6 +497,9 @@ construct is internally converted to an ``ungettext`` call. This means the
 same :ref:`notes regarding ungettext variables <pluralization-var-notes>`
 apply.
 
+.. note:: The previous more verbose format is still supported:
+   ``{% blocktrans with book|title as book_t and author|title as author_t %}``
+
 .. _template-translation-vars:
 
 Other tags