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

1 files changed, 27 insertions, 3 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