In-Depth

Using Knockout Custom Binding Handlers

Knockout custom binding handlers can help simplify integration with third-party JavaScript libraries. Here's how.

• By Patrick Steele
• 04/30/2014

A few months ago, I wrote an article on using the JavaScript library Knockout. One thing I didn't cover was custom bindings. This is a feature of Knockout that can make integrating with other JavaScript libraries a breeze.

Knockout Bindings
Knockout comes loaded with bindings to handle all sorts of things:

• Text and appearance ("text," "visible," "css" and so on)
• Control flow ("foreach," "if" and so on)
• Form fields ("value," "options," "checked" and so on)
• Events ("click," "hasFocus" and so on)

But sometimes that isn't enough. Sometimes, I've got a third-party JavaScript library with which I need to integrate. Since using Knockout, I've become spoiled and I no longer write a lot of code to manually update controls and register event handlers. When I move away from the standard HTML controls and start using third-party libraries, I'm back to writing UI update code again. Yuck! That's where writing custom binding handlers comes in. I can tell Knockout how to bind my view model to these other libraries.

Google Charts
You might not be aware, but Google has a really nice set of Visualization APIs for creating charts available to Web developers. It's a very easy way to add some simple (as well as not-so-simple) charts and graphs to your Web application. For this sample, I'm going to use some gauges to display the current time (hours, minutes and seconds), as shown in Figure 1.

I'm going to start off by doing this manually with straight JavaScript. Then I'll refactor into a custom Knockout binding for easier reuse and better separation of my presentation and logic.

Initializing the Google Visualization API starts with loading the necessary packages. I'm only using the gauges, so I only need to load the "gauge" package:

<script type='text/javascript' src='https://www.google.com/jsapi'></script>
<script type="text/javascript">
  google.load('visualization', '1', {packages:['gauge']});
</script>

Google charts are rendered in a standard <div> tag. The API will use the most optimal method for rendering based on the browser. More modern HTML5-enabled browsers will use SVG, while older IE browsers will use VML. I just define the <div> tags and let the Visualization API do the hard work:

<div id="hours"></div>
<div id="minutes"></div>
<div id="seconds"></div>

Using the jQuery document.ready handler, I'll create the three gauges for each of the <div> tags:

hourChart = new google.visualization.Gauge($('#hours')[0]);
minuteChart = new google.visualization.Gauge($('#minutes')[0]);
secondChart = new google.visualization.Gauge($('#seconds')[0]);

I also initialized some options to be used when rendering each gauge. They should be self-explanatory (Note: See the Google Visualization API documentation for a complete set of options):

var hourOptions = { min: 0, max: 23, width: 200, height: 200 };
var minuteOptions = { min: 0, max: 59, width: 200, height: 200 };
var secondOptions = {min: 0, max: 59, width: 200, height: 200, animation: { duration: 0 } };

Note that I set the animation.duration value to zero for the seconds gauge. By default, the charts have a nice, smooth animation to them as their values are updated. For something that represents a ticking seconds hand, I wanted it to have a nice "snap." By setting the animation duration to zero, the gauge updates immediately.

