Friday, June 22, 2012

Realtime data editing using an Excel-like grid and KnockoutJs

Sometimes you need to edit a batch data requiring an agile UI that allow:
  • Send changes without need confirmation
  • Quickly Navigate to any field that you want edit
  • Provide a visual indicator of the updated fields
An example: Realtime Weather Forecast Editor
On this example, the main requirement is allow quickly edit the cities temperatures at different day times. Basically for each city could edit the morning, afternoon or midnight temperature. For simplicity, the cities list are stored in a session variable.
This is a list of the implementation techniques for the app main features:
  • Updates are sent back to the server when textboxes lost focus: using a KnockoutJs extender the temperature fields changes are captured and sent to server using ajax calls.
  • Updated values are highlighted: a css binding changes the textbox background color after a field is updated successfully on server
  • Key based navigation: a jQuery handler allow navigate between textboxes using the arrows keys
App Screenshot

Using a KnockoutJs extender to send the realtime updates
A new extender named "realtime" is added to the Knockout extenders. At the initialization, it stores in two private fields (cityId and dayTime) the values required to identify the time slot to be updated on the ajax call after the observable property value changes. Also, a sub-observable (hasChanged) is used to notify the highlighter databinder.
ko.extenders.realtime = function(target, options) {
    // store private vars to use as parameters on updates
    // cityId: the key of entity to be updated
    // daytime: the field of entity to be updated (Morning/Afternoon/Midnight)
    target.cityId = options[0];
    target.daytime = options[1];
    //add a sub-observable to mantain a changed flag
    target.hasChanged = ko.observable(false);

    //define a function to send updates
    function update(newValue) {
                 url: "/home/updateforecast", 
                data: { cityId: target.cityId, daytime: target.daytime, value: newValue },
                type: "post", 
                success: function(result) 

    //update whenever the value changes

    //return the original value
    return target;

Applying the extender
The extender is applied on the ForecastModel temperature fields
var model = @Html.Raw(new JavaScriptSerializer().Serialize(Model));
var viewModel = { 
    forecasts :  ko.observableArray(ko.utils.arrayMap(model, function(forecast) {
        return new ForecastModel(forecast);
function ForecastModel(forecast) {
    this.City = ko.observable(forecast.City);
    // extend the observable fields that will be updated in realtime
    this.Morning = ko.observable(forecast.Morning).extend({realtime:[forecast.Id, "Morning"]});
    this.Afternoon = ko.observable(forecast.Afternoon).extend({realtime:[forecast.Id, "Afternoon"]});
    this.Midnight = ko.observable(forecast.Midnight).extend({realtime:[forecast.Id, "Midnight"]});

Configuring the View
A table (tblForecasts) is used to display the cities names and edit the different day times temperatures. On each temperature textbox the "value binding" is applied to each temperature field. Also, a "css binding" to the hasChanged sub-observable is applied in order to highlight the textbox background color when a change callback returns successfully from server.
    Realtime Weather Forecast Editor</h1>
<table id="tblForecasts">
    <tbody data-bind="template: { name: 'forecastRowTemplate', foreach: forecasts }">
<script type="text/html" id="forecastRowTemplate"> 
    <td><span data-bind="text: City"/></td> 
    <td><input data-bind="value: Morning, css: { hasChanged: Morning.hasChanged }"/></td> 
    <td><input data-bind="value: Afternoon, css: { hasChanged: Afternoon.hasChanged }"/></td> 
    <td><input data-bind="value: Midnight, css: { hasChanged: Midnight.hasChanged }"/></td> 
Adding keyboard navigation to table
A simple handler is attached to the textboxes keydown event to detect the arrows keys pressing and move focus
$("#tblForecasts").on("keydown", "input:text", function(e) {
        // detect arrows pressing
        if (e.keyCode < 37 || e.keyCode > 40)

        var target;
        var cellAndRow = $(this).parents('td,tr');
        var cellIndex = cellAndRow[0].cellIndex;
        var rowIndex = cellAndRow[1].rowIndex;

        switch (e.keyCode) {
            // left arrow                 
            case 37:
                cellIndex = cellIndex - 1;                        
            // right arrow                 
            case 39:
               cellIndex = cellIndex + 1;                        
            // up arrow                 
            case 40:
                rowIndex = rowIndex + 1;
            // down arrow                 
            case 38:
                rowIndex = rowIndex - 1;
        target = $('table tr').eq(rowIndex).find('td').eq(cellIndex).find("input:text");
        if (target != undefined) {
Server side code
The Forecast Model
public class Forecast
    public int Id { get; set; }
    public string City { get; set; }
    public int Morning { get; set; }
    public int Afternoon { get; set; }
    public int Midnight { get; set; }
The Controller
Just contains the code to initialize the cities list on session and a method to update the temperatures
private const string C_ForecastModels = "ForecastModels";

// Expose the stored Forecasts from Session
public IEnumerable<Forecast> ForecastModels
        if (Session[C_ForecastModels] == null)
            Session[C_ForecastModels] = new[] {
                new Forecast { Id=1, City="Barcelona", Morning=90, Afternoon=45, Midnight=40},                new Forecast { Id=2, City="Berlin", Morning=78, Afternoon=34, Midnight=0 },
                new Forecast { Id=3, City="New York", Morning=45, Afternoon=35, Midnight=20 },
                new Forecast { Id=4, City="Sydney", Morning=65, Afternoon=45, Midnight=40 },
                new Forecast { Id=5, City="Tokio", Morning=74, Afternoon=70, Midnight=60 }
        return Session[C_ForecastModels] as IEnumerable<Forecast>;
    set { Session[C_ForecastModels] = value; }

 public ActionResult Index()
     // Return the Session stored Forecasts
     return View(ForecastModels);

 // Update Forecast value for selected daytime (Morning/Afternoon/Midnight)
 public JsonResult Updateforecast(int cityId, string daytime, int value)
     var cityForecast = ForecastModels.SingleOrDefault(forecastModel => forecastModel.Id == cityId);
     if (cityForecast == null)
         return Json(false);
     switch (daytime)
         case "Morning":
             cityForecast.Morning = value;
         case "Afternoon":
             cityForecast.Afternoon = value;
         case "Midnight":
             cityForecast.Midnight = value;
     return Json(true);
This is a basic example to demonstrate the KnockoutJs extenders usage. The realtime edition on the grid and the keyboard navigation resembles the old DOS applications, but still is a powerful technique for some specific scenarios (I've worked in some projects on that this type of UI was explicitly required by the client or app end users).
Project files