JavaScript code in CKAN is broken down into modules: small, independent units
of JavaScript code. CKAN themes can add JavaScript features by providing their
own modules. This tutorial will explain the main concepts involved in CKAN
JavaScript modules and walk you through the process of adding custom modules
to themes.

See also

This tutorial assumes a basic understanding of CKAN plugins and templating,
see:

The idea behind CKAN’s JavaScript modules is to keep the code simple and
easy to test, debug and maintain, by breaking it down into small,
independent modules. JavaScript modules in CKAN don’t share global
variables, and don’t call each other’s code.

These JavaScript modules are attached to HTML elements in the page, and enhance
the functionality of those elements. The idea is that an HTML element with a
JavaScript module attached should still be fully functional even if JavaScript
is completely disabled (e.g. because the user’s web browser doesn’t support
JavaScript). The user experience may not be quite as nice without JavaScript,
but the functionality should still be there. This is a programming technique
known as graceful degradation, and is a basic tenet of web accessibility.

In the sections below, we’ll walk you through the steps to add a new JavaScript
feature to CKAN - dataset info popovers. We’ll add an info button to each
dataset on the datasets page which, when clicked, opens a popover containing
some extra information and user actions related to the dataset:

This bit of JavaScript calls the ckan.module() function to register a
new JavaScript module with CKAN. ckan.module() takes two arguments: the
name of the module being registered ('example_theme_popover' in this
example) and a function that returns the module itself. The function takes
two arguments, which we’ll look at later. The module is just a JavaScript
object with a single attribute, initialize, whose value is a function
that CKAN will call to initialize the module. In this example, the
initialize function just prints out a confirmation message - this
JavaScript module doesn’t do anything interesting yet.

Note

JavaScript module names should begin with the name of the extension,
to avoid conflicting with other modules. See Avoid name clashes.

Note

Each JavaScript module’s initialize() function is called on
DOM ready.

Include the JavaScript module in a page, using Fanstatic, and apply it to
one or more HTML elements on that page. We’ll override CKAN’s
package_item.html template snippet to insert our module whenever a
package is rendered as part of a list of packages (for example, on the
dataset search page). Create the file
ckanext-example_theme/ckanext/example_theme_docs/templates/snippets/package_item.html with these
contents:

