Knock Me Out

Working with AMD modules in Knockout.js

2013-05-01T22:35:00-05:00

After being a bit resistant at first, I have happily moved to using require.js to manage dependencies in most of the Knockout.js applications that I have written in the last year or so. With each application, I have tried a number of patterns to make it easier to work with AMD (Asynchronous Module Definition) modules. Recently, I decided to formalize some of these patterns into a lightweight plugin that makes it simple to bind against modules and pull in templates that live in external files.

The result is this library: knockout-amd-helpers

Why require.js and AMD modules

Breaking an application down into small, decoupled modules is a pattern that works well when done right. Creating modules in JavaScript is often accomplished by using various namespacing patterns. As an application grows though, it is easy to lose sight of the individual dependencies of each module and eventually maintaining the order that all of your scripts need to be loaded in becomes a burden as well. AMD module loaders can help with these issues.

There are plenty of good resources that help explain require.js, dependency management, and AMD modules. Here are a few good ones:

The require.js documentation on AMD modules.
Our documentation on using Knockout with require.js.
My co-worker Jonathan Creamer’s tutorial on using Knockout.js in large-scale applications. He also recently did a presentation for dotnetConf that can be found here on using require.js and using it with ASP.NET MVC.
While require.js is the most mentioned option in this category, there are others including the excellent curl.js.

A few pain points

When developing Knockout applications using require.js, there are a couple of situations that out-of-the-box still seemed less than perfect to me.

1- After breaking down your application into specific modules, it is unfortunate to have to include all of your markup on a single page. There are server-side solutions to pull in partials for your templates, but that still results in a page that contains all of your markup from the start. These is also the external template engine, which works well, but is not designed to leverage the capabilities of the AMD loader libraries.

2- Dynamically requesting and binding against modules is not trivial. Normally, you would build a main “App” view model that contains all of the sub-modules that you want to bind against. It would be nice though to be able to dynamically pull in modules or use modules as reusable components in an app under any context.

Looking at potential solutions

Based on some of the different approaches that I have used in the past, I created the knockout-amd-helpers plugin to hopefully help ease these issues.

An AMD compatible template engine

The first feature of the plugin is to use one of Knockout’s extensibility points to replace the default template engine with one that is able to load named templates using the AMD loader’s text plugin.

I used the template sources extensibility point that I discussed here. When a named template is requested, it first checks to see if there is a script tag with the specified id (the default engine actually will grab any element with that id) and if not uses the text plugin to require the template. This will asynchronously load the template (unless it has already been loaded or is bundled and already available on the client). The template source uses an observable that triggers the template binding to update when the template is available.

For example, when using a binding like:

    <ul data-bind="template: { name: 'itemView', foreach: items }"></ul>

If there is no script tag with an id of itemView, it will attempt to load the template. The engine uses a default path of templates and a default suffix of .tmpl.html. So, it would look for the template at templates/itemView.tmpl.html. The default path and suffix can be configured and you can also pass a more specific path in for the name (sub/path/itemView).

A module binding

This updated template engine now helps keep your templates as modular as your view models, but it still would be nice to easily pull modules into an application without using a top-level view model that needs to contain everything that you might want to bind against.

To help with this situation, the plugin includes a module binding, which offers a flexible way to dynamically pull a module into your markup. Here is a basic example:

    <nav data-bind="module: 'navigation'"></div>

This will require a navigation module (the base directory can be configured as well). If the main element had children, then it would use them as an inline/anonymous template. However, in this case, since the element does not have children, it will use navigation as the template name and follow the template engine’s rules for pulling in the template.

After the loading the module it will follow a few rules for deciding what data to bind against:

If the module returns a function, then it will create a new instance
If the module returns an object, then it will, by default, call an initialize function on the object (if it exists) and either use the result of the function or the original object if there is not a return value.

This gives you the flexibility of either constructing a new object, using an existing object, or calling a function that returns some object to bind against.

The module binding has a number of options that you can pass in as well. Here is an example passing all of the options:

    <div data-bind="module: { name: 'one', data: initialData, template: 'oneTmpl',
                              initializer: 'createItem', afterRender: myCallback }"></div>

These options let you do things like customize the template to use, specify data to pass into the constructor or initializer, define the name of the function to call, and pass an afterRender function through to the template binding.

With this binding, it is possible to call ko.applyBindings({}) and build your application strictly using the module binding. A module binding can be nested inside other module bindings and you can also use observables to dynamically specify your module.

Communicating between modules

When building an app using this structure, it would be less than ideal to rely on $root or $parent calls within the markup to communicate between modules. This can potentially couple your module to only working within a certain context. While this can certanily work, a better solution may be to use some type of messaging to communicate between the modules.

I have a library called knockout-postbox that adds a ko.postbox object and some observable extensions that make it easy to publish values on a topic and update an observable based on a subscription to a topic.

For example, in a module that defines the main content, you could have an observable like:

   this.sectionName = ko.observable().subscribeTo("navigation.current");

Then, in the navigation module, publish on that topic like:

   this.selectedNavItem = ko.observable().publishOn("navigation.current");

The postbox library supports a number of options that control how the publish/subscribe process works, but if you are looking for a stand-alone library that supports a number of additional features (channels, wildcards, envelopes), then I would recommend postal.js

Summary

If you are using AMD modules in your Knockout application and are looking for a lightweight and simple, but flexible way to bind against templates and modules, then check out this new library. It has been tested with both require.js and curl.js. I would be happy to help support any other AMD loaders, if there is interest. Please check out the README on the repository for additional documentation. I also plan to work on a better example, as time permits.

Joining appendTo

2013-03-28T09:35:00-05:00

Just a quick note that I joined appendTo as a senior JavaScript engineer at the beginning of March. I am really excited to work with a great group of talented people and to get a chance to work on a wide variety of web development projects. I am especially eager to use some new technologies/libraries to solve real problems and can’t wait to gain new perspectives on ways to improve or build on top of Knockout.

If you are looking for help with a significant Knockout project (or any other front-end technology), then I would encourage you to contact appendTo and maybe we could have the chance to work together. For general KO questions or if you are looking for help on a project that only requires a small time investment, feel free to contact me directly.

Tekpub Refactoring Knockout.js Screencast

2013-02-21T20:35:00-06:00

Recently, I had the chance to do some pair programming with Rob Conery to refactor a Knockout-based shopping cart for a Tekpub full throttle video. Rob has had a love/hate relationship with Knockout over the years and I have had several discussions with him in the past trying to work through some of his concerns.

He recently asked me to take a look at a Knockout-based shopping cart that he had written for another video. The code was working just fine, but as I dug into it, I started jotting down a LOT of notes. I ended up formatting them in markdown and sent them Rob’s way. He thought that it would be a good idea to record a screencast to really dig into those notes.

Here is a trailer for the screencast:

I personally have had a Tekpub subscription for around two years and definitely recommend the service. They are really putting out some great content lately and have a well-done Knockout series.

Update: here is a link to the notes that I sent Rob.

A Simple Editor Pattern for Knockout.js

2013-01-28T20:35:00-06:00

Implementing an editor that allows users to accept or cancel their changes is a common task in Knockout.js. Previously, I suggested the idea of a protectedObservable that is an extended observable with the ability to commit and reset the value being edited. Since Knockout 2.0, I would probably now implement that functionality using either extenders or by augmenting the .fn object of the core types. However, I now use a different pattern.

I described this pattern in the Twin Cities Code Camp presentation here. This technique allows you to easily copy, commit, and revert changes to an entire model. There are two rules that make this pattern work:

The creation of observables and computeds needs to be separate from actually populating them with values.
The format of the data that you put in should be the same as the format that you are able to get out. Typically this means that calling ko.toJS on your model should result in an object that you could send back through the function described in step 1 to re-populate the values.

Separate creation and initialization

The idea is that we can apply fresh data to our object at anytime, so our constructor function should just create our structure, while a separate method handles setting the values.

    var Item = function(data) {
        this.name = ko.observable();
        this.price = ko.observable();

        this.update(data);
    };

    Item.prototype.update = function(data) {
        this.name(data.name || "new item");
        this.price(data.price || 0);
    };