Now I need to get this running in a continuous loop that will update every second (I'll cover the 'updateCharts' function later):

loop();

function loop() {
  updateCharts();
  window.setTimeout(loop, 1000);
}

The Visualization API defines a DataTable to hold the data used for many of its charts. There are different ways to construct a DataTable; for this example, I've used the utility method arrayToDataTable. This takes an array of arrays and creates a row/column-based DataTable. Because I need to create a DataTable for each gauge (hour, minute, second), I create a utility method for generating a DataTable:

function createDataTable(caption, value) {
  return google.visualization.arrayToDataTable([
    ['Label', 'Value'],
    [caption, value]
  ]);
}

Finally, it's time to put all of this together and display my gauges:

function updateCharts() {
  var d = new Date();

  hourChart.draw(createDataTable(
    'Hours', d.getHours()), hourOptions);
  minuteChart.draw(createDataTable(
    'Minutes', d.getMinutes()), minuteOptions);
  secondChart.draw(createDataTable(
    'Seconds', d.getSeconds()), secondOptions);
}

As you can see, this isn't terribly difficult, but there's a lot of code to write, considering I just want to display three gauges, each with a single value. What I would prefer is to simply have three Knockout observables and bind them directly to a <div> that will render as a gauge.

Knockout Custom Bindings
Writing a custom binding is pretty straightforward. All I have to do is add a subproperty to ko.bindingHandlers:

ko.bindingHandlers.myCustomBindingName = {
  init: function(…),
  update: function(…)
};

Note that there are only two calls to handle:

1. init: This is called when the biding is first applied to a DOM element. This is where you would perform one-time initialization such as registering an event handler to update your observable when the DOM element changes.
2. update: This is called once when the binding is first applied, and again whenever your observable changes and the DOM element needs to be updated.

Some binding handlers may only need one or the other (you don't have to implement both). For example, if I was creating a binding for a read-only control, I'd only need to handle the update callback and change the control whenever my observable changed.

My gauge binding will need to handle both the init and the update callbacks. Here's the signature for the init callback:

init: function (element, valueAccessor, allBindings, viewModel, bindingContext) { }

• element: This is the actual DOM element that the data-bind attribute has been defined on. With this being passed directly to my custom binding handler, I don't need to do a jQuery lookup based on some id.
• valueAccessor: This represents a JavaScript function that can be used to access the current property or expression involved in this binding. Because Knockout allows you to use either a view model property directly (such as "data-bind='enabled: isEnabled'"), or an expression (such as "data-bind='enabled: firstName.length > 0'"), there's a utility function that will "unwrap" and give you the actual value used in the binding. Incidentally, this function is called "ko.unwrap."
• allBindings: This JavaScript object contains all other model values bound to this element. For example, the value binding allows you to define a valueUpdate option, which will determine when the value update is performed:

  data-bind="value: firstName, valueUpdate: 'afterkeydown'"

In the previous sample, allBindings.get('valueUpdate') will return the value 'afterkeydown.'

• viewModel: This is an old parameter from pre-Knockout 3.x. The data for this value is now exposed as a property on the bindingContext parameter.
• bindingContext: This object defines the context under which binding is currently available for the DOM element. This object also includes special properties such as "$parent" and "$root" that can be used to access data bound against the ancestors of the bindingContext.

For convenience, the parameters for the update callback contain the same set of parameters. Once you're familiar with one, you're familiar with both!

I'm going to start by writing my data-bind attribute and then creating the custom binding to support that:

<div data-bind="gauge: hour, caption: 'Hour', gaugeOptions: { min: 0, max: 23 }" ></div>

Only three binding values:

1. gauge: This binds to the observable that defines the value for the gauge.
2. caption: The caption to be displayed on the gauge.
3. gaugeOptions: The gauge options passed directly into the Visualization API.

Adding this to Knockout is simply a matter of adding a gauge property to ko.bindingHandlers:

ko.bindingHandlers.gauge = {
  init: function(…) {},
  update: function(…) {}
};

On to the binding!

The Init Callback
Handling the init callback is pretty simple, except that I need to create a chart object and hold on to that reference for the update callback so I can draw on it. Luckily, Knockout includes a utility function to store and retrieve data on the element. This allows me to create the chart and save it with the <div> tag to which I'm binding:

init: function (element, valueAccessor, allBindings, viewModel, bindingContext) {
  var chart = new google.visualization.Gauge(element);
  ko.utils.domData.set(element, 'chart', chart);
}

That's all I need to do to initialize my binding.

The Update Callback
My update code will handle getting the updated model value and re-drawing the gauge. I start with grabbing the value to bind, as well as the caption. If no caption was defined on the binding, I default to Caption:

update: function (element, valueAccessor, allBindings, viewModel, bindingContext) {
  var value = ko.unwrap(valueAccessor());
  var caption = allBindings.get('caption') || 'Caption';
}

Note how I use the ko.unwrap utility method to get the actual value of whatever is bound to my gauge binding.

When it comes to the gaugeOptions value, I want to have a default width and height. The Visualization API has documented defaults, but I found a small quirk: if I don't define a width and height explicitly, my gauge seems to shrink a little on each redraw. I didn't dig in to see if this was an issue in my code or a bug in the API, but providing a set width and height fixed the issue, so I defined a default of 200 for width and height inside my binding:

var options = allBindings.get('gaugeOptions') || {};
options.width = options.width || 200;
options.height = options.height || 200;

Notice that I don't assume a gaugeOptions was passed in, and I don't overwrite a width or height value if it's provided.

Now I just need to build the DataTable with the caption and the value:

var data = google.visualization.arrayToDataTable([
  ['Label', 'Value'],
  [caption, value]
]);

Finally, it's time to draw the chart. I grab the chart object that I created during the init and update it with new data:

var chart = ko.utils.domData.get(element, 'chart');
chart.draw(data, options);

The complete update callback is shown in Listing 1.

update: function (element, valueAccessor, allBindings, viewModel, bindingContext) {
  var value = ko.unwrap(valueAccessor());
  var caption = allBindings.get('caption') || 'Caption';

  var options = allBindings.get('gaugeOptions') || {};
  options.width = options.width || 200;
  options.height = options.height || 200;

  var data = google.visualization.arrayToDataTable([
    ['Label', 'Value'],
    [caption, value]
  ]);
  var chart = ko.utils.domData.get(element, 'chart');
  chart.draw(data, options);
}

Using the Gauge Binding
I start refactoring my original example by moving the logic of what I want to do into a simple view model, as shown in Listing 2. It's very simple, clean and easy to understand.

function GaugeViewModel() {
  var me = this;

  me.hour = ko.observable(0);
  me.minute = ko.observable(0);
  me.second = ko.observable(0);

  me.update = function() {
    var d = me.getDate();
    me.hour(d.getHours());
    me.minute(d.getMinutes());
    me.second(d.getSeconds());
  };

  me.loop = function() {
    window.setTimeout(function() {
      me.update();
      me.loop();
    }, 1000);
  };

  me.update();
}

GaugeViewModel.prototype.getDate = function() {
  return new Date();
};

I can also write some Jasmine specs to make sure my update function actually updates my observables properly (that's why I added getDate to the prototype -- it allows me to mock it out with Jasmine by spying on GaugeViewModel.prototype!).

I'll still need to load the Visualization APIs (and add a reference to the knockout library), but my document.ready handler is greatly simplified:

$(function() {
  var vm = new GaugeViewModel();
  ko.applyBindings(vm);
  vm.loop();
});

Finally, here's my HTML to display the gauges:

<div data-bind="gauge: hour, caption: 'Hour', gaugeOptions: { min: 0, max: 23 }" ></div>
<div data-bind="gauge: minute, caption: 'Minute', gaugeOptions: { min: 0, max: 59 }" ></div>
<div data-bind="gauge: second, caption: 'Seconds', gaugeOptions: { min: 0, max: 59, 
  animation: { duration: 0 } }" ></div>

• Get Code Download