From bc08d244fcd64c7dcb4dac54de19388903295778 Mon Sep 17 00:00:00 2001
From: Sean Hammond <seanhammond@lavabit.com>
Date: Thu, 12 Sep 2013 11:46:04 +0200
Subject: [PATCH] [#847] Clarify about variables passed into snippets

---
 .../v8_snippet/templates/home/index.html        |  1 +
 doc/theming.rst                                 | 17 ++++++++++++-----
 2 files changed, 13 insertions(+), 5 deletions(-)

diff --git a/ckanext/example_theme/v8_snippet/templates/home/index.html b/ckanext/example_theme/v8_snippet/templates/home/index.html
index a94d4a20682..60f8ee48d04 100644
--- a/ckanext/example_theme/v8_snippet/templates/home/index.html
+++ b/ckanext/example_theme/v8_snippet/templates/home/index.html
@@ -5,6 +5,7 @@
   {{ h.recently_changed_packages_activity_stream() }}
 
   <h3>Dataset of the day</h3>
+  {# Call the package_item.html snippet. #}
   {% snippet 'snippets/package_item.html',
              package=h.example_theme_dataset_of_the_day() %}
 
diff --git a/doc/theming.rst b/doc/theming.rst
index ca29ce9c715..db2d5160c7b 100644
--- a/doc/theming.rst
+++ b/doc/theming.rst
@@ -522,11 +522,18 @@ Let's change our |index.html| file to call this snippet:
 
 .. literalinclude:: ../ckanext/example_theme/v8_snippet/templates/home/index.html
 
-The ``{% snippet %}`` tag takes one or more arguments. The first argument is
-the name of the snippet to call. Any further arguments will be passed into
-the snippet as parameters. As in the ``package_item.html`` docstring above,
-each snippet's docstring should document the parameters it requires. In this
-example was pass just one parameter to the snippet: the dataset to be rendered.
+Here we pass two arguments to the ``{% snippet %}`` tag:
+
+.. literalinclude:: ../ckanext/example_theme/v8_snippet/templates/home/index.html
+   :start-after: {# Call the package_item.html snippet. #}
+   :end-before: {% endblock %}
+
+the first argument is the name of the snippet file to call. The second
+argument, separated by a comma, is the package to pass into the snippet.  After
+the filename you can pass any number of variables into a snippet, and these
+will all be available to the snippet code as top-level global variables.  As in
+the ``package_item.html`` docstring above, each snippet's docstring should
+document the parameters it requires.
 
 If you reload your `CKAN front page`_ in your web browser now, you should see
 the dataset of the day rendered nicely.