Building a JavaScript Module

CKAN makes heavy use of modules to add additional functionality to the page. Essentially all a module consists of is an object with an .initialize() and .teardown() method.

Here we will go through the basic functionality of building a simple module that sends a “favourite” request to the server when the user clicks a button.

HTML

The idea behind modules is that the element should already be in the document when the page loads. For example our favourite button will work just fine without our module JavaScript loaded.

<form action="/favourite" method="post" data-module="favorite">
  <button class="btn" name="package" value="101">Submit</button>
</form>

Here it’s the data-module="favorite" that tells the CKAN module loader to create a new instance for this element.

JavaScript

Modules reside in the javascript/modules directory and should share the same name as the module. We use hyphens to delimit spaces in both filenames and modules.

/javascript/modules/favorite.js

A module can be created by calling ckan.module():

ckan.module('favorite', function (jQuery) {
  return {};
});

We pass in the module name and a factory function that should return our module object. This factory gets passed a local jQuery object and a translation object.

Note

In order to include a module for page render inclusion within an extension it is recommended that you use {% asset %} within your templates. See the Assets Documentation

Initialisation

Once ckan has found an element on the page it creates a new instance of your module and if present calls the .initialize() method.

ckan.module('favorite', function (jQuery) {
  return {
    initialize: function () {
      console.log('I've been called for element: %o', this.el);
    }
  };
});

Here we can set up event listeners and other setup functions.

initialize: function () {
  // Grab our button and assign it to a property of our module.
  this.button = this.$('button');

  // Watch for our favourite button to be clicked.
  this.button.on('submit', jQuery.proxy(this._onClick, this));
},
_onClick: function (event) {}

Event Handling

Now we create our click handler for the button:

_onClick: function (event) {
  event.preventDefault();
  this.favorite();
}

And this calls a .favorite() method. It’s generally best not to do too much in event handlers it means that you can’t use the same functionality elsewhere.

favorite: function () {
  // The client on the sandbox should always be used to talk to the api.
  this.sandbox.client.favoriteDataset(this.button.val());
}

Internationalisation

See Internationalizing strings in JavaScript code.

Notifications

This submits the dataset to the API but ideally we want to tell the user what we’re doing.

favorite: function () {
  this.button.text('Loading');

  // The client on the sandbox should always be used to talk to the api.
  var request = this.sandbox.client.favoriteDataset(this.button.val())
  request.done(jQuery.proxy(this._onSuccess, this));
},
_onSuccess: function () {
  // Notify allows global messages to be displayed to the user.
  this.sandbox.notify('Done', 'success');
}

Options

Displaying an id to the user isn’t very friendly. We can use the data-module attributes to pass options through to the module.

<form action="/favourite" method="post" data-module="favorite" data-module-dataset="my dataset">

This will override the defaults in the options object.

ckan.module('favorite', function (jQuery) {
  return {
    options: {
      dataset: ''
    }
    initialize: function () {
      console.log('this dataset is: %s', this.options.dataset);
      //=> "this dataset is: my dataset"
    }
  };
});

Error handling

When ever we make an Ajax request we want to make sure that we notify the user if the request fails. Again we can use this.sandbox.notify() to do this.

favorite: function () {
  // The client on the sandbox should always be used to talk to the api.
  var request = this.sandbox.client.favoriteDataset(this.button.val())
  request.done(jQuery.proxy(this._onSuccess, this));
  request.fail(jQuery.proxy(this._onError, this));
},
_onError: function () {
  // Notify allows global messages to be displayed to the user.
  this.sandbox.notify('An error occurred!', 'error');
}

Module Scope

You may have noticed we keep making calls to jQuery.proxy() within these methods. This is to ensure that this when the callback is called is the module it belongs to.

We have a shortcut method called jQuery.proxyAll() that can be used in the .initialize() method to do all the binding at once. It can accept method names or simply a regexp.

initialize: function () {
  jQuery.proxyAll(this, '_onSuccess');

  // Same as:
  this._onSuccess = jQuery.proxy(this, '_onSuccess');

  // Even better do all methods starting with _on at once.
  jQuery.proxyAll(this, /_on/);
}

Publish/Subscribe

Sometimes we want modules to be able to talk to each other in order to keep the page state up to date. The sandbox has the .publish() and .subscribe() methods for just this cause.

For example say we had a counter up in the header that showed how many favourite datasets the user had. This would be incorrect when the user clicked the ajax button. We can publish an event when the favorite button is successful.

_onSuccess: function () {
  // Notify allows global messages to be displayed to the user.
  this.sandbox.notify(message, 'success');

  // Tell other modules about this event.
  this.sandbox.publish('favorite', this.button.val());
}

Now in our other module ‘user-favorite-counter’ we can listen for this.

ckan.module('user-favorite-counter', function (jQuery) {
  return {
    initialize: function () {
      jQuery.proxyAll(this, /_on/);
      this.sandbox.subscribe('favorite', this._onFavorite);
    },
    teardown: function () {
      // We must always unsubscribe on teardown to prevent memory leaks.
      this.sandbox.unsubscribe('favorite', this._onFavorite);
    },
    incrementCounter: function () {
      var count = this.el.text() + 1;
      this.el.text(count);
    },
    _onFavorite: function (id) {
      this.incrementCounter();
    }
  };
});

Unit Tests

Every module has unit tests. These use Cypress to assert the expected functionality of the module.