Our update function (call it whatever you like init, initialize, hydrate, etc.), needs to handle populating the values of all of the observables given a plain JavaScript object. It can also handle supplying default values.

Data in matches data out

To make this pattern work, we need to be able to put a plain JavaScript object in and get the equivalent object out. Ideally, simply calling ko.toJS on our model, will give us the plain object that we need. It is okay, if there are some additional computeds/properties on the object, but it needs to be appropriate for sending through the update function again.

A technique that I use frequently to “hide” data that I won’t want when I turn the model into a plain JavaScript object or to JSON is to use a “sub-observable”. So, if we had a computed observable to show a formatted version of the price that we don’t want in our output, we could specify it like:

    var Item = function(data) {
        this.name = ko.observable();
        this.price = ko.observable();
        this.price.formatted = ko.computed(this.getFormattedPrice, this);

        this.update(data);
    };

Since observables are functions and functions are objects that can have their own properties, it is perfectly valid to create a formatted computed off of the price observable. In the markup, we can bind against price.formatted. However, when calling ko.toJS or ko.toJSON, the formatted sub-observable will disappear, as we will simply be left with a price property and value.

Reverting changes

Now that we have these pieces in place, it is easy to create an editor that allows reverting changes. In the event that a user chooses to cancel their editing, all we need to do is send the original data back through our update function and we will be back to where we started.

We will need to track the original data, so that it is available to repopulate the model. A good place to cache this data is in the update function itself. It is useful to make sure that the data is “hidden” as well, so multiple edits don’t result in recursive versions of the old data being kept around. If we were not using the prototype, then we could just use a local variable to store the data, but since we are placing our shared functions on the prototype in these samples, we need to find another way to hide this data. A simple solution is to create an empty cache function and store our data as property off of it. This will prevent calls to ko.toJS or ko.toJSON from capturing this data.

    var Item = function(data) {
        this.name = ko.observable();
        this.price = ko.observable();
        this.cache = function() {};

        this.update(data);
    };

    ko.utils.extend(Item.prototype, {
      update: function(data) {
        this.name(data.name || "new item");
        this.price(data.price || 0);

        //save off the latest data for later use
        this.cache.latestData = data;
      },
      revert: function() {
        this.update(this.cache.latestData);
      }
    });

In this scenario, we will let edits persist to our observables and in the event that a user chooses to cancel, we will refresh our model with the original data.

Committing changes

When a user accepts the data, we need to make sure that we update the cached data with the current state of the model. For example, we could simply add a commit or accept function to our prototype that does:

    commit: function() {
        this.cache.latestData = ko.toJS(this);
    }

We now have the latest data cached, so the next time that a user cancels it will be reverted back to this updated state.

Copying/cloning

