[#1377] Add a snippet API javascript example

This example could be improved by passing only the package id to the
snippet, the snippet can then use h.get_action('package_show')(...) to
get the full package dict.

ckanext/example_theme/v18_snippet_api/fanstatic/example_theme_popover.css

@@ -0,0 +1,27 @@
+.dataset-list .popover .nums {
+
+  /* We're reusing the .nums class from the dataset read page,
+   * but we don't want the border, margin and padding, get rid of them. */
+  border: none;
+  margin: 0;
+  padding: 0;
+
+  /* We want the license and numbers to appear side by side, so float the
+   * numbers list to the left and make it take up just over half of
+   * the width of the popover. */
+  float: left;
+  width: 55%;
+}
+
+.dataset-list .popover .license {
+
+  /* Prevent the words in the license from being wrapped mid-word. */
+  word-break: keep-all;
+}
+
+.dataset-list .popover .go-to-dataset {
+
+  /* Float the "Go to dataset" button to the right side of the popover,
+   * this puts some space between the two buttons. */
+  float: right;
+}

ckanext/example_theme/v18_snippet_api/fanstatic/example_theme_popover.js

@@ -0,0 +1,55 @@
+ckan.module('example_theme_popover', function (jQuery, _) {
+  return {
+    initialize: function () {
+
+      // proxyAll() ensures that whenever an _on*() function from this
+      // JavaScript module is called, the `this` variable in the function will
+      // be this JavaScript module object.
+      //
+      // You probably want to call proxyAll() like this in the initialize()
+      // function of most modules.
+      //
+      // This is a shortcut function provided by CKAN, it wraps jQuery's
+      // proxy() function: http://api.jquery.com/jQuery.proxy/
+      jQuery.proxyAll(this, /_on/);
+
+      // Add a Bootstrap popover to the button. Since we don't have the HTML
+      // from the snippet yet, we just set the content to "Loading..."
+      this.el.popover({title: this.options.title, html: true,
+                       content: 'Loading...', placement: 'left'});
+
+      // Add an event handler to the button, when the user clicks the button
+      // our _onClick() function will be called.
+      this.el.on('click', this._onClick);
+    },
+
+    // Whether or not the rendered snippet has already been received from CKAN.
+    _snippetReceived: false,
+
+    _onClick: function(event) {
+
+        // Send an ajax request to CKAN to render the popover.html snippet.
+        // We wrap this in an if statement because we only want to request
+        // the snippet from CKAN once, not every time the button is clicked.
+        if (!this._snippetReceived) {
+            this.sandbox.client.getTemplate('example_theme_popover.html',
+                                            this.options,
+                                            this._onReceiveSnippet);
+            this._snippetReceived = true;
+        }
+    },
+
+    // CKAN calls this function when it has rendered the snippet, and passes
+    // it the rendered HTML.
+    _onReceiveSnippet: function(html) {
+
+      // Replace the popover with a new one that has the rendered HTML from the
+      // snippet as its contents.
+      this.el.popover('destroy');
+      this.el.popover({title: this.options.title, html: true,
+                       content: html, placement: 'left'});
+      this.el.popover('show');
+    },
+
+  };
+});

ckanext/example_theme/v18_snippet_api/plugin.py

@@ -0,0 +1 @@
+../v17_popover/plugin.py

ckanext/example_theme/v18_snippet_api/templates/ajax_snippets/example_theme_popover.html

@@ -0,0 +1,38 @@
+{# The contents for a dataset popover.
+
+   id - the id of the dataset
+   num_resources - the dataset's number of resources
+   license_title - the dataset's license title
+
+#}
+<div class="context-info">
+  <div class="nums">
+    <dl>
+
+      <dt>{{ _('Followers') }}</dt>
+      <dd>{{ h.get_action('dataset_follower_count', {'id': id}) }}</dd>
+
+      <dt>{{ _('Resources') }}</dt>
+      <dd>{{ num_resources }}</dd>
+
+    </dl>
+  </div>
+
+  <div class="license">
+    <dl>
+      <dt>License</dt>
+      <dd>{{ license_title }}</dd>
+    </dl>
+  </div>
+
+  <div class="clearfix"></div>
+
+  {{ h.follow_button('dataset', id) }}
+
+  <a class="btn go-to-dataset"
+     href="{{ h.url_for(controller='package', action='read', id=id) }}">
+    <i class="icon-circle-arrow-right"></i>
+    Go to dataset
+  </a>
+
+</div>

ckanext/example_theme/v18_snippet_api/templates/snippets/package_item.html

@@ -0,0 +1,16 @@
+{% ckan_extends %}
+
+{% block package_item_content %}
+  {{ super() }}
+
+  {% resource 'example_theme/example_theme_popover.js' %}
+  {% resource 'example_theme/example_theme_popover.css' %}
+
+  <button data-module="example_theme_popover"
+          data-module-id="{{ package.id }}"
+          data-module-title="{{ package.title }}"
+          data-module-license_title="{{ package.license_title }}"
+          data-module-num_resources="{{ package.num_resources }}">
+    <i class="icon-info-sign"></i>
+  </button>
+{% endblock %}

setup.py

@@ -96,6 +96,7 @@
         'example_theme_v15_fanstatic = ckanext.example_theme.v15_fanstatic.plugin:ExampleThemePlugin',
         'example_theme_v16_initialize_a_javascript_module = ckanext.example_theme.v16_initialize_a_javascript_module.plugin:ExampleThemePlugin',
         'example_theme_v17_popover = ckanext.example_theme.v17_popover.plugin:ExampleThemePlugin',
+        'example_theme_v18_snippet_api = ckanext.example_theme.v18_snippet_api.plugin:ExampleThemePlugin',
     ],
     'ckan.system_plugins': [
         'domain_object_mods = ckan.model.modification:DomainObjectModificationExtension',