From 11f5cb0fb370f87a1825d5bf9442bdec8a8625ac Mon Sep 17 00:00:00 2001
From: Sean Hammond <seanhammond@lavabit.com>
Date: Thu, 12 Dec 2013 22:32:03 +0100
Subject: [PATCH] [#1377] Add this.options and this.el javascript example

---
 ckanext/example_theme/v17_popover/__init__.py |  0
 .../fanstatic/example_theme_popover.js        | 35 ++++++++++
 ckanext/example_theme/v17_popover/plugin.py   |  1 +
 .../templates/snippets/package_item.html      | 16 +++++
 doc/theming/best-practices.rst                | 12 ++++
 doc/theming/javascript.rst                    | 67 +++++++++++++++++++
 setup.py                                      |  1 +
 7 files changed, 132 insertions(+)
 create mode 100644 ckanext/example_theme/v17_popover/__init__.py
 create mode 100644 ckanext/example_theme/v17_popover/fanstatic/example_theme_popover.js
 create mode 120000 ckanext/example_theme/v17_popover/plugin.py
 create mode 100644 ckanext/example_theme/v17_popover/templates/snippets/package_item.html

diff --git a/ckanext/example_theme/v17_popover/__init__.py b/ckanext/example_theme/v17_popover/__init__.py
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/ckanext/example_theme/v17_popover/fanstatic/example_theme_popover.js b/ckanext/example_theme/v17_popover/fanstatic/example_theme_popover.js
new file mode 100644
index 00000000000..a8312e99cc4
--- /dev/null
+++ b/ckanext/example_theme/v17_popover/fanstatic/example_theme_popover.js
@@ -0,0 +1,35 @@
+/* example_theme_popover
+ *
+ * This JavaScript module adds a Bootstrap popover with some extra info about a
+ * dataset to the HTML element that the module is applied to. Users can click
+ * on the HTML element to show the popover.
+ *
+ * title - the title of the dataset
+ * license - the title of the dataset's copyright license
+ * num_resources - the number of resources that the dataset has.
+ *
+ */
+ckan.module('example_theme_popover', function (jQuery, _) {
+  return {
+    initialize: function () {
+
+      // Access some options passed to this JavaScript module by the calling
+      // template.
+      var num_resources = this.options.num_resources;
+      var license = this.options.license;
+
+      // Format a simple string with the number of resources and the license,
+      // e.g. "3 resources, Open Data Commons Attribution License".
+      var content = 'NUM resources, LICENSE'
+        .replace('NUM', this.options.num_resources)
+        .replace('LICENSE', this.options.license)
+
+      // Add a Bootstrap popover to the HTML element (this.el) that this
+      // JavaScript module was initialized on.
+      this.el.popover({title: this.options.title,
+                       content: content,
+                       placement: 'left'});
+    }
+  };
+});
+
diff --git a/ckanext/example_theme/v17_popover/plugin.py b/ckanext/example_theme/v17_popover/plugin.py
new file mode 120000
index 00000000000..1bef9f0d987
--- /dev/null
+++ b/ckanext/example_theme/v17_popover/plugin.py
@@ -0,0 +1 @@
+../v16_initialize_a_javascript_module/plugin.py
\ No newline at end of file
diff --git a/ckanext/example_theme/v17_popover/templates/snippets/package_item.html b/ckanext/example_theme/v17_popover/templates/snippets/package_item.html
new file mode 100644
index 00000000000..c1c7ce1c4ee
--- /dev/null
+++ b/ckanext/example_theme/v17_popover/templates/snippets/package_item.html
@@ -0,0 +1,16 @@
+{% ckan_extends %}
+
+{% block package_item_content %}
+  {{ super() }}
+  {% resource 'example_theme/example_theme_popover.js' %}
+
+  {# Apply out JavaScript module to an HTML <button> element.
+     The additional data-module-* attributes are options that will be passed
+     to the JavaScript module. #}
+  <button data-module="example_theme_popover"
+          data-module-title="{{ package.title }}"
+          data-module-license="{{ package.license_title }}"
+          data-module-num_resources="{{ package.num_resources }}">
+    <i class="icon-info-sign"></i>
+  </button>
+{% endblock %}
diff --git a/doc/theming/best-practices.rst b/doc/theming/best-practices.rst
index bea48709dde..1ea6ddf436e 100644
--- a/doc/theming/best-practices.rst
+++ b/doc/theming/best-practices.rst
@@ -72,6 +72,18 @@ example: ``fanstatic/example_theme_popover.js``:
 
 .. literalinclude:: /../ckanext/example_theme/v16_initialize_a_javascript_module/fanstatic/example_theme_popover.js
 
+.. _javascript module docstrings best practice:
+
+-------------------------------------------
+|javascript| modules should have docstrings
+-------------------------------------------
+
+A |javascript| module should have a docstring at the top of the file, briefly
+documentating what the module does and what options it takes. For example:
+
+.. literalinclude:: /../ckanext/example_theme/v17_popover/fanstatic/example_theme_popover.js
+   :language: javascript
+
 
 --------------------------------------------
 Use ``{% snippet %}``, not ``{% include %}``
diff --git a/doc/theming/javascript.rst b/doc/theming/javascript.rst
index db54e56c01e..cd420f1e72b 100644
--- a/doc/theming/javascript.rst
+++ b/doc/theming/javascript.rst
@@ -30,6 +30,7 @@ To get CKAN to call some custom JavaScript code, we need to:
       function? I've seen ``jQuery`` and ``$`` and ``i18n`` and ``_``.
 
    .. literalinclude:: /../ckanext/example_theme/v16_initialize_a_javascript_module/fanstatic/example_theme_popover.js
+      :language: javascript
 
    .. note::
 
@@ -56,6 +57,7 @@ To get CKAN to call some custom JavaScript code, we need to:
    contents:
 
    .. literalinclude:: /../ckanext/example_theme/v16_initialize_a_javascript_module/templates/snippets/package_item.html
+      :language: django
 
    .. todo:: Link to something about HTML data-* attributes.
 
@@ -82,6 +84,71 @@ To get CKAN to call some custom JavaScript code, we need to:
       own ``<script>`` tags.
 
 
+--------------------------------
+``this.options`` and ``this.el``
+--------------------------------
+
+Now let's start to make our |javascript| module do something useful: show a
+`Bootstrap popover <http://getbootstrap.com/2.3.2/javascript.html#popovers>`_
+with some extra info about the dataset when the user clicks on the info button.
+
+.. todo:: Insert screenshot.
+
+First, we need our Jinja template to pass some of the dataset's fields to our
+|javascript| module as *options*. Change ``package_item.html`` to look like
+this:
+
+.. literalinclude:: /../ckanext/example_theme/v17_popover/templates/snippets/package_item.html
+   :language: django
+
+This adds some ``data-module-*`` attributes to our ``<button>`` element, e.g.
+``data-module-title="{{ package.title }}"`` (``{{ package.title }}`` is a
+:ref:`Jinja2 expression <expressions and variables>` that evaluates to the
+title of the dataset, CKAN passes the Jinja2 variable ``package`` to our
+template).
+
+.. warning::
+
+   Although HTML 5 treats any attribute named ``data-*`` as a data attributes,
+   only attributes named ``data-module-*`` will be passed as options to a CKAN
+   |javascript| module.
+
+Now let's make use of these options in our |javascript| module. Change
+``example_theme_popover.js`` to look like this:
+
+.. literalinclude:: /../ckanext/example_theme/v17_popover/fanstatic/example_theme_popover.js
+   :language: javascript
+
+.. note::
+
+   It's best practice to add a docstring to the top of a |javascript| module,
+   as in the example above, briefly documenting what the module does and what
+   options it takes. See :ref:`javascript module docstrings best practice`.
+
+Any ``data-module-*`` attributes on the HTML element are passed into the
+|javascript| module in the object ``this.options``:
+
+.. literalinclude:: /../ckanext/example_theme/v17_popover/fanstatic/example_theme_popover.js
+   :language: javascript
+   :start-after: // template.
+   :end-before: // Format
+
+A |javascript| module can access the HTML element that it was applied to
+through the ``this.el`` variable. To add a popover to our info button, we call
+Bootstap's ``popover()`` function on the element, passing in an options object
+with some of the options that Bootstrap's popovers accept:
+
+.. FIXME: This should be a literal.
+
+::
+
+ // Add a Bootstrap popover to the HTML element (this.el) that this
+ // JavaScript module was initialized on.
+ this.el.popover({title: this.options.title,
+                  content: content,
+                  placement: 'left'});
+
+
 --------------------
 Responding to events
 --------------------
diff --git a/setup.py b/setup.py
index 560c6a69280..16f705df946 100644
--- a/setup.py
+++ b/setup.py
@@ -95,6 +95,7 @@
         'example_theme_v14_more_custom_css = ckanext.example_theme.v14_more_custom_css.plugin:ExampleThemePlugin',
         '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',
     ],
     'ckan.system_plugins': [
         'domain_object_mods = ckan.model.modification:DomainObjectModificationExtension',