{%ckan_extends%}{%blockcontent%}{{super()}}{# Use Fanstatic to include our custom JavaScript module. A <script> tag for the module will be inserted in the right place at the bottom of the page. #}{%resource'example_theme/example_theme_popover.js'%}{# Apply our JavaScript module to an HTML element. The data-module attribute, which can be applied to any HTML element, tells CKAN to initialize an instance of the named JavaScript module for the element. The initialize() method of our module will be called with this HTML element as its this.el object. #} <button data-module="example_theme_popover" class="btn" href="#"> <i class="fa fa-info-circle"></i> </button>{%endblock%}

If you now restart the development server and open
http://127.0.0.1:5000/dataset in your web browser, you should see an
extra info button next to each dataset shown. If you open a
JavaScript console in your browser, you should see the message that your
module has printed out.

See also

Most web browsers come with built-in developer tools including a
JavaScript console that lets you see text printed by JavaScript code
to console.log(), a JavaScript debugger, and more. For example:

If you have more than one dataset on your page, you’ll see the module’s
message printed once for each dataset. The package_item.html template
snippet is rendered once for each dataset that’s shown in the list, so your
<button> element with the data-module="example_theme_popover"
attribute is rendered once for each dataset, and CKAN creates a new instance
of your JavaScript module for each of these <button> elements. If you
view the source of your page, however, you’ll see that
example_theme_popover.js is only included with a <script> tag once.
Fanstatic is smart enough to deduplicate resources.

Note

JavaScript modules must be included as Fanstatic resources,
you can’t add them to a public directory and include them using your
own <script> tags.

This adds some data-module-* attributes to our <button> element, e.g.
data-module-title="{{package.title}}" ({{package.title}} is a
Jinja2 expression 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 attribute,
only attributes named data-module-* will be passed as options to a CKAN
JavaScript module. So we have to named our parameters
data-module-title etc., not just data-title.

Now let’s make use of these options in our JavaScript module. Change
example_theme_popover.js to look like this:

"use strict";/* 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($){return{initialize:function(){// Access some options passed to this JavaScript module by the calling// template.varnum_resources=this.options.num_resources;varlicense=this.options.license;// Format a simple string with the number of resources and the license,// e.g. "3 resources, Open Data Commons Attribution License".varcontent='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'});}};});

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 JavaScript modules should have docstrings.

Any data-module-* attributes on the HTML element are passed into the
JavaScript module in the object this.options:

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:

Default values for JavaScript module options can be provided by adding an
options object to the module. If the HTML element doesn’t have a
data-module-* attribute for an option, then the default will be used
instead. For example…

So far, we’ve used simple JavaScript string formatting to put together the
contents of our popover. If we want the popover to contain much more complex
HTML we really need to render a template for it, using the full power of
Jinja2 templates and CKAN’s
template helper functions. Let’s edit our
plugin to use a Jinja2 template to render the contents of the popups nicely.

First, edit package_item.html to make it pass a few more parameters to the
JavaScript module using data-module-* attributes:

This is a Jinja2 template that renders some nice looking contents for a
popover, containing a few bits of information about a dataset. It uses a number
of CKAN’s Jinja2 templating features, including marking user-visible strings
for translation and calling template helper functions. See Customizing CKAN’s templates
for details about Jinja2 templating in CKAN.

Note

The new template file has to be in a templates/ajax_snippets/ directory
so that we can use the template from our JavaScript code using
CKAN’s getTemplate() function. Only templates
from ajax_snippets directories are available from the
getTemplate() function.

Next, edit fanstatic/example_theme_popover.js as shown below.
There’s a lot going on in this new JavaScript code, including:

The sandbox is a JavaScript object, available to all JavaScript modules
as this.sandbox, that contains a collection of useful functions and
variables.

this.sandbox.client is a CKAN API client written in JavaScript, that
should be used whenever a JavaScript module needs to talk to the CKAN API,
instead of modules doing their own HTTP requests.

this.sandbox.client.getTemplate() is a function that sends an
asynchronous (ajax) HTTP request (i.e. send an HTTP request from
JavaScript and receive the response in JavaScript, without causing
the browser to reload the whole page) to CKAN asking for a template snippet
to be rendered.

"use strict";ckan.module('example_theme_popover',function($){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/$.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:this._('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');},};});

Finally, we need some custom CSS to make the HTML from our new snippet look
nice. In package_item.html above we added a {%resource%} tag to
include a custom CSS file. Now we need to create that file,
ckanext-example_theme/ckanext/example_theme/fanstatic/example_theme_popover.css:

.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;}

Restart CKAN, and your dataset popovers should be looking much better.

What if our JavaScript makes an Ajax request to CKAN, such as our
getTemplate() call above, and gets an error in
response? We can simulate this by changing the name of the requested template
file to one that doesn’t exist:

If you reload the datasets page after making this change, you’ll see that when
you click on a popover its contents remain Loading…. If you have a
development console open in your browser, you’ll see the error response from
CKAN each time you click to open a popover.

Our JavaScript module’s _onReceiveSnippet() function is only called if the
request gets a successful response from CKAN.
getTemplate() also accepts a second callback
function parameter that will be called when CKAN sends an error response.
Add this parameter to the getTemplate() call:

You may have noticed that, with our example code so far, if you click on the
info button of one dataset on the page then click on the info button of another
dataset, both dataset’s popovers are shown. The first popover doesn’t disappear
when the second appears, and the popovers may overlap. If you click on all the
info buttons on the page, popovers for all of them will be shown at once:

To make one popover disappear when another appears, we can use CKAN’s
publish() and
subscribe() functions. These pair of functions
allow different instances of a JavaScript module (or instances of different
JavaScript modules) on the same page to talk to each other.
The way it works is:

Modules can subscribe to events by calling
this.sandbox.client.subscribe(), passing the ‘topic’
(a string that identifies the type of event to subscribe to) and a callback
function.

Modules can call this.sandbox.client.publish() to
publish an event for all subscribed modules to receive, passing the topic
string and one or more further parameters that will be passed on as
parameters to the receiver functions.

When a module calls publish(), any callback
functions registered by previous calls to
subscribe() with the same topic string will
be called, and passed the parameters that were passed to publish.

If a module no longer wants to receive events for a topic, it calls
unsubscribe().

Remember that because we attach our example_theme_popover.js module to a
<button> element that is rendered once for each dataset on the page, CKAN
creates one instance of our module for each dataset. The only way these objects
can communicate with each other so that one object can hide its popover when
another object shows its popover, is by using pubsub.

Here’s a modified version of our example_theme_popover.js file that uses
pubsub to make the dataset popovers disappear whenever a new popover appears:

"use strict";ckan.module('example_theme_popover',function($){return{initialize:function(){$.proxyAll(this,/_on/);this.el.popover({title:this.options.title,html:true,content:this._('Loading...'),placement:'left'});this.el.on('click',this._onClick);// Subscribe to 'dataset_popover_clicked' events.// Whenever any line of code publishes an event with this topic,// our _onPopoverClicked function will be called.this.sandbox.subscribe('dataset_popover_clicked',this._onPopoverClicked);},teardown:function(){this.sandbox.unsubscribe('dataset_popover_clicked',this._onPopoverClicked);},_snippetReceived:false,_onClick:function(event){if(!this._snippetReceived){this.sandbox.client.getTemplate('example_theme_popover.html',this.options,this._onReceiveSnippet);this._snippetReceived=true;}// Publish a 'dataset_popover_clicked' event for other interested// JavaScript modules to receive. Pass the button that was clicked as a// parameter to the receiver functions.this.sandbox.publish('dataset_popover_clicked',this.el);},// This callback function is called whenever a 'dataset_popover_clicked'// event is published._onPopoverClicked:function(button){// Wrap this in an if, because we don't want this object to respond to// its own 'dataset_popover_clicked' event.if(button!=this.el){// Hide this button's popover.// (If the popover is not currently shown anyway, this does nothing).this.el.popover('hide');}},_onReceiveSnippet:function(html){this.el.popover('destroy');this.el.popover({title:this.options.title,html:true,content:html,placement:'left'});this.el.popover('show');},};});

CKAN provides a number of custom jQuery plugins for JavaScript modules to use
by default, see CKAN jQuery plugins reference.
Extensions can also add their own jQuery plugins, and the plugins will then be
available to all JavaScript code via the this.$ object.

jQuery’s own documentation on writing jQuery plugins. Read this for all
the details on writing jQuery plugins, here we’ll only provide a simple
example and show you how to integrate it with CKAN.

It’s a good idea to implement any JavaScript functionality not directly related
to CKAN as a jQuery plugin. That way your CKAN JavaScript modules will be
smaller as they’ll contain only the CKAN-specific code, and your jQuery plugins
will also be reusable on non-CKAN sites. CKAN core uses jQuery plugins to
implement features including date formatting, warning users about unsaved
changes when leaving a page containing a form without submitting the form,
restricting the set of characters that can be typed into an input field, etc.

If this JavaScript code looks a little confusing at first, it’s probably
because it’s using the
Immediately-Invoked Function Expression (IIFE)
pattern. This is a common JavaScript code pattern in which an anonymous
function is created and then immediately called once, in a single expression.
In the example above, we create an unnamed function that takes a single
parameter, jQuery, and then we call the function passing this.jQuery
to its jQuery parameter. The code inside the body of the function is the
important part. Writing jQuery plugins in this way ensures that
any variables defined inside the plugin are private to the plugin, and don’t
pollute the global namespace.

In the body of our jQuery plugin, we add a new function called greenify()
to the jQuery object:

jQuery.fn.greenify=function(){this.css("color","green");returnthis;};

jquery.fn is the jQuery prototype object, the object that normal jQuery
objects get all their methods from. By adding a method to this object, we
enable any code that has a jQuery object to call our method on any HTML element
or set of elements. For example, to turn all <a> elements on the page green
you could do: jQuery('a').greenify().

The code inside the greenify() function just calls jQuery’s standard
css() method to set the CSS color
attribute of the element to green. This is just standard jQuery code,
except that within a custom jQuery function you use this to refer to the
jQuery object, instead of using $ or jquery (as you would normally do
when calling jQuery methods from code external to jQuery).

Our method then returns this to allow jQuery method chaining to be used
with our method. For example, a user can set an element’s CSS color
attribute to green and add the CSS class greenified to the element in
a single expression by chaining our jQuery method with another method:
$('a').greenify().addClass('greenified');

Before we can use our greenify() method in CKAN, we need to import the
jquery.greenify.js file into the CKAN page. To do this, add a
{%resource%} tag to a template file, just as you would do to include any
other JavaScript or CSS file in CKAN. Edit the package_item.html file:

Now we can call the greenify() method from our example_theme_popover
JavaScript module. For example, we could add a line to the _onClick()
method in example_theme_popover.js so that when a dataset info button is
clicked it turns green:

_onClick:function(event){// Make all the links on the page turn green.this.$('i').greenify();if(!this._snippetReceived){this.sandbox.client.getTemplate('example_theme_popover.html',this.options,this._onReceiveSnippet);this._snippetReceived=true;}this.sandbox.publish('dataset_popover_clicked',this.el);},