Sometimes in an editor, we would not want the currently edited observables to affect the rest of the UI until the user chooses to accept the changes. In this case, we can use these same methods to create a copy of the item for editing and then apply it back to the original. Here is how our overall view model might look:

    var ViewModel = function(items) {
        //turn the raw items into Item objects
        this.items = ko.observableArray(ko.utils.arrayMap(items, function(data) {
            return new Item(data);
        });

        //hold the real currently selected item
        this.selectedItem = ko.observable();

        //make edits to a copy
        this.itemForEditing = ko.observable();
    };

    ko.utils.extend(ViewModel.prototype, {
        //select and item and make a copy of it for editing
        selectItem: function(item) {
            this.selectedItem(item);
            this.itemForEditing(new Item(ko.toJS(item)));
        },

        acceptItem: function(item) {
            var selected = this.selectedItem(),
                edited = ko.toJS(this.itemForEditing()); //clean copy of edited

            //apply updates from the edited item to the selected item
            selected.update(edited);

            //clear selected item
            this.selectedItem(null);
            this.itemForEditing(null);
        },

        //just throw away the edited item and clear the selected observables
        revertItem: function() {
            this.selectedItem(null);
            this.itemForEditing(null);
        }
    });

So, we make edits to a copy of the original and on an accept we apply those edits back to the original. We can use ko.toJS to get a plain JavaScript object and feed it into our update function to apply the changes. In this scenario, the revertItem function can simply throw away the copied item and clear our the selected value.

Link to sample on jsFiddle.net

If you were going to reuse this technique often, then you could even create an extension to an observableArray that adds the appropriate observables and functions off of the observableArray itself like in this sample.

Updating from server

Our update function is also a handy way to apply updates from the server to our existing view model. In our case, we would likely need to add an id to the Item objects, so that we can identify which object needs updating. This works very well with something like SignalR or socket.io to keep various clients in sync with each other. This is an easier pattern than trying to swap items in an array or update specific properties one by one.

Summary

Editors with accept/cancel options are a common scenario in a Knockout.js application. By separating the creation of observables/computeds from poplating their values, we can commit, reset, and update models by feeding a version of the data through our update function. When you think in terms of the plain JS object that you can get out of or put into a model, it makes many of these scenarios easy to handle.

Revisting Event Delegation in Knockout.js

2012-11-19T20:35:00-06:00

Previously, I discussed a technique to do event delegation in Knockout.js. That post was created before Knockout 2.0, which added the ability to use ko.dataFor and ko.contextFor to retrieve the data context related to a specific element (as described here). With these new tools, there are now much better ways to add a single handler on a parent element that can respond to events triggered on its child elements.

Note: based on the techniques in this post, I created a plugin called knockout-delegatedEvents located here: https://github.com/rniemeyer/knockout-delegatedEvents.

Why event delegation in Knockout.js?

Currently when you use the click or event binding in Knockout, an event handler is attached directly to that element. Generally this is fine and causes no real problems. However, if you face a scenario where you have a large number of elements that require these bindings, then there can be a performance impact to creating and attaching these handlers to each element, especially in older browsers. For example, you may be creating a grid where each cell needs various event handlers or a hierarchical editor where you are potentially attaching handlers to interact with the parent items as well as each child (and each child may have children).

In this case, there are advantages to using event delegation:

you only have to attach one (or a few) event handlers rather than one on each element. Events bubble up to the higher-level handler and can understand the original element that triggered it.
dynamically added content does not need new event handlers added to them (largely not an issue with KO bindings and templating)

Normal event delegation with KO 2.0+

With Knockout 2.0+, the common way to use event delegation is to avoid attaching event handlers in the bindings themselves and add another layer of code to attach a single handler to a parent element using something like jQuery’s on (previously live/delegate). So, rather than doing:

<ul data-bind="foreach: items">
    <li>
        <a href="#" data-bind="click: $root.selectItem, text: name"></a>
    </li>
</ul>

You would instead do:

<ul id="items" data-bind="foreach: items">
    <li>
        <a href="#" data-bind="text: name"></a>
    </li>
</ul>

and attach an event handler elsewhere like:

$("#items").on("click", "a", function() {
    var context = ko.contextFor(this); //this is the element that was clicked
    if (context) {
        context.$root.selectItem(context.$data);
    }
});

Attaching a single handler like this works quite well. However, there are a few issues that I still have with this technique:

you have another layer of code to manage besides your view model. This is the type of code that Knockout generally helps you get away from.
this code is tightly coupled (fairly) with this view’s markup
in our example, if the entire ul is part of a template that gets swapped, then we would need to hook up our handler again or choose to add our handler at a higher level (possibly up to the body)
this particular code also adds a dependency on jQuery that is not really necessary

In my perfect Knockout application, you have your view and your view model with the only code outside of that being a call to ko.applyBindings. To accomplish this, we would need to be able to wire it up declaratively in the view. I have been exploring a few ways to make this happen.

Declaratively adding a handler

The first step is attaching a handler on the parent or root element that will respond when events bubble up to it. This is pretty easy to accomplish with a custom binding. When the event is handled, we can determine the original element and use ko.dataFor or ko.contextFor to get the original data context and then execute some method.

//add a handler on a parent element that reponds to events from the children
ko.bindingHandlers.delegatedHandler = {
    init: function(element, valueAccessor) {
        //array of events
        var events = ko.utils.unwrapObservable(valueAccessor()) || [];
        ko.utils.arrayForEach(events, function(event) {
            ko.utils.registerEventHandler(element, event, createDelegatedHandler(event, element));
        });
    }
};

To create the handler, we take the target element and get its context:

//create a handler for a specific event like "click"
var createDelegatedHandler = function(eventName, root) {
    //return a handler
    return function(event) {
        var el = event.target,
            data = ko.dataFor(el),
            action = findAnAction(el, context); //??? how do we know what method to call


        //execute the action
        if (action) {
            //call it like KO normally would with the data being both the value of `this` and the first arg
            result = action.call(data, data, event);

            //prevent the default action, unless the function returns true
            if (result !== true) {
                if (event.preventDefault) {
                    event.preventDefault();
                }
                else {
                    event.returnValue = false;
                }
            }
        }
    };
};

When used on an element, the binding would take in an array of events like:

<ul data-bind="delegatedHandler: ['click', 'mouseover', 'mousedown']">
...
</ul>

With this binding in place, we can handle the event, find the element that triggered the event, and determine the data context of the element. However, we still need to know what method to call. I looked at a few alternatives for this piece.

Option #1 - using a binding

On the child elements, we could use a binding that stores a reference to the function to call. The binding can use Knockout’s ko.utils.domData functions to store and retrieve data on the element, as Knockout automatically cleans up this data whenever it removes elements from the document. For example, we could create a delegatedClick binding to make this association.

//associate a handler with an element that will be executed by the delegatedHandler
ko.bindingHandlers.delegatedClick = {
    init: function(element, valueAccessor) {
        var action = valueAccessor();
        ko.utils.domData.set(element, "ko_delegated_click", action);
    }
};

Now, on a child element, you would associate a function like:

<li>
    <a href="#" data-bind="text: name, delegatedClick: $parent.selectItem"></a>
</li>

We could create additional bindings for other events that we are interested in and could even create a helper function to generate these bindings given an array of events that we need to handle.

Pros

Can simply replace click bindings with delegatedClick (and other events) without any other changes
Can bind against specific functions and can execute code for cases where you need to call a function with a parameter to create a handler (delegatedClick: $parent.createHandler('some_modifier'))

Cons

The binding on the child elements is lightweight, but we still have to pay the overhead of parsing and executing a binding.

Option #2 - use a `data-` attribute with method name

The first solution works well, but I still do not like having to pay the price of executing bindings on the child elements. For an alternative solution, I looked at a different approach where the child elements are tagged with a data-eventName attribute that contains the method name.

<li>
    <a href="#" data-click="selectItem" data-bind="text: name"></a>
</li>

With this technique we would no longer need the child bindings. In the event handling code, we would now need to locate a method that matches our data-eventName attribute value. This time we can use ko.contextFor to get back the entire binding context. It is very common to call functions off of $parent or $root as well as off of the current data itself, so the $parents array allows us to walk up the scope chain to locate an appropriate method.

Pros

No overhead of executing a binding on the child elements
Can execute the function with the correct owner, so we do not need to use .bind or var self = this; to ensure that the context is correct. This is a really nice benefit, we have to search for the method in each scope, so we know the appropriate owner of the method to use as the context.

Cons

could run into issues with clashing names (child has an add method, but you wanted to call parent’s add)
cannot execute code to create a handler, as the attribute value would be a string that needs to match a method name

Option #3 - associate method and name in root/global object

Another alternative might be to use the data- attribute, but use the string to key into an object that holds the associations between names and actions. Perhaps something like ko.actions or ko.commands. This object could hold just function references or maybe a function and owner. For arrays of objects, we would not be able to indicate an appropriate owner, so we would have to fall back to making sure that the function is properly bound on each instance. For example, we could even give the function an alias of select like:

ko.actions.select = {
    action: this.selectItem,
    owner: this
};

Pros

No overhead of executing a binding on the child elements
No issues with ambiguity in names, as names can be aliased
Functions outside of a view model could be included
Could dynamically change the definition of the action

Cons

have to manage adding (and maybe removing) functions to this object
different types of objects with the same method names would have to be aliased with unique names in this object

Summary

In cases where you need to attach a large number of event handlers, using event delegation can be a nice win. Attaching these handlers declaratively provides an alternative to wiring this up outside of your view/viewmodel. While considering each of the techniques to determine the function to execute, I was leaning towards #2, as it does not require the child bindings and as a bonus gets the context right when it calls the handler. Instead though, I decided to create a plugin that can use all of these techniques interchangeably. The plugin lives at: http://github.com/rniemeyer/knockout-delegatedEvents. Please let me know if you have feedback or suggestions for the plugin.

Knockout.js 2.2 is out now!

2012-10-29T20:35:00-05:00

Just a quick note that Knockout 2.2 is now available. You can read more about the details of this release in the announcement or Steve Sanderson’s blog post.

Here are a few of my favorite changes:

The css binding can either toggle specific classes on and off like (css: { error: hasError, required: isRequired }) or now add one or more classes dynamically like css: someClassOrClasses. This is handy when the class names are dynamic. Previously, you could do something similar with the attr binding against the class attribute, but it would overwrite the class attribute completely. When using the css binding in this way, it will now preserve existing classes and will properly remove any class or classes that were previously added by the binding when the value changes.
The if and ifnot bindings now only re-render their contents when the bound value changes between truthy and falsy. This helps to alleviate the performance issue described in the first half of this post.
There is a new peek function available on observables and computed observables. This allows you to retrieve its value without creating a dependency. This definitely can be useful when you want tight control over when bindings and other subscriptions are triggered, but I would use caution as it does circumvent the normal dependency tracking mechanism. If you find that you need this functionality, then you probably have a good reason why you don’t want a dependency and would understand what does and doesn’t trigger updates.
The foreach binding and the foreach option of the template binding now try to understand if items have been moved and will relocate the content rather than tearing it down and re-rendering it at its new position. This comes with some new callbacks (beforeMove and afterMove).
The ko variable is now available from within bindings, even if ko is not a global variable (common in AMD scenarios).

You can download the 2.2 files from here. There were no intentional breaking changes made in 2.2 (unless someone was relying on an existing bug), so if you have any issues with your application not behaving as it did in 2.1, please log an issue here.

Getting the Most Out of Knockout.js Session From Twin Cities Code Camp

2012-10-09T20:35:00-05:00

Last weekend, I was invited to talk about Knockout.js at Twin Cities Code Camp. It was a very enjoyable day, as I saw several great presentations and had a chance to talk to many Knockout users.

I was told that there had been several sessions in the past that touched on Knockout, so for this talk I decided to focus on some tips, tricks, and techniques that can be used to get the most out of Knockout. The topics covered included:

Brief introduction to Knockout
Getting data in and out
Extending Knockout’s structures
Custom Bindings
Performance tips

There was a small amount of overlap with the session that I did at ThatConference in August, but all of the samples were new for this talk. The project that I used to give the presentation is also described in the ThatConference post and a reference project lives here.

Here is a screencast of the presentation:

Getting the Most Out of Knockout.js - 10/06/2012 - Twin Cities Code Camp

A few clarifications from the presentation:

At the end of the “getting data out” part, I had typed var meta instead of this.meta.
In the maxLength extender, I used a writeable computed observable. In the write function, I should have written the new value to our observable (original(newValue);), in addition to checking its length.
In the enterKey custom binding, you probably would want to return the result of the actual function call, as when you return true from a handler called by the event binding, it will allow the default action to proceed, which can be useful at times.
In the modal binding where we add a handler for the hidden event, you may want to check if what you are dealing with can be written to as an observable (is an observable or writeable computed observable) by calling ko.isWriteableObservable. So, we might want to call ko.isWriteableObservable(data) before doing data(null).
In the modal binding, the wrappers to the with binding, should really be written with with quoted like return ko.bindingHandlers['with'].init.apply(this, arguments); and return ko.bindingHandlers['with'].update.apply(this, arguments);. In IE < 9 the use of with as a property name will cause an error, as it is a JavaScript keyword.

Participating in the code camp was definitely worth the effort of traveling up to the Twin Cities. I would be happy to hear any type of feedback on the presentation. Photo by @JudahGabriel.

Extending Knockout.js Session From ThatConference

2012-08-15T20:35:00-05:00

I had a wonderful time at ThatConference this week. It was really special to be in a place with so many people that are passionate about the same types of things that I am. I also had the pleasure of giving a talk about Knockout. The session mainly focused on the various extensibility points in Knockout. After reviewing some Knockout basics, I discussed extending observables, creating custom bindings, and the idea of binding providers.

For the presentation, I knew that I wanted to show a lot of code, but I was not too excited about continually flipping between a slide show, an IDE, and a browser. So, I decided to create a slideshow from scratch with Knockout that let me combine all three pieces into a single page app. It was quite a bit of work, but it was a fun experience overall.

Here is a screencast of the presentation:

Extending Knockout.js - 08/14/2012 - ThatConference

For creating the presentation app, I used these libraries:

Knockout
require.js & the text plugin - for managing dependencies and dynamically loading view models, templates, and code samples.
CodeMirror - for the code editor
jQuery - just for some animations
jqPlumb - for drawing lines between two elements

Here is a repository with a heavily stripped down version of the app that I created for this presentation https://github.com/rniemeyer/SamplePresentation.

The binding provider sample implementation is also available here https://github.com/rniemeyer/knockout-classBindingProvider.

I would love to hear any feedback on the presentation. Also, I was thinking about the possibility of recording some short (< 10 minutes) screencasts on various Knockout topics. Would there be any interest in something like that?

Knockout.js Performance Gotcha #3 - all bindings fire together

2012-06-22T23:55:00-05:00

How bindings are processed

When using multiple bindings on a single element, it is important to understand how Knockout triggers updates to bindings to avoid potential performance issues. For example, a common binding might look like:

<select data-bind="options: choices, value: selectedValue, visible: showChoices"></select>

How are the bindings on this element processed? When Knockout determines that an element has bindings, a computed observable is created to aid in tracking dependencies. Inside the context of this computed observable, Knockout parses the data-bind attribute’s value to determine which bindings to run and the arguments to pass. As the init and update functions for each binding are executed, the computed observable takes care of accumulating dependencies on any observables that have their value accessed.

Here is a simplified flow chart of the binding execution:

There are a couple of important points to understand here:

The init function for each binding is only executed once. However, currently this does happen inside the computed observable that was created to track this element’s bindings. This means that you can trigger the binding to run again (only it’s update function) based on a dependency created during initialization. Since, the init function won’t run again, this dependency will likely be dropped on the second execution (unless it was also accessed in the update function).
There is currently only one computed observable used to track all of an element’s bindings. This means that the update function for all of an element’s bindings will run again when any of the dependencies are updated.

This is definitely something to consider when writing custom bindings where your update function does a significant amount of work. Whenever bindings are triggered for the element, your update function will run, even if none of its observables were triggered. If possible, it is a good idea to check if you need to do work, before actually executing your update logic.

Common problems with the default bindings

1- A common scenario where this can cause an issue is when using the template binding in conjunction with other bindings. For example, you may attach a visible binding along with a template binding like:

<div data-bind="visible: showPlaylist, template: { name: 'playlistTmpl', data: playlist }"></div>

In this case, if showPlaylist is frequently updated, it will cause the template binding to re-render the template again. In some cases, this may not cause a concern (it would just behave like the if binding). However, in a scenario where the template has significant markup and the visible binding’s condition is frequently triggered this can cause an unnecessary performance hit. Note that when using the foreach option or binding, logic is executed to determine if any items were added or removed, so it will cause less of a performance hit in that case.

2- Another place where this can come into play with the default bindings is when using the options and value bindings together. The update function of the options binding rebuilds the list of option tags for the select element. Whenever the value is updated, it will trigger all of the bindings on the element to execute. So, instead of just setting the appropriate value, it will rebuild all of the options and then set the value. If you have a situation where you have a large number of options, then this can cause a performance issue.

Ways to address this concern

1- In some cases, it makes sense to put bindings on separate elements or on a container element. For example, you may be able to move a frequently triggered visible binding to a parent element rather have it coupled with other bindings like the template binding.

<div data-bind="visible: showPlaylist">
    <div data-bind="template: { name: 'playlistTmpl', data: playlist }"></div>
</div>

Here is a sample showing a visible and template binding on the same and different elements:

2- In the case of the options and value bindings, you can choose to build your option elements separately. It would be nice to just use a containerless foreach statement inside of a select element, but Internet Explorer will remove comments that it finds between select and option elements. An alternative would be to use Michael Best’s repeat binding on the option element like:

<select data-bind="value: selectedOption">
    <option data-bind="repeat: {foreach: items, bind: 'attr: { value: $item().id }, text: $item().name'}">
</select>

3- A more advanced way to handle these issues, is to create your own computed observable in the init function to handle updates yourself. Any observables accessed in your computed observable, will not be a dependency of the overall computed observable used to track all of the element’s bindings.

This is a technique that I tend to use by default in any bindings that I write. It is also useful when you want a single binding to accept multiple observable options and you want to respond separately to each one changing (as opposed to using the update function to repond when any observable changes). You can even wrap the existing bindings in this way to create an isolatedOptions binding.

ko.bindingHandlers.isolatedOptions = {
    init: function(element, valueAccessor) {
        var args = arguments;
        ko.computed({
            read:  function() {
               ko.utils.unwrapObservable(valueAccessor());
               ko.bindingHandlers.options.update.apply(this, args);
            },
            owner: this,
            disposeWhenNodeIsRemoved: element
        });
    }
};

A few notes on this technique:

The idea is that we want to trap our dependencies in our own isolated computed observable.
We call the update function of the options binding using .apply with the original arguments that were passed ot the binding.
The disposeWhenNodeIsRemoved option ensures that this computed observable will be destroyed if Knockout removes our element, like in a templating scenario.
There is one minor issue with using this technique currently: observables that are accessed in the actual binding string are included in the overall computed observable during parsing rather than when you create you call valueAccessor. This means that if your binding contains an expression where you access the observable’s value (text: 'Hello ' + name()) , then it will be tracked in the overall computed observable. This is likely to change in the near future.

Here is a sample that shows using #2 and #3 with options and value bindings: http://jsfiddle.net/rniemeyer/QjVNX/

Future

There has been some thought and work put into running each binding in the context of its own computed observable. Michael Best has this working properly in his Knockout fork. As these changes can be considered breaking, they will likely be carefully implemented over time using an opt-in approach, perhaps until a major version allows us to make some potentially breaking changes. For now, it is wise to keep in mind how your bindings are triggered and how that affects other bindings on the same element.

Using KO's native PubSub for decoupled synchronization

2012-05-29T23:55:00-05:00

In the previous post, I suggested some ideas for binding against multiple view models in Knockout.js. When working with more than one view model, a common task is deciding how to communicate between the separate components. Creating direct references between them often doesn’t feel right and can lead you down a path where each view model has lost its independence and cannot be used effectively without the other objects.

To handle this situation, we can keep our components loosely coupled by using a messaging system where each view model or component does not need to have direct references to its counterparts. There are several benefits to using this technique:

Components remain independent. They can be developed, tested, and used in isolation.
Knockout view models and non-KO components can communicate using a common interface without direct knowledge of each other.
Components can be safely refactored. Properties can be renamed, moved, and adjusted without worrying about breaking compatibility.

Knockout’s native pub/sub

There are already many libraries and options for providing this type of message bus. One option might be triggering custom events or using great pub/sub libraries like amplify.js or postal.js. While these libraries provide robust capabilities, Knockout itself already has all of the tools to do basic pub/sub communication built-in. This is part of the ko.subscribable type, which has its capabilities added to observables, computed observables, and observableArrays.

Normally, you would not construct a ko.subscribable directly, but it is easy enough to do so:

var postbox = new ko.subscribable();

In Knockout 2.0, support was added for topic-based subscriptions to aid in sending out beforeChange notifications. To create a topic-based subscription against our ko.subscribable, we would simply do:

postbox.subscribe(callback, target, topic);

//with some actual code
postbox.subscribe(function(newValue) {
    this.latestTopic(newValue);
}, vm, "mytopic");

To send out a notification on this topic we would do:

postbox.notifySubscribers(value, "mytopic");

Now, we can do basic pub/sub messaging using subscribe and notifySubscribers against our mediator, the postbox object. However, whenever I explore integrating a new technique with Knockout, I try to consider how to make it feel as easy and natural as possible.

Extending Observables

A typical scenario for this type of functionality would be that we want to synchronize an observable between view models. This might be a one-way or even a two-way conversation. To make this easy, we can look at extending the ko.subscribable type, which would affect observables, observableArrays, and computed observables.

Suppose that we want to setup an observable to automatically publish on a topic whenever it changes. We would want to set up a manual subscription against that observable and then use notifySubscribers on our postbox.

ko.subscribable.fn.publishOn = function(topic) {
    this.subscribe(function(newValue) {
        postbox.notifySubscribers(newValue, topic);
    });

    return this; //support chaining
};

//usage of publishOn
this.myObservable = ko.observable("myValue").publishOn("myTopic");

Now, whenever the observable’s value changes, it will publish a message on the topic.

On the other side, we might want to make it easy for an observable to update itself from messages on a topic. We can use this same concept:

ko.subscribable.fn.subscribeTo = function(topic) {
    postbox.subscribe(this, null, topic);

    return this;  //support chaining
};

//usage
this.observableFromAnotherVM = ko.observable().subscribeTo("myTopic");

Notice that we can just pass this (the observable) in as the callback to the subscribe function. We know that an observable is a function and that it will have its value set when you pass an argument into the function. So, there is no need to write something like:

//no need to add an extra anonymous function like:
postbox.subscribe(function(newValue) {
    this(newValue);
}, this, topic);

Now, our observables can exchange information without direct references to each other. They do need to agree on a topic, but do not have any knowledge about the internals of the other view model or component. We can even mock or simulate the other components in testing scenarios by firing messages.

Potential gotcha: publishing objects

If the new value being published is an object, then we need to be careful, as both sides will have a reference to the same object. If code from multiple view models makes changes to that object, then we are likely no longer as decoupled as we would like. If the object is simply configuration/options passed as an object literal that are not modified, then this seems okay. Otherwise, it is preferable to stick to primitives in the values being published. Another alternative is to use something like ko.toJS to create a deep-copy of the object that is being published, so neither side has the same reference.

A new library: knockout-postbox

I created a small library called knockout-postbox to handle this type of communication. It uses the techniques described above and adds a bit of additional functionality:

creates a ko.postbox object with clean subscribe and publish methods that take a topic as the first argument.
adds a subscribeTo function to all subscribables (observables, observableArrays, and computed observables). The subscribeTo function also allows you to initialize your observable from the latest published value and allows you to pass a transform function that runs on the incoming values.
adds an unsubcribeFrom function to all subscribables that removes subscriptions created by subscribeTo.
adds a publishOn function to all subscribables that automatically publishes out new values. The publishOn function also allows you to control whether you want to immediately publish the initial value, and lets you supply an override function (equalityComparer) that allows you to compare the old and new values to determine if the new value should really be published.
adds a stopPublishingOn function to all subscribables that removes the subscription that handles the publishOn messages.
adds a syncWith function that does both a subscribeTo and a publishOn on the same topic for two-way synchronization.

Project link: https://github.com/rniemeyer/knockout-postbox

Basic sample:

Link to sample on jsFiddle.net

Next post: using this concept to integrate with client-side routing in a way that is natural to Knockout

Quick Tip: Telling Knockout to skip binding part of a page

2012-05-16T20:57:00-05:00

Recently, I worked with several people on questions related to binding multiple view models in a single page. One common approach is to bind a view model to a particular root element using a call like ko.applyBindings(vm, containerNode);. However, a limitation with this approach is that when binding multiple view models, none of the container elements can overlap. This means that you could not bind one view model nested inside of another.

One way to address this issue is to create a top level view model that contains your “sub” view models and then call ko.applyBindings on the entire page with the overall view model:

var profileModel = {
    first: ko.observable("Bob"),
    last: ko.observable("Smith")
};

var shellModel = {
    header: ko.observable("Administration"),
    sections: ["profile", "settings", "notifications"],
    selectedSection: ko.observable()
};

//the overall view model
var viewModel = {
    shell: shellModel,
    profile: profileModel
};

ko.applyBindings(viewModel);

Now in the view, you can use the with binding along with $root to bind a nested view model:

<div data-bind="with: shell">
    <h2 data-bind="text: header"></h2>
    <div data-bind="with: $root.profile">
        ...
    </div>
    ...
</div>

This technique is nice, because you only have to make a single ko.applyBindings call and you can use $root or $parent/$parents to access data at any time from another view model. However, based on a desire to maintain modular code and to control how and when elements are bound, it is often not convenient or practical to build a top level view model.

With Knockout 2.0, there is a simple alternative that can provide for greater flexibility. Bindings are now able to return a flag called controlsDescendantBindings in their init function to indicate that the current binding loop should not try to bind this element’s children. This flag is used by the template and control-flow bindings (wrappers to the template binding), as they will handle binding their own children with an appropriate data context.

For our scenario, we can take advantage of this flag and simply tell Knockout to leave a certain section alone by using a simple custom binding:

ko.bindingHandlers.stopBinding = {
    init: function() {
        return { controlsDescendantBindings: true };
    }
};

Now, we can bind our “shell” model to the entire page and bind our “profile” model to the specific container:

var profileModel = {
    first: ko.observable("Bob"),
    last: ko.observable("Smith")
};

var shellModel = {
    header: ko.observable("Administration"),
    sections: ["profile", "settings", "notifications"],
    selectedSection: ko.observable()
};

ko.applyBindings(shellModel);
ko.applyBindings(profileModel, document.getElementById("profile"));

In our view, we can now use the simple stopBinding custom binding around our inner container element:

<div>
    <h2 data-bind="text: header"></h2>
    <div data-bind="stopBinding: true">
        <div id="profile">
            <input data-bind="value: first" />
            <input data-bind="value: last" />
        </div>
    </div>
    ...
</div>

Adding the extra div to hold our stopBinding binding may not cause our app any problems, but if it does then in KO 2.1 we can now create containerless custom bindings by adding our binding to ko.virtualElements.allowedBindings.

ko.bindingHandlers.stopBinding = {
    init: function() {
        return { controlsDescendantBindings: true };
    }
};

ko.virtualElements.allowedBindings.stopBinding = true;

and finally we can clean up our view to look like:

<div>
    <h2 data-bind="text: header"></h2>
    <!-- ko stopBinding: true -->
    <div id="profile">
        <input data-bind="value: first" />
        <input data-bind="value: last" />
    </div>
    <!-- /ko -->
</div>

With this simple binding, we can now compose pages with multiple view models without the worry of conflicting/overlapping bindings.

Here is a live sample:

Link to full sample on jsFiddle.net

Knockout 2.1 is out

2012-05-08T03:57:00-05:00

Knockout.JS 2.1 is now available! Minified and debug versions available here. This release focused mainly on performance improvements and bug fixes after the 2.0 release.

Here are some highlights:

CommonJS and AMD support
Great performance improvements to templating - use cloned DOM nodes when possible rather than parsing strings into elements.
Support for custom container-less bindings
Ability to extend the binding context in a custom binding
Computed observables no longer can recursively evaluate themselves (I think that has happened to all of us a few times!)
$index is available in foreach scenarios from the binding context. There is no longer a need for workarounds like storing an index as a property of your data items. Note that $index is an observable, so it needs to be reference using $index() in expressions.
$parentContext is available from the binding context as well. While, $parent contains the actual data from one scope level up, $parentContext contains the actual binding context ($data, $parent, $parents, $root, etc.) of the parent.
ko.isComputed is a helper function that was added to determine if a value is a computed observable or not.
ko.toJSON now passes its arguments on to JSON.stringify after calling ko.toJS. This makes creating a handy “debug” section even easier <pre data-bind="text: ko.toJSON($root, null, 2)"></pre> and this can be used to include only certain properties in the converted JSON like ko.toJSON(person, ['firstName', 'lastName']). This seems even more flexible in many cases than the approach that I mentioned here.
Better support for using a single instance of KO between documents - you can now pass an instance of KO between documents and have bindings work properly across the documents. Previously the computed observables associated with bindings would dispose themselves when outside of the original document as they believed they were no longer part of the DOM.
Numerous other bug and performance fixes

For this release Michael Best joined the core team and drove the majority of the changes with Steve. Michael has numerous other exciting performance enhancements in his fork that will be evaluated for possible inclusion (in a non-breaking fashion) in the core. He has really helped tremendously in moving the project forward.

Please report any issues found here.

Giving the blog a facelift

2012-05-07T11:58:00-05:00

I just finished the process of moving this blog from Blogger to an Octopress site that uses Jekyll to generate a static blog. I am excited to have better control over the look and feel of the blog and to move to a git-based workflow using markdown files for posts.

Here are a few of the steps that I took to make this move:

Converted Blogger site to use disqus for comments
Imported old comments using the import tool from disqus
Imported blog posts into Octopress using the script here to at least get some basic structure and permalinks.
At that point, I scrapped all of the HTML for each post and recreated each in markdown. It was a painful and time consuming process, but the posts will hopefully now look consistent and will be easier to edit/update in the future.
Made updates/change to the layout and look of the default template.
Created an app in Heroku, pushed the site to it, and added the custom domain.
Pointed the domain to Heroku.
Updated the Feedburner feed to use the new RSS.

I was never too excited about the look, feel, and process of updating the old site. I was mostly focused on getting content out there and a Blogger blog was an easy way to get started. I am excited to continue tweaking the site and using git and markdown for the posts. Hopefully, I will find it easier to make more frequent posts and to update older posts as Knockout changes.

Knockout.js Performance Gotcha #2 - manipulating observableArrays

2012-04-07T23:24:00-05:00

Most Knockout.js applications tend to deal with collections of objects that are stored in one or more observableArrays. When dealing with observableArrays, it is helpful to understand exactly how they work to make sure that you don’t hit a performance issue.

An observableArray is simply an observable with some additional methods added to deal with common array manipulation tasks. These functions get a reference to the underlying array, perform an action on it, then notify subscribers that the array has changed (in KO 2.0, there is now an additional notification prior to the change as well).

For example, doing a push on an observableArray essentially does this:

ko.observableArray.fn.push = function () {
    var underlyingArray = this();
    this.valueWillMutate();
    var result = underlyingArray.push.apply(underlyingArray, arguments);
    this.valueHasMutated();
    return result;
};

Pushing items to an observableArray

Let’s consider a common scenario where we have a collection of objects along with a computed observable to track a filtered array of those objects.

var ViewModel = function() {
    this.items = ko.observableArray([
        new Item("Task One", "high"),
        new Item("Task Two", "normal"),
        new Item("Task Three", "high")
    ]);

    this.highPriorityItems = ko.computed(function() {
        return ko.utils.arrayFilter(this.items(), function(item) {
            return item.priority() === "high";
        });
    };
};

Now, say we want to add additional data from the server to the observableArray of items. It is easy enough to loop through the new data and push each mapped item to our observableArray.

this.addNewDataBad = function(newData) {
    var item;
    for (var i = 0, j = newData.length; i < j; i++) {
        item = newData[i];
        self.items.push(new Item(item.name, item.priority));
    }
};

Consider what happens though each time that we call .push(). The item is added to our underlying array and any subscribers are notified of the change. Each time that we push, our highPriorityItems filter code will run again. Additionally, if we are binding our UI to the items observableArray, then the template binding has to do work each time to determine that only the one new item was added.

A better pattern is to get a reference to our underlying array, push to it, then call .valueHasMutated(). Now, our subscribers will only receive one notification indicating that the array has changed.

this.addNewDataGood = function(newData) {
    var item, underlyingArray = self.items();
    for (var i = 0, j = newData.length; i < j; i++) {
        item = newData[i];
        underlyingArray.push(new Item(item.name, item.priority));
    }
    self.items.valueHasMutated();
};

This can be simplified down to:

this.addNewData = function(newData) {
    var newItems = ko.utils.arrayMap(newData, function(item) {
       return new Item(item.name, item.priority);
    });
    //take advantage of push accepting variable arguments
    self.items.push.apply(self.items, newItems);
};

Here is a jsFiddle that tracks the number of re-evaluations for each method: http://jsfiddle.net/rniemeyer/NCpxm/.

Clearing or replacing the contents of an observableArray

Another common scenario is when you want to completely replace the contents of an observableArray. This may be to empty the array or to set it to a new set of items. There is no need to loop through the array and operate on it. The most efficient operation is to simply set it to a new value:

//clear the observableArray
this.items([]);

//replace the contents of the observableArray
this.otherItems(newData);

Minimizing the amount of notifications to subscribers from observableArrays is an easy way to avoid a potential performance issue. Typically, this can be done by performing your operations on the underling array and then triggering notifications. In other cases, replacing the observableArray’s value with a completely new value is a good choice that results in a single notification.

Knockout.js Performance Gotcha #1 - if/with bindings are not always cheap

2012-03-29T23:56:00-05:00

update: Knockout 2.2 has addressed the first issue in this post. Now the if and ifnot binding will not re-render their contents unless the value changes between truthy and falsy.

A recent StackOverflow question prompted me to start a series of short posts with some basic performance tips/gotchas for Knockout.js. In smaller applications, many of these items would go unnoticed, but as a project becomes more complex, it is important to understand the amount of work that Knockout is doing to manage your UI.

The control flow bindings introduced in Knockout 2.0 are really just simple wrappers to the template binding. They use the children of the element as their “template” (what we call anonymous templates) and will re-render the contents whenever triggered. If you are not careful, the if and with bindings may be causing re-renders much more often than you might realize.

Problem: if binding causing frequent re-renders

A common scenario where you might use the if binding is when you want to display a section only when an observableArray actually contains items. Something like:

<!-- ko if: items().length -->
<h2>Items</h2>
<ul data-bind="foreach: items">
    <li data-bind="text: name"></li>
</ul>
<!-- /ko -->

The problem in this case, is that the if binding depends on the items observableArray and re-evaluates every time that it is updated. Each time that it is triggered and has a truthy value, it will actually re-render its “template” again, as you can see here.

Solutions

One choice to avoid these re-renders would be to instead use the visible binding on a container element around our section or on the individual elements, as shown here.

If we prefer to use the if binding in this case, then we need to make sure that it is only triggered when the number of items in our array moves between 0 and 1. One might think that a computed observable holding the length would be a good choice. However, one important thing to note is that currently computed observables will always notify subscribers when re-evaluated, even if their value ends up being the same.

However, this is not true for observables. Notifications are suppressed when you write a value that is identical to the previous value (this behavior can be overridden). So, one option is to subscribe to changes to our observableArray and populate an observable based on the length.

this.items = ko.observableArray();

this.hasItems = ko.observable(false);

this.items.subscribe(function(newValue) {
    this.hasItems(newValue && newValue.length ? true : false);
}, this);

Now, we can bind against hasItems and it will only notify subscribers when changing between true and false based on the length of the array. You can here see that each item is no longer re-rendered on every add.

You could even extend observableArrays to add a function that would attach this hasItems property as a sub-observable and create the subscription to keep it updated. This helps to keep the view model a bit cleaner and allows you to easily reuse the code.

It might look like:

ko.observableArray.fn.trackHasItems = function() {
    //create a sub-observable
    this.hasItems = ko.observable();

    //update it when the observableArray is updated
    this.subscribe(function(newValue) {
        this.hasItems(newValue && newValue.length ? true : false);
    }, this);

    //trigger change to initialize the value
    this.valueHasMutated();

    //support chaining by returning the array
    return this;
};

Here is a sample of how to use this function.

Problem: with binding causes entire area to re-render

The with binding is very handy for binding against nested objects/models and helps to keep your data-bind attributes from becoming too verbose. It is important, however, to understand that the with binding will re-render the entire section whenever its bound value changes.

For example, we might want to render a selected item like:

<div data-bind="with: selectedItem">
    <h2>Selected</h2>
    <input data-bind="value: name" />
    <input data-bind="value: price" />
</div>

The children of the main div become our template. Whenever selectedItem changes, the contents are re-rendered completely. So, rather than just binding the inputs against the new data, the entire section is replaced with new elements, as shown here. In this case, it won’t cause any issues, but if your markup is complex and/or has events attached outside of Knockout, then you can run into issues when the elements are removed and replaced by the original template.

Solutions

If performance does end up becoming an issue, then we could consider just binding directly to the observables on the selected item. If the selected item might be null, then you would need to make sure that the binding does not fail looking for properties on a null object, as show in this sample.

Another choice would be to use the with binding in smaller, targeted areas. We can make use of the containerless control-flow bindings to wrap more specific sets of elements, as shown here.

Finally, for cases where you want to bind against a nested object that won’t change (non-observable), take a look at the simple withlight binding developed by Michael Best. This will switch the context to your nested object on initialization, but is not designed to bind against an observable that will be changed.

Conclusion

The control-flow bindings are certainly handy, but when performance matters, it helps to understand a little bit about how they are implemented. In cases where you want to avoid re-rendering entire sections of your UI, it takes a little extra work to ensure that this is not happening too frequently.

Knockout.js bindings for Kendo UI

2012-03-25T23:50:00-05:00

Recently, I spent much of my late hour programming time working on a project to create a set of Knockout.js bindings for the Kendo UI web widgets. After being involved in several discussions about how Kendo UI could integrate with Knockout, I decided to jump in and try to provide a place where this integration could officially exist and grow. As a result, there is now a project on Github for these bindings.

Kendo UI – a great framework

If you are not familiar with Kendo UI, then take a look at the demos and documentation. Also, take note of the licensing requirements. I am not affiliated with Telerik in any way, but am quite impressed with the framework. In my experience, it is an excellent product with good people working on it.

When developing these bindings, the first challenge that I found was how to simultaneously write, test, and document 19 custom bindings. After writing a couple of the bindings “by hand”, I decided to take a different route and create a factory that could generate the bindings. The idea is that you pass in some configuration and it can produce a proper binding for you. This would allow for the sharing of common code, easier maintenance/enhancements, and the ability to generate some standard tests for each widget from the configuration.

A pattern for 3rd party widget bindings

To create the bindings, I followed a pattern that I like to use for custom bindings against 3rd party widget that involves these steps:

Prepare the options needed to initialize the widget
Subscribe to any events triggered by the widget that require an update to the model
Initialize the widget
Register to destroy the widget when KO removes this element *Use either the update function or individual computed observables created in the init function to update the widget based on changes to the model.

This covers creating the widget and syncing changes between the model and the widget. However, for these bindings I wanted to support a couple of additional features:

The ability to define global default options for a widget. The binding will merge any options passed in the data-bind attribute with these global options. This helps to keep the mark up clean by not forcing you to include all of the configuration in the binding string.
The ability to access the actual widget from the view model. If you pass a “widget” option to the binding, then it will fill that observable with a reference to the actual widget. This allows you to call methods of the widget from within view model methods, if necessary.

Next Steps

With these particular bindings, I hope to look at bringing tighter integration with templating and data sources. Many of the widgets (Grid, ListView) need this type of support to fit naturally in a Knockout application. I also hope to see what kind of feedback comes from real-world usage to decide the next steps.

Additionally, if there is enough demand, it would be interesting to apply this factory concept to other widgets like jQuery UI, YUI , and/or the Bootstrap plugins.

One final note: Kendo UI recently released their own native MVVM implementation. It has a Knockout flavor to some of the syntax and integrates well with the widgets. It is definitely an option to consider, if you are “all in” on Kendo UI.

Knockout-Kendo.js project link

Revisiting dragging, dropping, and sorting observableArrays

2012-02-04T13:54:00-06:00

Earlier I explored a set of Knockout.js bindings that would allow dragging and dropping items in an observableArray. These bindings could either be used to sort items in a single array or to move items between arrays. With Knockout 2.0, I wanted to take a fresh look at how this can be accomplished. The resulting project is here.

Areas for improvement

The original syntax that I was using for binding to a single array looked like:

<div class="container"
  data-bind="template: {name: 'taskTmpl', foreach: tasks},
    sortableList: tasks">
</div>

The syntax for binding multiple arrays, required additional data to be passed to the chlidren. The parent looked like:

<div class="container"
  data-bind="template: {name: 'taskTmpl',
    foreach: highPriorityTasks,
    templateOptions: { parentList: highPriorityTasks} },
    sortableList: highPriorityTasks">
</div>

The child elements required some meta-data to be attached via a binding:

<div data-bind="sortableItem: { item: $data, parentList: $item.parentList }" >

This syntax is far too verbose and forces us to use too many bindings to make this work. My goal is to use a single binding that will work for both a single array and moving items between arrays. Ultimately, I wanted to simplify it down to something like this:

<ul data-bind="sortable: tasks">
  <li data-bind="text: name"></li>
</ul>

or if using named templates like:

<ul data-bind="sortable: { tmpl: 'taskTmpl', list: tasks }"></ul>

What does our single binding need to accomplish?

We are not specifying the template or foreach binding, so our binding will have to wrap this functionality by calling the template binding with the appropriate options.
We are not specifying any bindings on the children, so we need to find a way to attach meta-data to the children, so we can retrieve the data and original parent from a dropped element. Since we are calling the template binding, we can use its afterRender option to add the meta-data.
The element require a certain class to be hooked up as a target. We should handle adding this class in the binding rather than requiring the developer to add it (or forget to add it).
We still need to initialize the container by calling jQuery UI’s .sortable and specify how to handle an item being dropped.
We should also call the sortable widgets destroy method when Knockout removes the element (perhaps by the template binding).

How about some extra features?

With these features in place, we can clean up the syntax required on the element and still accomplish the same functionality as before. However, there are a few additional enhancements that I felt would be useful in the binding:

You can configure the class that is used on the element to enable it as a drop target (the connectWith class).
You can specify a function, observable, or static value to determine whether the element is a target for dropping. This will toggle the class based on the supplied value and react if it changes.
The binding accepts a beforeMove function that allows you to perform an action prior to the item being moved from its original location to its new destination. This function can also cancel the move.
The binding also accepts an afterMove function to perform an action after the item has been moved to its new index it the destination array.

Each of these options can be specified in the binding like:

<ul data-bind="sortable: {data: items, afterMove: saveData, allowDrop: isBucketFull}"></ul>

Additionally, each feature can be configured with a global default. This keeps the markup/bindings clean when the options will apply to all or most of the bindings. This would look like:

ko.bindingHandlers.sortable.connectClass = "myContainer";
ko.bindingHandlers.sortable.allowDrop = viewModel.isBucketFull;
ko.bindingHandlers.sortable.afterMove = viewModel.saveData;

Samples

Single Todo list:

Link to sample on jsFiddle.net

Connected Todo lists:

Link to sample on jsFiddle.net

Seating chart:

Link to sample on jsFiddle.net

knockout-sortable Project

The binding is up on github here: https://github.com/rniemeyer/knockout-sortable. I am definitely looking for feedback and suggestions for additional functionality, as well as working to improve the docs, specs, examples.

Knockout 2.0 is out!

2011-12-21T08:25:00-06:00

KnockoutJS 2.0 is available now! This version was formally known as 1.3 and has been in the works for quite a while. It includes substantial changes that are mainly focused on allowing developers to write cleaner and simpler code while providing additional extensibility points to that allow better control of how Knockout is used. has been thoroughly updated for this release with changes to docs, examples, and tutorials along with some additional advanced topics.

A few links:

Get the 2.0 build on github here.
Check out Steve’s post summarizing the changes.
Look at the tutorials, docs, and examples.
See more in-depth coverage of some of the extensibility points in posts from this site:

KnockoutJS 2.0 is an exciting release. The native templating and control-flow bindings allow an easier and streamlined way to change scope and repeat content. It is no longer required to reference an external engine like the jQuery Templates plugin to do templating in Knockout. Even jQuery is not a strict dependency. The additional extensibility points allows developers to explore using Knockout in different ways, such as applying bindings in code rather than declaratively.

I would expect a 2.0.x release in the near future that will include some further performance tweaks that are being explored, but overall 2.0 feels very solid. Go try it now and please leave feedback here or here.

Knockout 1.3 Release Candidate + a new feature

2011-11-19T22:24:00-06:00

Update: Knockout 1.3 was eventually renamed to version 2.0

Just a quick note: the Knockout.js 1.3 release candidate is now available for testing. Barring any last-minute fixes, this should be the final version. Files are available from: https://github.com/SteveSanderson/knockout/tree/master/build/output.

Some links to 1.3 information:

Currently, I am working with Steve on documentation updates to <Knockoutjs.com> before a final release. Hopefully, it will be ready soon!

Controlling when to receive subscription notifications

There were was one feature added recently, which hasn’t been covered, that I wanted to briefly highlight. Knockout 1.3 now allows you to decide when you want to be notified before or after a value has changed when creating a manual subscription. The default behavior, as before, is that the subscription runs after the value has changed and passes the new value as the first argument.

When creating a manual subscription, you can now opt to have your code run before the value has changed and receive the previous value as the first parameter. To be notified before the value changes, the subscribe API now accepts a third parameter to specify an event name.

viewModel.price.subscribe(function(value) {
    this.history.push({ value: value, time: new Date() });
}, viewModel, "beforeChange");

If the event name is not passed, then it will default to change, which is consistent with the current behavior of manual subscriptions.

This can be useful to take action before a value has changed or to track changes to values. Previously, you could have accomplished this with a writeable dependentObservable in front of the actual observable, but this allows a more direct way to accomplish this type of action.

While change and beforeChange are the only events that Knockout uses itself, we are able to subscribe to custom events. We would couple this with the use of the notifySubscribers method on an observable to trigger messages for those events. This could be useful in certain scenarios where your application wants to delegate responsibilities to other components.

viewModel.price.subscribe(function(newValue) {
    if (!newValue) {
        this.price.notifySubscribers(null, "valueRemoved");
    }
}, viewModel);

viewModel.price.subscribe(function() {
    //react to the value being removed
}, viewModel, "valueRemoved");

As shown above, we can create an overall subscription to an observable that looks at its state and decides when to notify subscribers of any appropriate events. These could be chained together and allow us to create components that expose specific events to subscribers. Seems like a potentially useful feature to consider when creating a reusable library with Knockout.

KO 1.3 preview part 3: template sources

2011-10-21T23:07:00-05:00

Update: Knockout 1.3 was eventually renamed to version 2.0

Knockout 1.3 contains a number of enhancements that allow developers to extend the default capabilities of the library. Besides custom binding providers, you can now also create objects that define how to get and set a template’s contents based on the template name. These objects are called templateSources.

Knockout’s default templateSources

Knockout includes two templateSources that are used by default. The first templateSource understands how to retrieve a template from a DOM element using the template name as the id of the element. Typically, these are the templates that live in script tags. The other deals with anonymous templates, where the children of the element are used as the template. Anonymous templates are used when a name is not provided to the template binding and is most commonly used with the new control-flow bindings.

What does a templateSource look like?

A templateSource needs to provide a text and a data function. Similar to an observable, the text function when given no arguments should return the text of the template. When passed a single parameter, the function should write that value to wherever the template is being stored.

The data function is used to associate additional metadata related to the template and should accept key and value parameters. If only passed the key parameter, it should return the value. If passed both arguments, then it should use the key to write the value to an appropriate location. This meta-data is currently used for things like indicating that a template has been rewritten and to set/retrieve a precompiled version of a jQuery template.

A quick note about rewriting templates

When using a third-party engine, Knockout needs to take special care to ensure that the proper scope is available when applying bindings. You might want to use variables that are exposed by the template engine in your data-bind attributes or you may be looping over arrays using the template engine’s syntax and adding bindings on elements inside the loop. These are cases where Knockout can rewrite the template to allow bindings to execute under the proper context, as long as the template engine knows how to create a block to execute arbitrary JavaScript. Note that the new native template engine does not require this rewriting.

Writing a quick custom templateSource

Suppose that we want to keep our templates in strings. Maybe we want to load them from the server or even generate them on-the-fly. For starters, we can maintain an object that stores our template text by key like:

templates: {
    viewTemplate: "<li data-bind='text: name'></li>",
    editTemplate: "<li><input data-bind='value: name' /></li>"
}

To create our templateSource, let’s first write a constructor function that takes in the name of our template and the object that holds our templates.

ko.templateSources.stringTemplate = function(template, templates) {
    this.templateName = template;
    this.templates = templates;
};

Next our templateSource needs to provide a text method. When passed no parameters, we need to return our template from the template object. When passed a value (in the case of a rewritten template), we need to set the value on the template object. This method can be as simple as:

text: function(value) {
     if (arguments.length === 0) {
        return this.templates[this.templateName];
     }
     this.templates[this.templateName] = value;
}

Now we need a data method for storing any meta-data about the template. We could have our template object store text and data properties for each key, but to keep the template definitions simple, I am going to tuck the meta-data into a _data key on the template object.

data: function(key, value) {
    this.templates._data = this.templates._data || {};
    this.templates._data[this.templateName] = this.templates._data[this.templateName] || {};

    if (arguments.length === 1) {
        return this.templates._data[this.templateName][key];
    }

    this.templates._data[this.templateName][key] = value;
}

This method just ensures that the proper objects have been created and then does a get or set using the key.

There is one last step that we need to perform to take advantage of our new type of templateSource. We need to override the makeTemplateSource function of a template engine. To be flexible, we can create a function that takes in an existing template engine and the location of our string templates.

function createStringTemplateEngine(templateEngine, templates) {
    templateEngine.makeTemplateSource = function(template) {
        return new ko.templateSources.stringTemplate(template, templates);
    }
    return templateEngine;
}

Finally, we need to tell Knockout to use an appropriate template engine.

ko.setTemplateEngine(createStringTemplateEngine(new ko.nativeTemplateEngine(), viewModel.templates));

Here is a sample using this technique:

Link to sample on jsFiddle.net

You could even extend this concept to create a template source that loads its contents from an external source. Here is a sample that uses an observable to store the template contents, which allows the use of a loading template while the real template is being retrieved:

Link to sample on jsFiddle.net

Knockout 1.3 definitely has some great new extensibility features. While the default templateSources should be sufficient for most applications, it is nice to know that there is some flexibility built in to deal with templates in other ways.

Knock Me Out

Working with AMD modules in Knockout.js

Why require.js and AMD modules

A few pain points

Looking at potential solutions

An AMD compatible template engine

A module binding

Communicating between modules

Summary

Joining appendTo

Tekpub Refactoring Knockout.js Screencast

A Simple Editor Pattern for Knockout.js

Separate creation and initialization

Data in matches data out

Reverting changes

Committing changes

Copying/cloning

Updating from server

Summary

Revisting Event Delegation in Knockout.js

Why event delegation in Knockout.js?

Normal event delegation with KO 2.0+

Declaratively adding a handler

Option #1 - using a binding

Pros

Cons

Option #2 - use a data- attribute with method name

Pros

Cons

Option #3 - associate method and name in root/global object

Pros

Cons

Summary

Knockout.js 2.2 is out now!

Getting the Most Out of Knockout.js Session From Twin Cities Code Camp

Extending Knockout.js Session From ThatConference

Knockout.js Performance Gotcha #3 - all bindings fire together

How bindings are processed

Common problems with the default bindings

Ways to address this concern

Future

Using KO's native PubSub for decoupled synchronization

Knockout’s native pub/sub

Extending Observables

Potential gotcha: publishing objects

A new library: knockout-postbox

Quick Tip: Telling Knockout to skip binding part of a page

Knockout 2.1 is out

Here are some highlights:

Giving the blog a facelift

Knockout.js Performance Gotcha #2 - manipulating observableArrays

Pushing items to an observableArray

Clearing or replacing the contents of an observableArray

Knockout.js Performance Gotcha #1 - if/with bindings are not always cheap

Problem: if binding causing frequent re-renders

Solutions

Problem: with binding causes entire area to re-render

Solutions

Conclusion

Knockout.js bindings for Kendo UI

Kendo UI – a great framework

A pattern for 3rd party widget bindings

Next Steps

Revisiting dragging, dropping, and sorting observableArrays

Areas for improvement

What does our single binding need to accomplish?

How about some extra features?

Samples

knockout-sortable Project

Knockout 2.0 is out!

Knockout 1.3 Release Candidate + a new feature

Controlling when to receive subscription notifications

KO 1.3 preview part 3: template sources

Knockout’s default templateSources

What does a templateSource look like?

A quick note about rewriting templates

Writing a quick custom templateSource

Option #2 - use a `data-` attribute with method name