[#847] Add extra_public_paths example

ckan/templates/home/snippets/promoted.html

@@ -13,10 +13,15 @@ <h1 class="page-heading">{{ _("Welcome to CKAN") }}</h1>
       </p>
     {% endif %}
   </header>
-  <section class="featured media-overlay">
-    <h2 class="media-heading">{{ _("This is a featured section") }}</h2>
-    <a class="media-image" href="#">
-      <img src="http://placehold.it/420x220" alt="Placeholder" width="420" height="220" />
-    </a>
-  </section>
+
+  {% block home_image %}
+    <section class="featured media-overlay">
+      <h2 class="media-heading">{% block home_image_caption %}{{ _("This is a featured section") }}{% endblock %}</h2>
+      {% block home_image_content %}
+        <a class="media-image" href="#">
+          <img src="http://placehold.it/420x220" alt="Placeholder" width="420" height="220" />
+        </a>
+      {% endblock %}
+    </section>
+  {% endblock %}
 </div>

ckanext/example_theme/v11_extra_public_directory/plugin.py

@@ -0,0 +1,46 @@
+import ckan.plugins as plugins
+import ckan.plugins.toolkit as toolkit
+
+
+def most_popular_groups():
+    '''Return a sorted list of the groups with the most datasets.'''
+
+    # Get a list of all the site's groups from CKAN, sorted by number of
+    # datasets.
+    groups = toolkit.get_action('group_list')(
+            data_dict={'sort': 'packages desc', 'all_fields': True})
+
+    # Truncate the list to the 10 most popular groups only.
+    groups = groups[:10]
+
+    return groups
+
+
+class ExampleThemePlugin(plugins.SingletonPlugin):
+    '''An example theme plugin.
+
+    '''
+    plugins.implements(plugins.IConfigurer)
+
+    # Declare that this plugin will implement ITemplateHelpers.
+    plugins.implements(plugins.ITemplateHelpers)
+
+    def update_config(self, config):
+
+        # Add this plugin's templates dir to CKAN's extra_template_paths, so
+        # that CKAN will use this plugin's custom templates.
+        toolkit.add_template_directory(config, 'templates')
+
+        # Add this plugin's public dir to CKAN's extra_public_paths, so
+        # that CKAN will use this plugin's custom static files.
+        toolkit.add_public_directory(config, 'public')
+
+    def get_helpers(self):
+        '''Register the most_popular_groups() function above as a template
+        helper function.
+
+        '''
+        # Template helper function names should begin with the name of the
+        # extension they belong to, to avoid clashing with functions from
+        # other extensions.
+        return {'example_theme_most_popular_groups': most_popular_groups}

ckanext/example_theme/v11_extra_public_directory/templates/home/index.html

@@ -0,0 +1,37 @@
+{% ckan_extends %}
+
+{% block home_image_content %}
+  <a class="media-image" href="#">
+    <img src="featured-image.jpg" alt="Featured image"
+         width="420" height="220" />
+  </a>
+{% endblock %}
+
+{% block home_image_caption %}
+  {{ _("This is a customized featured section") }}
+{% endblock %}
+
+{% block secondary_content %}
+
+  <div class="row">
+
+    <div class="span6">
+      <div class="box">
+        <section class="module">
+          <header class="module-heading">
+            <h3>Recent activity</h3>
+          </header>
+          <div class="module-content">
+            {{ h.recently_changed_packages_activity_stream(limit=10) }}
+          </div>
+        </section>
+      </div>
+    </div>
+
+    <div class="span6">
+      {% snippet 'snippets/example_theme_most_popular_groups.html' %}
+    </div>
+
+  </div>
+
+{% endblock %}

ckanext/example_theme/v11_extra_public_directory/templates/home/snippets/promoted.html

@@ -0,0 +1,13 @@
+{% ckan_extends %}
+
+{% block home_image_caption %}
+  {{ _("CKAN's data previewing tool has many powerful features") }}
+{% endblock %}
+
+{# Replace the promoted image. #}
+{% block home_image_content %}
+  <a class="media-image" href="#">
+    <img src="/promoted-image.jpg" alt="Featured image"
+         width="420" height="220" />
+  </a>
+{% endblock %}

ckanext/example_theme/v11_extra_public_directory/templates/snippets

@@ -0,0 +1 @@
+../../v10_HTML_and_CSS/templates/snippets

doc/theming.rst

@@ -703,16 +703,77 @@ stream and groups lists layed out and styled nicely.
 CKAN custom Jinja2 tags reference
 ---------------------------------
 
----------------------------------------------------------------------
-Adding CSS, JavaScript, images and other static files using Fanstatic
----------------------------------------------------------------------
+-------------------
+Adding static files
+-------------------
 
-.. todo::
+You may need to add some custom *static files* to your CKAN site and use them
+from your templates, for example image files, PDF files, or any other static
+files that should be returned as-is by the webserver (as opposed to Jinja
+template files, which CKAN renders before returning them to the user).
+
+By adding a directory to CKAN's :ref:`extra_public_paths` config setting,
+a plugin can make a directory of static files available to be used or linked to
+by templates. Let's add a static image file, and change the home page template
+to use our file as the promoted image on the front page.
+
+.. note::
+
+   If you're adding |javascript| or CSS files, consider using Fanstatic instead
+   of :ref:`extra_public_paths`, to take advantage of extra features.
+   See :ref:`fanstatic tutorial` below.
+
+First, create a ``public`` directory in your extension with a
+``promoted-image.jpg`` file in it::
+
+ ckanext-example_theme/
+   public/
+     promoted-image.jpg
+
+``promoted-image.jpg`` should be a 420x220px JPEG image file. You could use
+this image file for example:
+
+.. image:: ../ckanext/example_theme/v11_extra_public_directory/public/promoted-image.jpg
+   :alt: An example promoted image
+   :height: 220px
+   :width: 420px
+
+Then in ``plugin.py``, register your ``public`` directory with CKAN by calling
+the :py:func:`~ckan.plugins.toolkit.add_public_directory` function. Add this
+line to the :py:func:`~ckan.ckanext.example_theme.v11_extra_public_directory.plugin.update_config`
+function:
 
-   * Introduce Fanstatic
-   * Use the plugin to register a Fanstatic library
-   * Use ``{% resource %}`` to load stuff from the library
-   * Presumably you can also load stuff from the core library?
+.. literalinclude:: ../ckanext/example_theme/v11_extra_public_directory/plugin.py
+   :pyobject: ExampleThemePlugin.update_config
+
+If you now browse to `127.0.0.1:5000/promoted-image.jpg <http://127.0.0.1:5000/promoted-image.jpg>`_,
+you should see your image file.
+
+To replace the image on the front page with your custom image, we need to
+override the ``promoted.html`` template snippet. Create the following directory
+and file::
+
+ ckanext-example_theme/
+   templates/
+     home/
+       snippets/
+         promoted.html
+
+Edit your new ``promoted.html`` snippet, and insert these contents:
+
+.. literalinclude:: ../ckanext/example_theme/v11_extra_public_directory/templates/home/snippets/promoted.html
+
+After calling ``{% ckan_extends %}`` to declare that it extends (rather than
+completely replaces) the default ``promoted.html`` snippet, this custom snippet
+overrides two of ``promoted.html``'s template blocks. The first block replaces
+the caption text of the promoted image. The second block replaces the ``<img>``
+tag itself, pointing it at our custom static image file:
+
+.. literalinclude:: ../ckanext/example_theme/v11_extra_public_directory/templates/home/snippets/promoted.html
+   :start-after: {# Replace the promoted image. #}
+
+If you now reload the `CKAN front page`_ in your browser, you should see the
+promoted image replaced with our custom one.
 
 
 ----------------------

setup.py

@@ -136,6 +136,7 @@
     example_theme_v8=ckanext.example_theme.v8_snippet.plugin:ExampleThemePlugin
     example_theme_v9=ckanext.example_theme.v9_custom_snippet.plugin:ExampleThemePlugin
     example_theme_v10=ckanext.example_theme.v10_HTML_and_CSS.plugin:ExampleThemePlugin
+    example_theme_v11=ckanext.example_theme.v11_extra_public_directory.plugin:ExampleThemePlugin
 
     [ckan.system_plugins]
     domain_object_mods = ckan.model.modification:DomainObjectModificationExtension