In Place Editor Custom Binding for Knockout.js

I recently discovered knockout.js and was totally blown away. It does a great job of removing the need for (most) DOM manipulations which lets you focus on your data model and get complex UIs running with a minimal amount of code.  That said, those complex UIs are by default made up of simple widgets (input boxes, buttons, etc) and if you want more complex widgets (date pickers, inline editors, etc) you need to either find them elsewhere or roll your own.  Ryan Niemeyer gives a great explanation of how to create a date picker (or any custom binding) and I quickly incorporated it into my own site.  Since I also needed an inline editor I figured I would post my results so others could reuse and improve upon them.  The following code is very much based on the Custom Bindings article referenced above and the Jeditable inline editor.

The Goal:

The goal is to create something that looks like text but when you click it becomes editable.  I also wanted when you click off or hit enter for the text to be saved to the model.  Finally, I want hitting "Esc" to undo the latest change.  Here is a live example you can play with:

Click this:
Current value:

The Prerequisites:

The following code is based on:

• Knockout.js 2.1.0 (obviously)
• JQuery 1.7.x (parent of Jeditable)
• Jeditable (inline edit control that does most of the work)

The HTML:

The HTML is pretty simple:

Click this: <span data-bind="jeditable: name, jeditableOptions: {}"></span>
Current value: <span data-bind="text: name"></span>

If you're comfortable with Knockout.js this should look pretty familiar.  The first line uses a custom binding called "jeditable" to tie a model property called "name" to a span tag.  Knockout.js will be responsible for keeping the model and DOM in sync.  As a developer I just tell it to use the "jeditable" binding for this element and the "name" property.  There is also an optional "jeditableOptions" property which I can use to pass options to the jeditable binding.

The second line uses the standard text binding to display the current value of the "name" property in the span. Once again, as a developer, I don't have to think at all about what to update when the model changes. It all happens automatically.

The Model

The model can also be super simple:

     function myViewModel() {
      this.name = ko.observable("Innocent looking text");
     };
  
     ko.applyBindings(new myViewModel());  

In this case I just need a single property called "name" that I default to "innocent looking text".  I pass an instance of my model to Knockout as is the KO way and it handles all of the heavy lifting.  All that leaves is...

The Custom Binding

The Custom Binding is the reusable code that knows how to update the DOM when the model changes and update the model when the DOM (or control) changes:

ko.bindingHandlers.jeditable = {
     init: function(element, valueAccessor, allBindingsAccessor) {
         // get the options that were passed in
         var options = allBindingsAccessor().jeditableOptions || {};
         
         // "submit" should be the default onblur action like regular ko controls
         if (!options.onblur) {
          options.onblur = 'submit';
         }
         
         // set the value on submit and pass the editable the options
         $(element).editable(function(value, params) {
          valueAccessor()(value);
          return value;
         }, options);

         //handle disposal (if KO removes by the template binding)
         ko.utils.domNodeDisposal.addDisposeCallback(element, function() {
             $(element).editable("destroy");
         });

     },
     
     //update the control when the view model changes
     update: function(element, valueAccessor) {
         var value = ko.utils.unwrapObservable(valueAccessor());
         $(element).html(value);
     }
 };

This is a little more complicated and requires some explanation.  The binding consists of two functions "init" and "update".  "init" is called only once, when the binding is initially evaluated.  Here we can create our control and pass it any options that the user specified.  We also listen for any changes so we can notify the model.  "update" is called every time the model changes and gives us a chance to alter the control to match the state of the model.

The work begins at line 4.  Here we check to see if the user passed in any options.  This gives the user the ability to customize the Jeditable control using any of the options allowed by the plugin.  One option allowed is "onblur".  This tells the control what to do when the user clicks outside of the control.  By default Jeditable will cancel any edits onblur but since the default Knockout.js controls will save onblur we follow this convention and set the default onblur value to be "submit" (that is, save) on lines 7-9.

Lines 12-15 are where we create the control with the specified options and tie it to the appropriate DOM node.  The function that we pass in is what gets called when the user saves a new value.  In this function we simply update the model with the new value and return that value so that Jeditable thinks everything is ok.

Lines 18-20 are just housekeeping.  That's where we clean up our control if Knockout.js tells us that the DOM node should be cleaned up.

Finally, it's time to update at lines 25-28.  Here we simply get a reference to the new value in the model and update the Jeditable control to display that new value.  And that's it!  Now we have a custom binding that can be reused many times throughout the site.

The Conclusion

Knockout.js bindings may seem a little scary at first but they're not that complicated and can be very powerful.  Even someone like me who is new to Knockout.js (and JQuery) can easily whip one up and reuse it throughout a site.  My only wish is that it was easier to distribute custom bindings so that some nice libraries could be written and shared across the 'net.  Please give me any feedback or improvements you have in the comments!