From 9a0b71b05dbcb093566adff13c0751a845cbc130 Mon Sep 17 00:00:00 2001
From: Sean Hammond <seanhammond@lavabit.com>
Date: Tue, 26 Nov 2013 20:33:38 +0100
Subject: [PATCH] [#847] Update template snippets example

---
 ckanext/example_theme/v09_snippet/__init__.py |  0
 .../home/{index.html => layout1.html}         |  7 ++++++-
 doc/theming/index.rst                         |  1 +
 doc/theming/template-snippets.rst             |  8 +++++++
 doc/theming/templates.rst                     | 21 +++++++++----------
 5 files changed, 25 insertions(+), 12 deletions(-)
 create mode 100644 ckanext/example_theme/v09_snippet/__init__.py
 rename ckanext/example_theme/v09_snippet/templates/home/{index.html => layout1.html} (77%)
 create mode 100644 doc/theming/template-snippets.rst

diff --git a/ckanext/example_theme/v09_snippet/__init__.py b/ckanext/example_theme/v09_snippet/__init__.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/ckanext/example_theme/v09_snippet/templates/home/index.html b/ckanext/example_theme/v09_snippet/templates/home/layout1.html
similarity index 77%
rename from ckanext/example_theme/v09_snippet/templates/home/index.html
rename to ckanext/example_theme/v09_snippet/templates/home/layout1.html
index c89acea2a21..057490e69ea 100644
--- a/ckanext/example_theme/v09_snippet/templates/home/index.html
+++ b/ckanext/example_theme/v09_snippet/templates/home/layout1.html
@@ -1,10 +1,15 @@
 {% ckan_extends %}
 
-{% block secondary_content %}
+{% block featured_group %}
 
   {{ h.recently_changed_packages_activity_stream() }}
 
+{% endblock %}
+
+{% block featured_organization %}
+
   <h3>Most popular groups</h3>
+
   {# Call the group_list.html snippet. #}
   {% snippet 'group/snippets/group_list.html',
              groups=h.example_theme_most_popular_groups() %}
diff --git a/doc/theming/index.rst b/doc/theming/index.rst
index c74c2fd477f..7c27bc3509d 100644
--- a/doc/theming/index.rst
+++ b/doc/theming/index.rst
@@ -46,3 +46,4 @@ your custom CKAN theme.
    jinja-tags
    variables-and-functions
    template-helper-functions
+   template-snippets
diff --git a/doc/theming/template-snippets.rst b/doc/theming/template-snippets.rst
new file mode 100644
index 00000000000..ca4bf72f0a5
--- /dev/null
+++ b/doc/theming/template-snippets.rst
@@ -0,0 +1,8 @@
+===========================
+Template snippets reference
+===========================
+
+.. todo::
+
+   Autodoc all the default template snippets here.
+   This probably means writing a Sphinx plugin.
diff --git a/doc/theming/templates.rst b/doc/theming/templates.rst
index db1186cbd06..71177c92404 100644
--- a/doc/theming/templates.rst
+++ b/doc/theming/templates.rst
@@ -484,29 +484,28 @@ Template snippets
 functions, can be called from any template file. To call a snippet, you use
 another of CKAN's custom Jinja2 tags: ``{% snippet %}``. CKAN comes with a
 selection of snippets, which you can find in the various ``snippets``
-directories in ``ckan/templates/``, such as ``ckan/templates/snippets/`` and
-``ckan/templates/package/snippets/``.
-
-.. todo::
-
-   Autodoc all the default snippets, link to reference docs.
+directories in `ckan/templates/ <https://github.com/okfn/ckan/tree/master/ckan/templates>`_,
+such as `ckan/templates/snippets/ <https://github.com/okfn/ckan/tree/master/ckan/templates/snippets>`_
+and `ckan/templates/package/snippets/ <https://github.com/okfn/ckan/tree/master/ckan/templates/package/snippets>`_.
+For a complete list of the default snippets available to templates, see
+:doc:`template-snippets`.
 
 ``ckan/templates/group/snippets/group_list.html`` is a snippet that renders a
 list of groups nicely (it's used to render the groups on CKAN's ``/group`` page
-and one user dashboard pages, for example):
+and on user dashboard pages, for example):
 
 .. literalinclude:: /../ckan/templates/group/snippets/group_list.html
 
 (As you can see, this snippet calls another snippet, ``group_item.html``, to
 render each individual group.)
 
-Let's change our |index.html| file to call this snippet:
+Let's change our |layout1.html| file to call this snippet:
 
-.. literalinclude:: /../ckanext/example_theme/v09_snippet/templates/home/index.html
+.. literalinclude:: /../ckanext/example_theme/v09_snippet/templates/home/layout1.html
 
 Here we pass two arguments to the ``{% snippet %}`` tag:
 
-.. literalinclude:: /../ckanext/example_theme/v09_snippet/templates/home/index.html
+.. literalinclude:: /../ckanext/example_theme/v09_snippet/templates/home/layout1.html
    :start-after: {# Call the group_list.html snippet. #}
    :end-before: {% endblock %}
 
@@ -518,7 +517,7 @@ As in the ``group_list.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.
+the groups rendered nicely.
 
 
 ---------------------------------