The "Tech. Arch."

Creating Rich Interactive Web Apps With KnockOut.js – Part 4

techarch — Tue, 03 Jan 2012 04:30:00 +0000

Intro

In part 3 we built a complete working version of the Savings Goal Simulator where each view model and view mediator is nicely separated in its own module and corresponding source file. But what about the view? Well the goal of part 4 is to modularize and extract each view component.

Synopsis Of The Approach

The approach will need to meet the following requirements:

The view markup needs to have its own url and be cacheable
The view markup needs an ID
The view should have an HTML element
The view HTML element should be renderable

View Markup With A URL

Just like script blocks and images can be “sourced” externally from any url, we need a similar mechanism for our views.

So since the script tag allow us to do that already, let’s use it, assign an id, but let’s use a more appropriate type like text/html.

View Markup With An ID

To make it possible to reference the “script-view-markup” later on in our page or Javascript code, we’ll just assign the script an ID like so:

View HTML Element

Now that we have a way to define how a view markup can be “included” in our page, we’ll just define our view “container” as a normal HTML element. We can use a “div” or any of the more semantically significant HTML5 elements like “section“:

What we’re missing is a mechanism to:

associate the view element and the view markup together
render the actual view
optionally: data-bind any view model to the view

Renderable View

To render the markup for a given view we need a view rendering engine. As of this writing, the most prevalent option is jQuery Template.

Note: The jQuery Template implementation is rock solid and in use in many production web sites and internal applications. However the jQuery UI core team is in the process of deprecating its use and eventually replace it with another implementation. A serious contender for this is the jsRender + jsViews library. Other options also include Mustache and Handlebars. Although this tutorial is leveraging jQuery Template as its platform, I recommend you perform some additional due diligence once you’re ready to settle on library.

KnockoutJS goes one step further by integrating the view rendering engine with data-binding capabilities.

Note: KnockoutJS will allow pluggable view rendering engines over time, making it possible to use the one you choose (as long a as a plugin exists).

So KnockoutJS can take a view element with a corresponding “view template” and a view model, and render the resulting view.

Since we introduced the notion of “view template“, let’s spend some time getting familiar with the concept before proceeding with externalized views.

Introduction To Templating

Simple String-Based Templates

An string-based template is just a string containing text plus placeholders for variables. A placeholder is the name of the variable surrounded by curly braces and a prefixed by a dollar sign. So for example a template to display a time variable would look like:

    var viewTemplate = "${firstName}, the time is now ${time}"

We can group our “variables” in a Javascript object literal like so:

    var viewData = { firstName: 'Chris',
                     time:  (new Date()).toLocaleTimeString()
                    }

We can get the engine to bind the template and the data like so:

    var viewContent = $.tmpl(viewTemplate, viewData);

Finally assuming a div with the id ‘my-view’, jQuery can render the view content like so:

    $('#my-view').html(viewContent);

In summary here is a diagram showing the relationships between the various components used in templating:

To try this out yourself:

Create a web page named index.html
Add script references to both jQuery and jQuery Template using their content distribution network urls:
- http://ajax.googleapis.com/ajax/libs/jquery/1.7.0/jquery.min.js
- http://ajax.aspnetcdn.com/ajax/jquery.templates/beta1/jquery.tmpl.min.js
Add a div with the id ‘my-view’ in the body of the page

Add a Javascript script block with a jQuery ready function with our template rendering code:

You should be able to open the index.html web page in a browser and the div should now contain the rendered text with the first name and the current time.

Now we have an idea of how templating using jQuery Template is working. But in this example we are just using a string to hold our template. The library actually has a feature where you can store the template in a script tag on the same page.

Simple Inline Templates

The jQuery Template library also allow us to store the template in a script tag with a text/html type like so:

The template can then be rendered with a slightly different form of the tmpl API:

var viewContent = $('#my-view-template').tmpl(viewData);

Having the template moved out of the code is a step in the right direction, but what we need is the ability to externalize the template to an external url. We’ll tackle that subject soon I promise, but in the meantime let’s look at what KnockoutJS brings us in terms of additional templating power.

KnockoutJS Databinding Support For Inline Templates

Up to now, we have had to write the actual code to: a) render the template, and then b) insert the resulting text in an HTML element. Well, let’s see what KnockoutJS can do to simplify our task. (This will be very handy especially when your main page has many views.)

As you know, KnockoutJS provides a “data-bind” attribute where you can specify the visual or behavioral aspects (e.g. value, text, visible, enable, …) to link to a value model or dependent observable function. When we want to data-bind an HTML element to both a template and a view model, we’ll use the following syntax:

It is even possible to specify a Javascript function in an afterRender template parameter. That function will the be invoked once the HTML element has been rendered. This can be useful if you need to dynamically attach new behaviors or event handlers to the produced content. For example, you could invoke jQuery UI component configuration APIs such as applying icons for a jQuery UI button.

Our view model would then be re-written as follows:

var myViewModel = { firstName: ko.observable('Chris'),
                    time: ko.observable((new Date()).toLocaleTimeString())
}

And our “myViewHookup” after-render function would have the following form:

function myViewHookup(renderedElements, viewModel) {
    // E.g. highlight the new content for 3 seconds
    renderedElements.effect('highlight',
                            { color: 'LightGreen' },
                            3000);
}

And finally our page initialization code would ask KnockoutJS to apply the data bindings using the ko.applyBindings API:

$(document).ready(function () {
    var myViewModel = { firstName: ko.observable('Chris'),
                        time: ko.observable((new Date()).toLocaleTimeString())
    }

    ko.applyBindings(viewModel);
});

So when using jQuery, jQuery Template, and KnockoutJS, we can define a template-based view and data-bind it to a view model so it can be rendered dynamically.

Now we have covered all but one requirement: the ability to externalize the view template to a specific url.

Externalized View Templates

Basic Mechanism Needed To Externalize A Template

Let’s review our simple “template script markup”:

What we really need at this point is a way to externalize this template into its own file (maybe in a sub-folder named after the parent page, itself organized under a “view” folder):

/view/mypage/my.view.html
${firstName}, the time is now ${time}

We would then just add a src tag to our script block:

If you try this out you will notice that the browser will indeed [wget] “fetch” the content of _my.view.html, and using the web developer tool of your browser you will actually see the template markup.

But if you try to access the content of the script element using jQuery using:

$("#my-view-template").text()

… you will notice that the content is empty! The browser engine has retrieved the content but did not store it in the actual DOM element for the script. This is due to the fact that a script of type text/html is not recognized as being a script to interpret.

So we need a mechanism to fetch and store the source. The approach consists of re-fetching the source using jQuery’s $.get API. Since it was fetched once, the content is stored in the browser’s cache so retrieval wil be very fast. We then store it in the DOM’s element.
Here is a simplistic example of what the code would look like:

$(document).ready(function () {
    $.get("/view/mypage/_my.view.html",
                function(data, textStatus, jqXHR) {
                    $("#my-view-template")
                        .text(jqXHR.responseText);
                }
    );
});

So finally we can integrate our KnockoutJS view model code in the ready function:

$(document).ready(function () {
    $.get("/view/mypage/_my.view.html",
                function(data, textStatus, jqXHR) {
                    $("#my-view-template")
                        .text(jqXHR.responseText);

                    var myViewModel = { firstName: ko.observable('Chris'),
                                        time: ko.observable((new Date()).toLocaleTimeString())
                    }

                    ko.applyBindings(viewModel);
                }
    );
});

You now have externalized the view template, dynamically loaded it, data-bound it to a view model using KnockoutJS, and rendered using the jQuery Template engine!

Our example was fairly basic but it illustrates the overall concept and approach.

Generic ViewLoader Plugin

The jQuery ViewLoader plugin will take us even further by providing the ability to:

Handle nested externalized templates
Parallelize the processing of each template
Provide a simple way to handle all templates on a page and synchronize their post-processing so that the page initialization logic can proceed.

Here is what the minimum syntax looks like:

$(document).viewloader({
    logLevel: "debug",
    success: function () {
        ko.applyBindings(viewModel);
    }
});

The plugin will identify all scripts of type text/html and a source url ending in “.view.html“, including nested template scripts and request their parallel loading. Once all template scripts have been succesfully processed the success function is invoked.

Behind the scenes, jQuery ViewLoader relies on the jQuery concept of “Deferred“, an action which can be launched for “deferred” (i.e. later) execution, but can trigger a callback when completed. Actions can be grouped together so that a specific callback can be triggered once all of them have completed.

Here is a diagram of the approach:

Externalizing The Views Of Our Savings Goal Simulator

Intro

We can now apply the new approach to our Savings Goal Simulator web app since it currently contains 3 views:

savings-goal-view
consumption-scenarios-view
savings-forecast-view

For each view, we will:

Create an externalized template in the /view/index folder based on the view markup
Replace the view in index.html by a template script reference and a container DIV data-bound to the template.

Finally, we’ll update the main application.js to plugin the jQuery ViewLoader.

Here is an outline of the step-by-step approach:

#	To Do	Area
1	Create An External Template For The savings-goal-view	View
2	Refactor the savings-goal-view In Our Web Page	View
3	Hookup jQuery ViewLoader In Our Main application.js	Application
4	Refactor The Savings Goal Mediator	View Mediator

1. Create An External Template For The savings-goal-view

Our first step will be to create a new folder named view under scripts to organize our external views. Similarly to frameworks like Ruby On Rails, or ASP.NET MVC, we’ll create a subfolder named shared, for all views reusable across pages, then we’ll create a subfolder named index for views appearing on our index.html web page.

In the scripts/view/index folder, let’s create a file named _savings-goal.view.html. I used an underscore prefix to reflect the Rails convention of “partial views” being prefixed that way.

Then we can copy the savings-goal-view markup from index.html page and paste it in our new _savings-goal.view.html file.


    Savings Goal Amount:
    


    Savings Max Duration (In Months):
    


    Savings Target Per Month:

Now we can refactor index.html.

2. Refactor the savings-goal-view In Our Web Page

In place of our savings-goal-view markup, let’s first add a script reference to the view we just created, and give it an id of savings-goal-view-template:

Second, let’s add a div acting as a container for our external view. We’ll give it an id of savings-goal-view-container, and declare our KnockoutJS data-binding with the savings-goal-view-template:

Let’s download:

the latest version of jQuery Templates from https://github.com/jquery/jquery-tmpl
the latest version of KnockoutJS from https://github.com/SteveSanderson/knockout
the jQuery ViewLoader plugin and place it in the /scripts/vendor folder.

In the index.html page, in the LAB loader section, let’s:

Replace the call to load jQuery Template from our downloaded version (instead of the version from the CDN which is older)
Replace the call to load KnockoutJS from our downloaded version

Add a call to load the jQuery ViewLoader plugin:

Here is how all the piece parts will fit together:

Ok, now it’s time to plug in code to get the ViewLoader to load our view.

3. Hookup jQuery ViewLoader In Our Main application.js

First let’s create 2 new utility functions in application.js:

GetPageSettings – to retrieve our page settings from the DOM

SetPageSettings – to store our page settings in the DOM

function GetPageSettings() {
    return $(document).data("sgs.pagesettings");
}

function SetPageSettings(pageSettings) {
    $(document).data("sgs.pagesettings", pageSettings);
}

Let’s review the InitializeApplication function of our main application.js module. The core code consists of initializing a pageSettings dictionary and invoking our view mediators.

Let’s extract that part of the code into a new function named InitializeViewMediators:

function InitializeViewMediators() {
    if (typeof(console) != 'undefined' && console)
        console.info("InitializeViewMediators starting ...");

    // Initialize our page-wide settings
    var pageSettings = { defaultSavingsGoal: 500,
                         defaultSavingsMaxDuration: 6
    }

    // Save the page-wide settings
    SetPageSettings(pageSettings);

    // Create / launch our view mediator(s)
    sgs.mediator.savingsgoal.createViewMediator(pageSettings);
    sgs.mediator.coffeepricing.createViewMediator(pageSettings);
    sgs.mediator.consumptionscenarios.createViewMediator(pageSettings);
    sgs.mediator.savingsforecast.createViewMediator(pageSettings);

    if (typeof(console) != 'undefined' && console)
        console.info("InitializeViewMediators done ...");
}

Let’s add the code to InitializeApplication to attach our ViewLoader plugin to the document object and invoke InitializeViewMediators upon success (i.e. once all views have been loaded):

function InitializeApplication() {
    if (typeof(console) != 'undefined' && console)
        console.info("InitializeApplication starting ...");

    $(document).viewloader({
        logLevel: "debug",
        success: function (successfulResolution) {
            InitializeViewMediators();
        }
    );

    if (typeof(console) != 'undefined' && console)
        console.info("InitializeApplication done ...");
}

And let’s add some logging code in the error function to know when the ViewLoader is failing to load a given view.

function InitializeApplication() {
    // ...

    $(document).viewloader({
        // ...
        success: function (successfulResolution) {
            InitializeViewMediators();
        },
        error: function (failedResolution) {
            if (typeof(console) != 'undefined' && console) {
                console.error("index.html page failed to load");
            }
        }
    });

    // ...
}

Here is the visual depiction of how application.js coordinates with the ViewLoader:

Not so fast … if we run the app, we’ll get an error. This is due to the fact that the code from the createViewMediator function of our sgs.mediator.savingsgoal module is expecting the view to be available. But at this point in the execution the view as not yet been rendered. This leads us to one more refactoring.

4. Refactor The Savings Goal Mediator

The current implementation of the createViewMediator function of our sgs.mediator.savingsgoal module assumes that our view is in the DOM, but at the moment the ViewLoader plugin kicked off the InitializeViewMediators function, KnockoutJS has not been requested to apply bindings yet nor render any view templates.

So let’s refactor the code related to setting up the various data-bindings and invoking KnockoutJS into a new function named setupViewDataBindings:

sgs.mediator.savingsgoal.setupViewDataBindings = function() {
    // Declare the HTML element-level data bindings
    $("#savings-goal-amount").attr("data-bind","value: savingsGoalAmount");
    $("#savings-max-duration").attr("data-bind","value: savingsMaxDuration");
    $("#savings-target-per-month").attr("data-bind","text: savingsTargetPerMonthFormatted()");

    // Ask KnockoutJS to data-bind the view model to the view
    var viewNode = $('#savings-goal-view')[0];
    var viewModel = sgs.mediator.savingsgoal.getViewModel();
    ko.applyBindings(viewModel, viewNode);

    // Apply masking to the savings goal amount and max duration input fields
    viewModel.savingsGoalAmountMask.attach($("#savings-goal-amount")[0]);
    viewModel.savingsMaxDurationMask.attach($("#savings-max-duration")[0]); 

    // Initialize default for value models linked to masked fields
    var pageSettings = GetPageSettings();
    viewModel.savingsGoalAmount(pageSettings.defaultSavingsGoal || 0);
    viewModel.savingsMaxDuration(pageSettings.defaultSavingsMaxDuration || 0);

    // Subscribe to interesting value model changes
    viewModel.savingsTargetPerMonthFormatted.subscribe(function() {
        $("#savings-target-per-month")
            .effect('highlight', { color: 'LightGreen' }, 3000); // for 3 seconds
    });

    if (typeof(console) != 'undefined' && console)
        console.info("sgs.mediator.setupViewDataBindings done!");
}

Note: We had to add a new line to access the viewModel since it is now available in the DOM and accessible using the sgs.mediator.savingsgoal.getViewModel function. We also add to add a line to get the pageSettings using our new GetPageSettings function.

After having extracted some of the code the createViewMediator function consist of the following:

sgs.mediator.savingsgoal.createViewMediator = function (pageSettings, pageViewModel) {
    // Create the view Savings Goal view-specific view model
    var viewModel = sgs.model.savingsgoal.initializeViewModel(pageSettings);

    // Save the view model
    sgs.mediator.savingsgoal.setViewModel(viewModel);   

    if (typeof(console) != 'undefined' && console) console.info("sgs.mediator.savingsgoal ready!");
}

But since we added the savings-goal-view-container div to the page, we need to handle its data binding here. So let’s do that:

sgs.mediator.savingsgoal.createViewMediator = function (pageSettings, pageViewModel) {
    // Create the view Savings Goal view-specific view model
    var viewModel = sgs.model.savingsgoal.initializeViewModel(pageSettings);

    // Save the view model
    sgs.mediator.savingsgoal.setViewModel(viewModel);   

    // Ask KnockoutJS to data-bind the view model to the view
    var viewNode = $('#savings-goal-view-container')[0];
    ko.applyBindings(viewModel, viewNode);

    if (typeof(console) != 'undefined' && console) console.info ("sgs.mediator.savingsgoal ready!");
}

You probably noticed that there is no call yet to invoke our new setupViewDataBindings function! So where will it be invoked then? Well do you remember the comment about KnockoutJS exposing an afterRender callback function? (See back in KnockoutJS Databinding Support For Inline Templates.)

We’ll update the data-binding of savings-goal-view-container in our index.html, by assigning our new sgs.mediator.savingsgoal.setupViewDataBindings function to the afterRender attribute:

And now if we re-run our application, we’ll see in the console that setupViewDataBindings is being called while the savings-goal-view is being rendered, after the loading is successfully completed.

Here is an excerpt of the console:

InitializeApplication starting ...
viewloader.loadSourceForPartialView loading source for view: id=savings-goal-view-template src=scripts/view/index/_savings-goal.view.html
InitializeApplication done ...
viewloader.loadSourceForPartialView saving source in savings-goal-view-template
viewloader.loadAllPartialViews executing 'success' function
InitializeViewMediators starting ...
sgs.mediator.setupViewDataBindings done!
sgs.mediator.savingsgoal ready!
...
InitializeViewMediators done ...

We have successfully externalized the markup for the savings-goal-view!!!

In summary here is a diagram illustrating the page load processing flow:

5. Recap

Here is a quick recap of the steps we followed:

#	To Do	Area
1	Create An External Template For The savings-goal-view Create a _your.view.html file Cut the view markup from your .html and paste it in the .view.html	View
2	Refactor the savings-goal-view In Our Web Page Add a script tag with an id, a text/html type and point the source to the new .view.html Create a DIV container and add a data-bind with the template name (id)	View
3	Hookup jQuery ViewLoader In Our Main application.js Split the view mediators initialization code into a separate InitializeViewMeditors function Add $(document).viewloader({ // … }) to InitializeApplication Call InitializeViewMeditors from the success callback of viewloader	Application
4	Refactor The Savings Goal Mediator Create a new setupViewDataBindings function to create and apply data bindings inside the view Trim down createViewMediators to focus only on initializing and storing the view model and asking KnockoutJS to apply the bindings to the view container. Add an afterRender parameter to the template data-binding to instruct the template engine to invoke the setupViewDataBindings	View Mediator

6. Externalizing The Remaining Views

Now we just need to repeat the process on our remaining two views:

consumption-scenarios-view
savings-forecast-view

If you want to follow along with the source code changes, just get code for the tag corresponding to any particular step on the GitHub repository for the Savings Goal Simulator.

So What?

jQuery Template and jQuery ViewLoader allow you to structure and load views within a web page.

Externalizing your views makes your web pages more modular and easier to maintain, especially if you are working within a team as this allows you to assign different views (markup + code) to different individuals.

In the context of a “single page application” where you may have many views, these benefits are crucial to help you manage the complexity and allow you to grow the application organically / incrementally.

Another benefit of modularizing your views and view mediators will be that it will be easier to adapt and create different versions of the application for other channels, like a mobile web site or a mobile version of the application (using for example jQuery Mobile and PhoneGap).

References And Resources

jQuery Plugins

jQuery Template : http://api.jquery.com/category/plugins/templates/
jQuery ViewLoader : http://github.com/techarch/jquery-viewloader
jsRender + jsViews rendering engine : https://github.com/BorisMoore/jsviews
Mustache rendering engine : http://mustache.github.com/
Handlebars rendering engine : http://www.handlebarsjs.com/
jQuery ViewLoader rendering engine : https://github.com/techarch/jquery-viewloader

Miscellaneous

jQuery $.get : http://api.jquery.com/jQuery.get/
jQuery Deferred : http://api.jquery.com/category/deferred-object/
KnockoutJS afterRender : http://knockoutjs.com/documentation/template-binding.html#note4usingthe_option
Savings Goal Simulator : http://savings-goal-simulator.heroku.com/

My Other Related Posts:

Full Source Of The Savings Goal Simulator (KnockoutJS Demo)

The whole application is available on Github under techarch / savings-goal-simulator.

If you enjoyed this post, I would love it if you could check out mySkillsMap, my skills management app.

Creating Rich Interactive Web Apps With KnockOut.js – Part 3

techarch — Sun, 30 Oct 2011 13:44:33 +0000

Intro

In Part 1, we introduced the key concepts and patterns including KnockoutJS. In Part 2, we started to build the first increment of our Savings Goal Simulation rich web app. The objectives of this third tutorial are:

Build up the rest of the application
Gain more practice with View Models, View Mediators, and KnockoutJS
Incorporate some basic elements of usability

Here is the overall target structure of the application:

Building Our App Step-By-Step

Here is what the app will look like at the end of this tutorial:

Here is an outline of the approach:

#	To Do	Area
1	Create the Consumption Scenarios View	View
2	Create the Consumption Scenarios ViewModel	View Model
3	Create the Consumption Scenarios View Mediator	View Mediator
4	Link the Page and the View Mediator	Main App
5	Create the Coffee Pricing ViewModel	View Model
6	Create the Coffee Pricing ViewMediator	View Mediator
7	Link the Page and the Coffee Pricing View Mediator	Main App
8	Leveraging Independent View Models	View Model
9	Create the Savings Forecast View	View Mediator
10	Create the Savings Forecast ViewModel	View Model
11	Create the Savings Forecast View Mediator	View Mediator
12	Link the Page and the Savings Forecast View Mediator	Main App

1. Create the Consumption Scenarios View

In our index.html page, let’s add a second section tag to represent our second panel / view: the consumption-scenarios-view.The view will let us enter current habits and see how modifying these habits can yield savings counting towards our saving goal.

This is what the view will look like:

Let’s add a table with 3 columns, one for the dimension to capture and affect (e.g. drink size), one for current habits, and one for our proposed consumption:


	
	
			Weekly Coffee Consumption

			
				
					
						Coffee Options
						Current Habits
						Proposed Change
					
				

				
					
						Type:
						
						
					

					
						Size:
						
						
					

					
						Frequency:
						
						
					

					
						Drinks per Day:
						
						
					

					
						Cost Per Week:

Let’s fill the [Drink] Type row, consisting of sets of radio buttons for Regular, Latte, and Espresso, in both Current and Proposed columns:


	
		Type:
		
			
				
					Regular

				
					Latte

				
					Espresso

			
		
		
			
				
					Regular

				
					Latte

				
					Espresso

Let’s fill the [Drink] Size row, consisting of sets of radio buttons for Tall, Grande, and Venti, in both Current and Proposed columns:


	
	
		Size:
		
				
					
						Tall

					
						Grande

					
						Venti

				
		
		
				
					
						Tall

					
						Grande

					
						Venti

Let’s fill the [Drink] Frequency row, consisting of sets of radio buttons for Everyday, Monday-through-Friday, and Other (i.e. N days per week), in both Current and Proposed columns:


	
	
		Frequency:
		
			
				
					Everyday

				
					Mon-Fri

				
					Other:
					

			
		
		
			
				
					Everyday

				
					Mon-Fri

				
					Other:

Let’s fill the Drinks Per Day row consisting of an simple input field, in both Current and Proposed columns:


	
	
		Drinks per Day:

Let’s fill the Cost Per Week row consisting of


	
	
		Cost Per Week:

Let’s fill the Savings Per Week row consisting of


	
	
		Savings Per Week:
		
				&nsbsp;

2. Create the Consumption Scenarios ViewModel

In the ViewModels folder under the scripts folder, create a file named: sgs.model.consumption-scenarios.js.And let’s add a statement to load our new module in in our LAB.js section:

$LAB
	// ...
	.script("scripts/viewmodel/sgs.model.savings-goal.js").wait()
	.script("scripts/viewmodel/sgs.model.savings-goal.js").wait()
	.script("scripts/viewmediator/sgs.mediator.savings-goal.js").wait()
	.script("scripts/viewmodel/sgs.model.consumption-scenarios.js").wait()
	// ...

Let’s add the code snippet to lazy-create the namespace:

// Lazy initialize our namespace context: sgs.model.consumptionscenarios
if (typeof(sgs) == 'undefined') sgs = { }
if (typeof(sgs.model) == 'undefined') sgs.model = { }
if (typeof(sgs.model.consumptionscenarios) == 'undefined') sgs.model.consumptionscenarios = { }

Let’s create our initializeViewModel function to initialize the view model and its three value models:

currentConsumption will track our current coffee drinking habits
proposedConsumption will allow us to experiment to see how much we could save
savingsPerWeek will show us the difference between proposed and current costs and will be implemented as a dependent observable function
savingsPerMonth(self explanatory)

For now let’s just assign currentConsumption and proposedConsumption to a ko.observable(null) for now – we’ll change that later (once we create the needed sub-view model).

sgs.model.consumptionscenarios.initializeViewModel = function (pageSettings) {
	// We can use properties of the pageSettings as default values for any of our ValueModels
	// If pageSettings are not provided we'll initialize an empty object
	if (typeof(pageSettings) == 'undefined') var pageSettings = { }

	var viewModel = {
		currentConsumption: 	ko.observable(null),
		proposedConsumption: 	ko.observable(null)
	};

	// Stub implementation to be fully implemented later on
	viewModel.savingsPerWeek = ko.dependentObservable(function() {
		var result = 0;
		return result;
	}, viewModel);

	viewModel.savingsPerMonth = ko.dependentObservable(function() {
		var perMonth = this.savingsPerWeek() * 4;
		var result = Math.round(perMonth * 100) / 100;
		return result;
	}, viewModel);

	return viewModel;
}

We need a way to model our coffee consumption.
So we’ll create a new module file named sgs.model.coffee-consumption.js under scripts/viewmodel.
And let’s add a statement to load our new module in in our LAB.js section (right before consumption-scenarios):

$LAB
	// ...
	.script("scripts/viewmodel/sgs.model.coffee-consumption.js").wait()
	.script("scripts/viewmodel/sgs.model.consumption-scenarios.js").wait()
	// ...

Let’s add the code snippet to lazy-create the namespace:

// Lazy initialize our namespace context: sgs.model.coffeeconsumption
if (typeof(sgs) == 'undefined') sgs = { }
if (typeof(sgs.model) == 'undefined') sgs.model = { }
if (typeof(sgs.model.coffeeconsumption) == 'undefined') sgs.model.coffeeconsumption = { }

if (typeof(console) != 'undefined' && console) console.info("sgs.model.coffeeconsumption loading!");

Let’s create our initializeViewModel function to initialize the view model based on the pageSettins as well as a scenario name. We’ll have the following value models:

scenarioName – will be either Current or Proposed
drinkType
drinkSize
drinkFrequency
customFrequency
drinksPerDay

sgs.model.coffeeconsumption.initializeViewModel = function (pageSettings, scenarioName) {
	// We can use properties of the pageSettings as default values for any of our ValueModels
	// If pageSettings are not provided we'll initialize an empty object
	if (typeof(pageSettings) == 'undefined') var pageSettings = { }

	var viewModel = {
		scenarioName: 		ko.observable(scenarioName),
		drinkType: 			ko.observable("Regular"),
		drinkSize: 			ko.observable("Tall"),
		drinkFrequency: 	ko.observable("Everyday"),
		customFrequency:	ko.observable(1),
		drinksPerDay: 		ko.observable(1)
	}

	return viewModel;
}

Let’s add two dependent observable functions named drinkHasStandardSize (will allow us to later restrict the drink size options based on the drink type) and drinkDaysPerWeek (will allow to calculate the cost per week):

sgs.model.coffeeconsumption.initializeViewModel = function (pageSettings, scenarioName) {
	// ...

	var viewModel = {
		// ...
	}

	viewModel.drinkHasStandardSize = ko.dependentObservable(function() {
		return this.drinkType() != 'Espresso';
	}, viewModel);

	viewModel.drinkDaysPerWeek = ko.dependentObservable(function() {
		var count = 0;

		switch(this.drinkFrequency()) {
			case "Everyday":
				count = 7;
				break;

			case "WorkDays":
				count = 5;
				break;

			case "Other":
				count = this.customFrequency();
				break;
		}

		return count;
	}, viewModel);

	return viewModel;
}

I encourage you to test as you develop along , whether or not you are using a TDD or BDD approach (and framework like Jasmine). So refresh your browser and in the Firebug (or Webkit browser) console, instantiate a sgs.model.coffeeconsumption view model and invoke its drinkDaysPerWeek dependent observable like so:

var cs = sgs.model.coffeeconsumption.initializeViewModel()
cs.drinkDaysPerWeek()

You can also step through the code in the debugger if you really want to check out what happens.

Now let’s move on and add a stub for a third dependent observable function named: costPerWeek

sgs.model.coffeeconsumption.initializeViewModel = function (pageSettings, scenarioName) {
	// ...

	var viewModel = {
		// ...
	}

	// ...

	// Stub implementation to be fully implemented later on
	viewModel.costPerWeek = ko.dependentObservable(function() {
		var result = 0;
		return result;
	}, viewModel);

	return viewModel;
}

Later on we’ll come back to this view model and complete the stub implementation of the costPerWeek dependentObservable function to calculate the actual cost of the consumption model (based on pricing).

Now let’s go back to the initializeViewModel of our sgs.model.consumptionscenarios module and update the value model definitions to use custom instantiations of the sgs.model.coffeeconsumption view model so that the relationship between the two view models looks like this:

sgs.model.consumptionscenarios.initializeViewModel = function (pageSettings) {
	// We can use properties of the pageSettings as default values for any of our ValueModels
	// If pageSettings are not provided we'll initialize an empty object
	if (typeof(pageSettings) == 'undefined') var pageSettings = { }

	var current 	= sgs.model.coffeeconsumption.initializeViewModel (pageSettings, "Current");
	var proposed 	= sgs.model.coffeeconsumption.initializeViewModel (pageSettings, "Proposed");

	var viewModel = {
		currentConsumption: 	ko.observable(current),
		proposedConsumption: 	ko.observable(proposed)
	}

	// Stub implementation to be fully implemented later on
	viewModel.savingsPerWeek = ko.dependentObservable(function() {
		var result = 0;
		return result;
	}, viewModel);

	viewModel.savingsPerMonth = ko.dependentObservable(function() {
		var perMonth = this.savingsPerWeek() * 4;
		var result = Math.round(perMonth * 100) / 100;
		return result;
	}, viewModel);

	return viewModel;
}

So now you have implemented an example of hierarchical view model! Again I invite you to test it using the browser Javascript console and debugger.

3. Create the Consumption Scenarios View Mediator

Let’s tackle the view mediator and connect the parts!
In the ViewMediator folder under the scripts folder, create a file named: sgs.mediator.consumption-scenarios.js.
This is the module where we’ll place our data-binding logic as well as any code related to mediating access between
the page, the consumption scenario view, and its view model.

And let’s add a statement to load our new module in in our LAB.js section:

$LAB
	// ...
	.script("scripts/viewmodel/sgs.model.consumption-scenarios.js").wait()
	.script("scripts/viewmediator/sgs.mediator.consumption-scenarios.js").wait()
	// ...

Let’s define our namespace:

// Lazy initialize our namespace context: sgs.mediator.consumptionscenarios
if (typeof(sgs) == 'undefined') sgs = { }
if (typeof(sgs.mediator) == 'undefined') sgs.mediator = { }
if (typeof(sgs.mediator.consumptionscenarios) == 'undefined') sgs.mediator.consumptionscenarios = { }

if (typeof(console) != 'undefined' && console) console.info("sgs.mediator.consumptionscenarios loading!");

Let’s create our createViewMediator function (per our convention) which we will eventually invoke from the InitializeApplication method in application.js. The createViewMediator function will have 4 responsibilities:

Instantiate a view model for the consumption scenarios view
Declare the data-binding between the HTML elements of the view and their corresponding value models in the view model
Ask KnockoutJS to make the bindings effective (they will be live right after that)
Save off the view model so we can access it from other parts of the app

So let’s implement the first responsibility to instantiate a view model for the consumption scenario view (using the initializeViewModel function we just created in the consumption scenario view model module).

sgs.mediator.consumptionscenarios.createViewMediator = function (pageSettings) {
	// Create the view Consumption Scenarios view-specific view model
	var viewModel = sgs.model.consumptionscenarios.initializeViewModel(pageSettings);
}

Now let’s declare the data-bindings we need. For input elements we used the value attribute in our data-bind declaration, but since we have some radio buttons, it is the checked attribute of each radio button we need to target. Note that our binding will have a level of indirection via the currentConsumption value model, which is itself a view model with value models like drinkType. Here is what a snippet looks like for the radio buttons located inside the current-drink-type div:

sgs.mediator.consumptionscenarios.createViewMediator = function (pageSettings) {
	// Create the view Consumption Scenarios view-specific view model
	var viewModel = sgs.model.consumptionscenarios
		.initializeViewModel(pageSettings);

	// Declare the HTML element-level data bindings for the Current Habits column
	$("#current-drink-type input[type=radio]")
		.attr("data-bind",
				"checked: currentConsumption().drinkType");

Let’s finish up the rest of the bindings:

	// ...

	// Declare the HTML element-level data bindings for the Current Habits column
	$("#current-drink-type  input[type=radio]")
		.attr("data-bind","checked: currentConsumption().drinkType");
	$("#current-drink-size input[type=radio]")
		.attr("data-bind","checked: currentConsumption().drinkSize");
	$("#current-drink-frequency input[type=radio]")
		.attr("data-bind","checked: currentConsumption().drinkFrequency");
	$("#current-custom-frequency")
		.attr("data-bind","value: currentConsumption().customFrequency");
	$("#current-drinks-per-day")
		.attr("data-bind","value: currentConsumption().drinksPerDay");
	$("#current-cost-per-week")
		.attr("data-bind","text: currentConsumption().costPerWeek");

	// Declare the HTML element-level data bindings for the Proposed Change column
	$("#proposed-drink-type input[type=radio]")
		.attr("data-bind","checked: proposedConsumption().drinkType");
	$("#proposed-drink-size input[type=radio]")
		.attr("data-bind","checked: proposedConsumption().drinkSize");
	$("#proposed-drink-frequency input[type=radio]")
		.attr("data-bind","checked: proposedConsumption().drinkFrequency");
	$("#proposed-custom-frequency")
		.attr("data-bind","value: proposedConsumption().customFrequency");
	$("#proposed-drinks-per-day")
		.attr("data-bind","value: proposedConsumption().drinksPerDay");
	$("#proposed-cost-per-week")
		.attr("data-bind","text: proposedConsumption().costPerWeek");
	$("#savings-per-week")
		.attr("data-bind","text: savingsPerWeek");

	// ...

Let’s add a new kind of binding attribute: “enable“, which allow us to control whether or not the data-bound HTML element should be enabled. This is a very useful binding as it will simplify enabling/disabling rules a lot. Here we’ll use it to control whether or not the drink size radio buttons should be enabled, since an espresso does not typically come in a Tall / Grande / Venti size! (Wow imagine the buzz on Venti!)

Reminder: The syntax of data-bind in KnockoutJS is:

databind="attribute1: valueModel1, attribute2: valueModel2, etc." // comma-separated list

This means that we will need to comma-separate and concatenate our new “attribute: valueModel” binding pair at the end of our existing declaration for the “checked” attribute like so:

	// ...

	// Declare the HTML element-level data bindings for the Current Habits column
	// ...
	$("#current-drink-size input[type=radio]")
		.attr("data-bind","checked: currentConsumption().drinkSize " +
						", enable: currentConsumption().drinkHasStandardSize");
	// ...

	// Declare the HTML element-level data bindings for the Proposed Change column
	// ...
	$("#proposed-drink-size input[type=radio]")
		.attr("data-bind","checked: proposedConsumption().drinkSize" +
						", enable: proposedConsumption().drinkHasStandardSize");

	// ...

Caution: the name of the attribute is “enable” (not “enabled” – I have been bit by that many times)!

Now we’ll ask KnockoutJS to “apply”, i.e. register / enable our bindings.

sgs.mediator.consumptionscenarios.createViewMediator = function (pageSettings) {
	// ...

	// Ask KnockoutJS to data-bind the view model to the view
	var viewNode = $('#consumption-scenarios-view')[0];
	ko.applyBindings(viewModel, viewNode);
}

Now let’s add the 2 functions to store retrieve our consumption scenarios view model:

sgs.mediator.consumptionscenarios.getViewModel = function() {
	return $(document).data("sgs.model.consumptionscenarios.viewmodel");
}

sgs.mediator.consumptionscenarios.setViewModel = function(viewModel) {
	$(document).data("sgs.model.consumptionscenarios.viewmodel", viewModel);
}

Now we can call the setViewModel function from inside createViewMediator to save off our freshly-created view model.

sgs.mediator.consumptionscenarios.createViewMediator = function (pageSettings) {
	// ...

	// Save the view model
	sgs.mediator.consumptionscenarios.setViewModel(viewModel);	

	if (typeof(console) != 'undefined' && console) console.info("sgs.mediator.coffeeconsumption ready!");
}

If you want to test the mediator, just refresh the browser, and invoke the createViewMediator in the browser Javascript console like so:

sgs.mediator.consumptionscenarios.createViewMediator({})

You will then see the radio buttons get set to their default value. And clicking on the Espresso radio button should cause the Size radio buttons to become disabled.

4. Link the Page and the Consumptions Scenarios View Mediator

To instantiate our new mediator, we just need to add a call to the overall page InitializeApplication function (located in our scripts/application.js) to our consumption scenario createViewMediator function like so:

function InitializeApplication() {
	if (typeof(console) != 'undefined' && console)
		console.info("InitializeApplication starting ...");

	// Initialize our page-wide settings
	var pageSettings = { defaultSavingsGoal: 500 }

	// Create / launch our view mediator(s)
	sgs.mediator.savingsgoal.createViewMediator(pageSettings);
	sgs.mediator.consumptionscenarios.createViewMediator(pageSettings);

	if (typeof(console) != 'undefined' && console)
		console.info("InitializeApplication done ...");
}

So now you should be able to load your index.html page in Firefox with the Firebug console on and watch the debug statement and finally our new consumption scenarios view displays with our default values:

5. Create the Coffee Pricing ViewModel

Now we need a pricing engine! It needs to ake into account : the drink type and drink size. And we can apply frequency and drinks per day to calculate the cost. To keep logic encapsulated, let’s create a new module file in the scripts/viewmodel folder named sgs.model.coffee-pricing.js. The new module will be responsible for:

having a default example pricing list for the various coffee options
providing its own view model with a pricing value model
loading / saving its content to the browser local storage (using jStorage, a cross-browser HTML 5 local storage abstraction library)

Let’s add the code snippet to lazy-create the namespace:

// Lazy initialize our namespace context: sgs.model.coffeeconsumption
if (typeof(sgs) == 'undefined') sgs = { }
if (typeof(sgs.model) == 'undefined') sgs.model = { }
if (typeof(sgs.model.coffeepricing) == 'undefined') sgs.model.coffeepricing = { }

if (typeof(console) != 'undefined' && console) console.info("sgs.model.coffeepricing loading!");

Update the LAB.js section of the index.html page so we can load the new module (before sgs.model.coffee-consumption):

	$LAB
		// ...
		.script("scripts/viewmodel/sgs.model.coffee-pricing.js").wait()
		.script("scripts/viewmodel/sgs.model.coffee-consumption.js").wait()
		// ...

Now we’ll create an examplePricing function which will return a hash of key-value pairs where the key will be a composite of the coffee type and size, and the value an amount.

sgs.model.coffeepricing.examplePricing = function() {
	var priceList = {
		"Regular-Tall": 1.40,
		"Regular-Grande": 1.60,
		"Regular-Venti": 1.70,

		"Latte-Tall": 2.55,
		"Latte-Grande": 3.10,
		"Latte-Venti": 3.40,

		"Espresso": 1.75,
		"EspressoShot": 0.25
	}

	return priceList;
}

Now let’s define our initializeViewModel function with a place holder for the price list:

sgs.model.coffeepricing.initializeViewModel = function (pageSettings) {
	// We can use properties of the pageSettings as default values for any of our ValueModels
	// If pageSettings are not provided we'll initialize an empty object
	if (typeof(pageSettings) == 'undefined') var pageSettings = { }

	var priceList = { }
	var viewModel = {
		pricing: 		ko.observable(priceList)
	}

	return viewModel;
}

Ok, now we want to check if we have a price list in local storage and lazy-initialize it otherwise. We’ll encapsulate the logic in a function named: getPriceList. We’ll try to retrieve the “coffee-price-list” using $.jStorage.get(key) API:

sgs.model.coffeepricing.getPriceList = function () {
	// Check if we have ever stored the price list locally
	var priceList = $.jStorage.get("coffee-price-list");

	if (priceList == null) {
		// If not create an example
		priceList = sgs.model.coffeepricing.examplePricing();

		// Save it off
		$.jStorage.set("coffee-price-list", priceList);
	}

	return priceList;
}

So now we can edit our in initializeViewModel function and plug in the getPriceList for the initialization of the pricing value model:

sgs.model.coffeepricing.initializeViewModel = function (pageSettings) {
	// We can use properties of the pageSettings as default values for any of our ValueModels
	// If pageSettings are not provided we'll initialize an empty object
	if (typeof(pageSettings) == 'undefined') var pageSettings = { }

	// Lazy-initialize the price list
	var priceList = sgs.model.coffeepricing.getPriceList();

	var viewModel = {
		pricing: 		ko.observable(priceList)
	}

	return viewModel;
}

To encapsulate pricing data requests, let’s add a “normal” function (i.e. not an dependent observable) named getCoffeeBeveragePrice to our view model:

sgs.model.coffeepricing.initializeViewModel = function (pageSettings) {
	// ...

	viewModel.getCoffeeBeveragePrice = function (drinkType, drinkSize) {
		var key = drinkType;

		if (drinkType != 'Espresso' && drinkSize) {
			key += '-' + drinkSize;
		}

		var price = viewModel.pricing()[key];
		return price;
	}

	return viewModel;
}

Once reloading the index.html page, you should be able to experiment with jStorage. To see all keys stored with jStorage (should be an empty array initially):

$.jStorage.index()

Now, let’s make a call to sgs.model.coffeepricing.getPriceList(). This will lazy-initialize the price list and store it. So when asking for the jStorage index a second time the console should display an array with our “coffee-price-list” key. And we can access the value for our key using:

sgs.model.coffeepricing.getPriceList()
$.jStorage.index()
$.jStorage.get("coffee-price-list")

6. Create the Coffee Pricing ViewMediator

In the Viewmediator folder under the scripts folder, create a file named: sgs.mediator.coffee-pricing.js. This is the module where we’ll place our data-binding logic as well as any code related to mediating access between the page, a future pricing editing view, and its view model.
And let’s add a statement to load our new module in in our LAB.js section:

$LAB
	// ...
	.script("scripts/viewmodel/sgs.model.coffee-pricing.js").wait()
	.script("scripts/viewmediator/sgs.mediator.coffee-pricing.js").wait()
	// ...

Let’s define our namespace:

// Lazy initialize our namespace context: sgs.mediator.coffeepricing
if (typeof(sgs) == 'undefined') sgs = { }
if (typeof(sgs.mediator) == 'undefined') sgs.mediator = { }
if (typeof(sgs.mediator.coffeepricing) == 'undefined') sgs.mediator.coffeepricing = { }

if (typeof(console) != 'undefined' && console) console.info("sgs.mediator.coffeepricing loading!");

Instantiate a view model for the future pricing editor view
Ask KnockoutJS to make the bindings effective (they will be live right after that)
Save off the view model so we can access it from other parts of the app

Note: this mediator will not need to setup any data-bindings with the view, since we are not planning on displaying the pricing. However, the consumption scenario mediator will collaborate with it in order to access its pricing view model.

So let’s implement the first responsibility to instantiate a view model
(using the initializeViewModel function we just created in the coffee pricing view model module).

sgs.mediator.coffeepricing.createViewMediator = function (pageSettings) {
	// Create the view Pricing Editor view-specific view model
	var viewModel = sgs.model.coffeepricing.initializeViewModel(pageSettings);
}

Now let’s add the 2 functions to store retrieve our coffee pricing view model:

sgs.mediator.coffeepricing.getViewModel = function() {
	return $(document).data("sgs.model.coffeepricing.viewmodel");
}

sgs.mediator.coffeepricing.setViewModel = function(viewModel) {
	$(document).data("sgs.model.coffeepricing.viewmodel", viewModel);
}

Now we can use the setViewModel function inside createViewMediator to save off our freshly-created view model.

sgs.mediator.coffeepricing.createViewMediator = function (pageSettings) {
	// ...

	// Save the view model
	sgs.mediator.coffeepricing.setViewModel(viewModel);	

	if (typeof(console) != 'undefined' && console) console.info("sgs.mediator.coffeepricing ready!");
}

7. Link the Page and the Coffee Pricing View Mediator

To instantiate our new mediator, we just need to add a call to the overall page InitializeApplication function (located in our scripts/application.js) to our coffee pricing createViewMediator function like so:

function InitializeApplication() {
	if (typeof(console) != 'undefined' && console)
		console.info("InitializeApplication starting ...");

	// Initialize our page-wide settings
	var pageSettings = { defaultSavingsGoal: 500 }

	// Create / launch our view mediator(s)
	sgs.mediator.savingsgoal.createViewMediator(pageSettings);
	sgs.mediator.coffeepricing.createViewMediator(pageSettings);
	sgs.mediator.consumptionscenarios.createViewMediator(pageSettings);

	if (typeof(console) != 'undefined' && console)
		console.info("InitializeApplication done ...");
}

8. Leveraging Independent View Models

At this point we have created the consumption, scenarios, and pricing view models, but we have not yet “connected” all the parts to allow for the costPerWeek value model of coffeeconsumption to work. Before we proceed let’s review a few requirements and guiding principles:

The consumptionscenarios view model knows about the current and proposed coffee consumptions
The coffeeconsumption view model has the costPerWeek dependent observable function
The coffeepricing view model has the pricing
The coffeepricing view mediator manages access to its view model
We want to keep the view models from knowing about the mediators
Over time, we may want to test different pricing models in each scenario

So to maintain isolation but yet gain some flexibility we will:

Add a pricing value model to the coffeeconsumption view model – this way costPerWeek will have access to it
Add a pricing value model to the consumptionscenarios view model – this way it can pass it on each of the current and proposed consumptions models
Add a subscription to the pricing change in the consumptionscenarios view model so we can update the pricing of the current and proposed consumptions models
Have the consumption-scenario and coffee pricing view mediators share the pricing view model

Here is what the relationship between the various mediators and model will look like:

First, let’s add a pricing value model to the coffeeconsumption view model (located in scripts/viewmodel/sgs.model.coffeeconsumption.js):

sgs.model.coffeeconsumption.initializeViewModel = function (pageSettings, scenarioName) {
	// ...

	var viewModel = {
		pricing: 		ko.observable(null),
		scenarioName: 	ko.observable(scenarioName),
		// ...
	}

	// ...
}

Second, let’s add a pricing value model to the consumptionscenarios view model (located in scripts/viewmodel/sgs.model.consumptionscenarios.js)

sgs.model.consumptionscenarios.initializeViewModel = function (pageSettings) {
	// ...

	var viewModel = {
		pricing: 				ko.observable(null),
		currentConsumption: 	ko.observable(current),
		proposedConsumption: 	ko.observable(proposed)
	}

	// ...
}

Third, let’s add a subscription to pricing value model so we can re-act to pricing model changes and pass the new pricing down to our 2 consumption models:

sgs.model.consumptionscenarios.initializeViewModel = function (pageSettings) {
	// ...

	viewModel.pricing.subscribe(function(newPricing) {
		viewModel.currentConsumption().pricing(newPricing);
		viewModel.proposedConsumption().pricing(newPricing);
	});

	// ...
}

Fourth, let’s have the consumption-scenario view mediator set the pricing based on the view model of the coffee pricing view mediator:

sgs.mediator.consumptionscenarios.createViewMediator = function (pageSettings) {
	// ...

	// Save the view model
	sgs.mediator.consumptionscenarios.setViewModel(viewModel);	

	// Set the pricing based on the Coffee Pricing view model
	var priceList = sgs.mediator.coffeepricing.getViewModel();
	viewModel.pricing(priceList);

	// ...
}

So now we have the bits in place to fully implement the costPerWeek function of the coffeeconsumption view model. (Remember we had just put in a stub implementation returning 0 in step “2. Create the Consumption Scenarios ViewModel”). It’s a matter of performing the calculations like so:

sgs.model.coffeeconsumption.initializeViewModel = function (pageSettings, scenarioName) {
	// ...

	viewModel.costPerWeek = ko.dependentObservable(function() {
		// Get the base price
		if (this.pricing() == null) {
			return 0;
		}

		var basePrice 	= this.pricing().getCoffeeBeveragePrice(this.drinkType(), this.drinkSize());
		var dailyCost 	= basePrice * this.drinksPerDay();
		var weeklyCost	= dailyCost * this.drinkDaysPerWeek();
		var result 		= Math.round(weeklyCost * 100) / 100;

		return result;
	}, viewModel);

	return viewModel;
}

And finally we can go back and finish the implementation of the savingsPerWeek function in the consumptionscenarios view model. (Remember we had just put in a stub implementation returning 0 in step “2. Create the Consumption Scenarios ViewModel”)

sgs.model.consumptionscenarios.initializeViewModel = function (pageSettings) {
	// ...

	viewModel.savingsPerWeek = ko.dependentObservable(function() {
		var costDifference = this.currentConsumption().costPerWeek() - this.proposedConsumption().costPerWeek();
		var result = Math.round(costDifference * 100) / 100;
		return result;
	}, viewModel);

	// ...

	return viewModel;
}

Now we’re ready to refresh the index.html page, select Grande Latte under Current Habits and Tall Regular under Proposed Changes and you should see the costs update as well as the savings. We now have a functioning Weekly Coffee Consumption panel! :-)

I will leave the following usability additions for you to do:

Formatting of the costs and saving amounts (dependent observables and Accounting.js – see Part 1 ToDo #9 – Applying Formatting Rules)
Add visual feedback (using the jQuery highlight effect) for the costs and savings fields see Part 1 ToDo #10 – Applying Visual Feedback Clues
Overall styling

9. Create the Savings Forecast View

In our index.html page, let’s add a second section tag to represent our third panel / view:
the savings-forecast-view.
The view will help us compare projected savings against our goal.

This is what the view will look like:

The view will have three pairs of labels and spans to show calculated values for:

Savings forecast per month
Forecast variance from the target monthly savings goal
Forecasted number of months to achieve the savings goal

			Savings Forecast Per Month:
			


			Forecast Variance:
			


			Months To Savings Goal:

10. Create the Savings Forecast ViewModel

In the ViewModels folder under the scripts folder, create a file named: sgs.model.savings-forecast.js.
And let’s add a statement to load our new module in in our LAB.js section:

$LAB
	// ...
	.script("scripts/viewmodel/sgs.model.savings-forecast.js").wait()
	// ...

Let’s add the code snippet to lazy-create the namespace:

// Lazy initialize our namespace context: sgs.model.savingsforecast
if (typeof(sgs) == 'undefined') sgs = { }
if (typeof(sgs.model) == 'undefined') sgs.model = { }
if (typeof(sgs.model.savingsforecast) == 'undefined') sgs.model.savingsforecast = { }

if (typeof(console) != 'undefined' && console) console.info("sgs.model.savingsforecast loading!");

Let’s create our initializeViewModel function to initialize the view model.
We need two dependent observable functions:

forecastVariancePerMonth will allow us to experiment to see how much we could save
timeToGoalInMonths will show us the difference between proposed and current costs and will be implemented as a dependent observable function

sgs.model.savingsforecast.initializeViewModel = function (pageSettings) {
	// We can use properties of the pageSettings as default values for any of our ValueModels
	// If pageSettings are not provided we'll initialize an empty object
	if (typeof(pageSettings) == 'undefined') var pageSettings = { }

	var viewModel = {
	};	

	viewModel.forecastVariancePerMonth = ko.dependentObservable(function() {
		// TBD
	}, viewModel);

	viewModel.timeToGoalInMonths = ko.dependentObservable(function() {
		// TBD
	}, viewModel);

	return viewModel;
}

Design Note: in this series of tutorial I have promoted the idea of decoupling all views, models, and mediators (as possible) as it makes the application more modular and it is easier to test all parts independently. So for this view model, instead of requesting the value models from other mediators namely savingsGoalAmount, savingsTargetPerMonth and savingsPerMonth, we will create dedicated value models which will later synchronize with using subscriptions in our mediators – since it is ok for the mediators to collaborate.

sgs.model.savingsforecast.initializeViewModel = function (pageSettings) {
	// ...

	var viewModel = {
		savingsGoalAmount: ko.observable(0),
		savingsTargetPerMonth: ko.observable(0),
		savingsPerMonth: ko.observable(0)
	};	

	// ...

	return viewModel;
}

Let’s flesh-out our calculations:

sgs.model.savingsforecast.initializeViewModel = function (pageSettings) {
	// ...	

	viewModel.forecastVariancePerMonth = ko.dependentObservable(function() {
		var variance = this.savingsPerMonth() - this.savingsTargetPerMonth();
		var result = Math.round(variance * 100) / 100;
		return result;
	}, viewModel);

	viewModel.timeToGoalInMonths = ko.dependentObservable(function() {
		var timeToGoal = 0;
		var savingsPerMonth = this.savingsPerMonth();
		var savingsGoalAmount = this.savingsGoalAmount();

		if (savingsPerMonth != 0) {
			timeToGoal = savingsGoalAmount / savingsPerMonth;
		}
	}, viewModel);

	// ...
}

11. Create the Savings Forecast View Mediator

In the Viewmediator folder under the scripts folder, create a file named: sgs.mediator.savings-forecast.js. This is the module where we’ll place our data-binding logic as well as any code related to mediating access between the page, the consumption scenario view, and its view model.
And let’s add a statement to load our new module in in our LAB.js section:

$LAB
	// ...
	.script("scripts/viewmodel/sgs.model.savings-forecast.js").wait()
	.script("scripts/viewmediator/sgs.mediator.savings-forecast.js").wait()
	// ...

Let’s define our namespace:

// Lazy initialize our namespace context: sgs.mediator.savingsforecast
if (typeof(sgs) == 'undefined') sgs = { }
if (typeof(sgs.mediator) == 'undefined') sgs.mediator = { }
if (typeof(sgs.mediator.savingsforecast) == 'undefined') sgs.mediator.savingsforecast = { }

if (typeof(console) != 'undefined' && console) console.info("sgs.mediator.savingsforecast loading!");

Instantiate a view model for the savings forecast view
Establish subscriptions for various value models to keep the main view model synchronized
Declare the data-binding between the HTML elements of the view and their corresponding value models in the view model
Ask KnockoutJS to make the bindings effective (they will be live right after that)
Save off the view model so we can access it from other parts of the app

sgs.mediator.savingsforecast.createViewMediator = function (pageSettings) {
	// Create the view Savings Forecast view-specific view model
	var viewModel = sgs.model.savingsforecast.initializeViewModel(pageSettings);
}

Now we need to establish 3 subscriptions so that we can keep our saving forecast view model in synch with value models from the savings goal and consumption scenarios view models. Here is a graphical depiction of what we need:

To make this happen we need the savingsforecast mediator to request specific value models from the view models of the savingsgoal and consumptionsscenarios mediators:

sgs.mediator.savingsforecast.createViewMediator = function (pageSettings) {
	// ...

	// Subscribe to changes in savingsGoalAmount and savingsTargetPerMonth
	// to synchronize our own equivalent value models
	var savingsGoalModel = sgs.mediator.savingsgoal.getViewModel();

	// Initialize the current savingsGoalAmount
	viewModel.savingsGoalAmount(savingsGoalModel.savingsGoalAmount());

	savingsGoalModel.savingsGoalAmount.subscribe(function(newValue) {
		viewModel.savingsGoalAmount(newValue);
	});

	savingsGoalModel.savingsTargetPerMonth.subscribe(function(newValue) {
		viewModel.savingsTargetPerMonth(newValue);
	});

	// Subscribe to changes in savingsPerMonth to synchronize our own equivalent value model
	var consumptionscenariosModel = sgs.mediator.consumptionscenarios.getViewModel();
	consumptionscenariosModel.savingsPerMonth.subscribe(function(newValue) {
		viewModel.savingsPerMonth(newValue);
	});

	// ...
}

Now let’s declare the data-bindings we need.

sgs.mediator.savingsforecast.createViewMediator = function (pageSettings) {
	// Create the view Savings Forecast view-specific view model
	var viewModel = sgs.model.savingsforecast
		.initializeViewModel(pageSettings);

	// Declare the HTML element-level data bindings
	$("#savings-forecast-per-month")
		.attr("data-bind","text: savingsPerMonth");
	$("#forecast-variance-per-month")
		.attr("data-bind","text: forecastVariancePerMonth");
	$("#time-to-goal-in-months")
		.attr("data-bind","text: timeToGoalInMonths");

	// ...

Now we’ll ask KnockoutJS to “apply”, i.e. register / enable our bindings.

sgs.mediator.savingsforecast.createViewMediator = function (pageSettings) {
	// ...

	// Ask KnockoutJS to data-bind the view model to the view
	var viewNode = $('#savings-forecast-view')[0];
	ko.applyBindings(viewModel, viewNode);
}

Now let’s add the 2 functions to store retrieve our savings forecast view model:

sgs.mediator.savingsforecast.getViewModel = function() {
	return $(document).data("sgs.model.savingsforecast.viewmodel");
}

sgs.mediator.savingsforecast.setViewModel = function(viewModel) {
	$(document).data("sgs.model.savingsforecast.viewmodel", viewModel);
}

Now we can use the setViewModel function inside createViewMediator to save off our freshly-created view model.

sgs.mediator.savingsforecast.createViewMediator = function (pageSettings) {
	// ...

	// Save the view model
	sgs.mediator.savingsforecast.setViewModel(viewModel);	

	if (typeof(console) != 'undefined' && console) console.info("sgs.mediator.savingsforecast ready!");
}

Again you can try your new mediator using the browser console:

sgs.mediator.savingsforecast.createViewMediator({})

Playing with the simulation should now update the savings-forecast view.

12. Link the Page and the Savings Forecast View Mediator

function InitializeApplication() {
	if (typeof(console) != 'undefined' && console)
		console.info("InitializeApplication starting ...");

	// Initialize our page-wide settings
	var pageSettings = { defaultSavingsGoal: 500 }

	// Create / launch our view mediator(s)
	sgs.mediator.savingsgoal.createViewMediator(pageSettings);
	sgs.mediator.coffeepricing.createViewMediator(pageSettings);
	sgs.mediator.consumptionscenarios.createViewMediator(pageSettings);
	sgs.mediator.savingsforecast.createViewMediator(pageSettings);

	if (typeof(console) != 'undefined' && console)
		console.info("InitializeApplication done ...");
}

Now you can refresh your page and should be able to see the new savings forecast view update as you experiment!

Overall Recap

In this part 3 of the tutorial we have added quite a bit more functionality and complexity. Hopefully the modularization, separation into different files and folders, the namespacing, and various patterns are now starting to reveal their purpose and value. ;-)
So here is a quick recap of the steps we followed:

#	To Do	Area (Module)
1	Create the Consumption Scenarios View	View
2	Create the Consumption Scenarios ViewModel	View Model
3	Create the Consumption Scenarios View Mediator	View Mediator
4	Link the Page and the View Mediator	Main App
5	Create the Coffee Pricing ViewModel	View Model
6	Create the Coffee Pricing ViewMediator	View Mediator
7	Link the Page and the Coffee Pricing View Mediator	Main App
8	Leveraging Independent View Models	View Model
9	Create the Savings Forecast View	View Mediator
10	Create the Savings Forecast ViewModel	View Model
11	Create the Savings Forecast View Mediator	View Mediator
12	Link the Page and the Savings Forecast View Mediator	Main App

So What?

This part 3 gave you a lot more practice with the core patterns and also showed you the following:

Create hierarchical view models
Setup custom subscriptions to keep independent view models synchronized
Configure multiple attributes inside a data-bind declaration (e.g. checked and enabled)
Leverage jStorage for local browser data caching

If we step back and look at the modularization of our application so far, we’ll notice that although our models and view mediators are modular, the actual index.html web page has become larger and is not modular at all. Wouldn’t it be nice if we could extract each of our views into external modules? Well, this is exactly what part 4 will cover!

Leveraging jQuery templates
Extracting views into templates (and in separate files)
… and more!

So stay tuned!

References and Resources

Patterns

Frameworks And Blogs

Javascript Loaders

jQuery Plugins

Other Javascript Libraries

Javascript Test Frameworks

My Other Related Posts:

Full Source Of The Savings Goal Simulator (KnockoutJS Demo)

The whole application is available on Github under techarch / savings-goal-simulator.

If you enjoyed this post, I would love it if you could check out mySkillsMap, my skills management app.

Creating Rich Interactive Web Apps With KnockOut.js – Part 2

techarch — Tue, 18 Oct 2011 03:29:18 +0000

Intro

In Part 1 of “Creating Rich Interactive Web Apps With KnockOut.js”, I reviewed some of the key patterns you need to consider such as: MVC, Model View – ViewModel, Observer, Publish Subscribe, Value Model, Data Binding.

In this second post, we will cover the following topics while creating a fun app:

Architecting our application so it can easily be extended over time
Splitting the logic according to separations of concerns
Incorporating rudimentary elements of usability

For The Price Of N Cups of Coffee …

To illustrate the various concepts, we’ll create a simulator application to figure out how we can tweak our coffee consumption habits to save a given amount of money over a period of time.

Note: You can try the app at: savings-goal-simulator.heroku.com and inspect / play with it in Firebug. The full source is also available on Github under techarch / savings-goal-simulator.

Building Our App Step-By-Step

Here is an outline of the approach:

#	To Do	Area
1	Create a Shell Application	Main app
2	Organize our Application Code	Main App
3	Create the Savings Goal View	View
4	Create the Savings Goal ViewModel	View Model
5	Create the Savings Goal View Mediator	View Mediator
6	Link the Page and the View Mediator	Main App
7	Apply Data Masking Business Rules	View Mediator
8	Apply Custom Masking Rules	View Mediator
9	Applying Formatting Rules	View Mediator
10	Providing Visual Feedback Cues	View Mediator

Thanks to Susan Potter‘s suggestion of tagging the source code on Github, you can download the source corresponding to the application as of the end of each “todo” step! You can find the list of tags here.

1. Create a Shell Application

Note: In this tutorial we will de-emphasize the server framework side and focus on browser considerations.

So let’s start:

Create a root folder for our application named savings-goal-simulator
Create a file named index.html for our main page
Create a folder for our Javascript files named scripts
Create a sub-folder under scripts for our vendor Javascript libraries named vendor
Add the basic markup for a page in index.html

Ok, now we’re ready to add our key external Javascript libraries.
Here is the basic minimum we’ll need with a quick rationale as of why they will help us:

Library	Purpose / Rationale
Modernizr	Detects HTML 5 support and provide IE shims
jQuery	Main foundation (do I need to say more :-) ?!)
jQuery UI	Prefabricated UI super-elements like tabs, accordions, sliders, etc.
jQuery Cookies	Easy management of cookies
jQuery HotKeys	Handling of keyboard shortcuts
jQuery Masked Input	Allow creation of custom input masks
jQuery Validate	Validation framework
Accounting.js	Allow formatting currency amounts
CurrencyMaskJS	Allow masked input of currency amounts
jStorage	Wrapper for local storage APIs

If we want to start authoring HTML 5 semantic pages, Modernizr is a library which can facilitate detection of specific HTML5 and CSS3 features. But it also shines for Internet Explorer versions earlier than 9 by plugging in “shims“, i.e. fake HTML elements in the DOM, named after the new HTML5 missing elements, making it possible to use tags likeheader, footer, section, etc. and styling them too.

You will need to create your own custom version of Modernizr based on the features you need. This will ensure the smallest most effective script for your situation.

For our app, I chose to only include the “HTML5 Shim/IEPP” and the “CSS classes” – see this download configuration. I renamed the resulted file as modernizr.custom.min.js and placed it in the scripts/vendor folder.
So we’ll need to include the script for Modernizr right at the beginning our our HEAD section.

For performance reasons, we’ll use a Javascript loader (see available options further on) to ensure the Javascript libraries we’ll need can be loaded asynchronously, in parallel, and not block the execution of our page load.
For this app, I chose LABjs as it is specializes only on loading and is commonly used.
But note that you could use some of the conditional loading features of Modernizr, called yepnope.
I chose to keep things minimal for our app. ;-)

Starting from a basic HTML page, let’s add a script reference to lab.js below our modernizr script, and then let’s define the order in which we want to load our libraries.
We’ll add a call to wait() if we want the execution of the actual code to be order-dependent:

You will notice that I am assuming a specific directory structure for our locally hosted Javascript code

scripts is the root of all .js files

Vendor will host external vendor libraries not available on a CDN.

Having all external JS libraries in a dedicated folder will keep our directory structure clean.
ViewMediator will include Javascript code mediating interactions between Views and ViewModels
ViewModel will include our ViewModel-specific Javascript code
application.js will be the main application .js file with an InitializeApplication function (called from our $LAB configuration)

At this point go ahead and create the same folder structure and download the needed Javascript libraries for the Vendor folder.
You can use the links in the External Javascript Libraries table above.

And create the application.js file under the root of the scripts folder, and let’s provide a minimal implementation for now:

function InitializeApplication() {
	if (typeof(console) != 'undefined' && console)
		console.info("InitializeApplication starting ...");
}

If you run the application you should see the informational message being displayed in the console.
And in Firefox Firebug, or on a WebKit browser you should see the parallel loading of the scripts.

For our CSS, let’s create a folder named css in which we’ll extract the custom-theme folder from our jQuery UI download.

We’ll also create an application.css file for our application-specific styles.

2. Organize our Application Code

Since our application will very modular and encompass many functions or classes,
we’ll establish a namespace to provide some structure and avoid function name clashes.
You can read more about how to implement namespaces in Javascript in the following two articles:

Elegant Code – Namespaces

StackOverflow “Javascript Namespace Declaration”

For this app, we’ll use sgs (for savings goal simulator) as a prefix,
followed by either model or mediator for ViewModel and ViewMediator respectively.
To keep our markup free of Javascript logic, we’ll organize the application code in the following folders:

application.js will contain only logic to initialize / setup the views and viewmodels
ViewModel – this folder will contain several files:
- sgs.model.common.js for reusable logic across all types of ViewModels
- one file for the page-level view model – e.g. sgs.model.index.js
- one file for each view-specific view model – e.g. sgs.model.savings-goal.js –
ViewMediator – this folder will contain several files:
- sgs.mediator.common.js for reusable logic across all view mediators
- one file for the page-level view mediator – e.g. sgs.mediator.index.js
- one file for each view-specific view mediator – e.g. sgs.mediator.savings-goal.js –

So at this point, create the folder structure described above as well as stub content for sgs.model.common.js and sgs.model.common.js (they can remain empty for now). And let’s update the LAB.js section to load these 2 files (before application.js):


	
	$LAB
		// ...
		.script("scripts/viewmodel/sgs.model.common.js")
		.script("scripts/viewmediator/sgs.mediator.common.js")
		.script("scripts/application.js").wait(function(){
			// When ALL scripts have been loaded AND executed:
			InitializeApplication();
		});

Here is a quick synopsis of the architecture for the first increment of our app:

3. Create the Savings Goal View

Now that we have a minimal shell in index.html,
let’s add a section tag to represent our first panel / view: the savings-goal-view.
The view will let us enter a savings goal amout and a maximum number of months.

Now we can add the two input elements (savings-goal-amount and savings-max-duration).
And we’ll have a span to display the calculated (derived) savings-target-per-month. This is what the view will look like:

Important Note: In this tutorial, instead of “inlining” the data-binding declaration with the view model inside the markup (like you will see in the KnockoutJS site or on any other simple tutorials), I am proposing a more “unobtrusive” approach consisting of keeping the markup pure and explicitly defining data-bindings separately later (in the view mediator which we’ll see soon in the next section).


	Savings Goal Amount:
	


	Savings Max Duration (In Months):
	


	Savings Target Per Month:

At some point in the future, once the number of views increases beyond a couple, we’ll externalize our views as individual [jQuery] template files – but we’ll see the approach in detail later.

Note: as we go along in the tutorial, I will not cover the CSS styling explicitly but you can always get the CSS when downloading the source based on the tag for a given step. Example: tag: part2-todo-2.zip (also available in tar.gz form). Look under for css/application.css

4. Create the Savings Goal ViewModel

If you have not yet created the ViewModels folder under the scripts folder, do that now. And then create a file named: sgs.model.savings-goal.js.

Here is a diagram summarizing what we’re about to implement:

As we indicated earlier, we’ll use namespaces to structure our code and avoid name collisions with other libraries.
There are various approaches for namespacing code in Javascript, some uses object literals, and some use functions as containers for our functions. Elijah Manor has a great summary highlighting the pros and cons of the various approaches.

For our needs and to make it easy to extend and edit our namespace we’ll use the object literals.
To lazy initialize our namespace hierarchy let’s add the following snippet, which checks if each node in our namespace exists and creates it if it is not yet defined.

// Lazy initialize our namespace context: sgs.model.savingsgoal
if (typeof(sgs) == 'undefined') sgs = { }
if (typeof(sgs.model) == 'undefined') sgs.model = { }
if (typeof(sgs.model.savingsgoal) == 'undefined') sgs.model.savingsgoal = { }

Now we can create functions prefixed by our namespace such as for e.g. the function to initialize the view model and its two value models:

sgs.model.savingsgoal.initializeViewModel = function (pageSettings) {
	// We can use properties of the pageSettings as default values for any of our ValueModels
	// If pageSettings are not provided we'll initialize an empty object
	if (typeof(pageSettings) == 'undefined') var pageSettings = { }

	var viewModel = {
		savingsGoalAmount: ko.observable(pageSettings.defaultSavingsGoal || 0), // dollars
		savingsMaxDuration: ko.observable(6), // months
	};

	return viewModel;
}

So our viewModel is basically an object literal (hash) where each property value is a value model,
implemented as KnockoutJS observable, essentially a function acting as an interceptor for a value. Everytime the function is acting as a setter, the interceptor notifies all observers (subscribers) of the value change.

Now let’s add a derived function (a.k.a. a dependent observable in KnockoutJS-speak) named savingsTargetPerMonth:

sgs.model.savingsgoal.initializeViewModel = function (pageSettings) {
	// We can use properties of the pageSettings as default values for any of our ValueModels
	// If pageSettings are not provided we'll initialize an empty object
	if (typeof(pageSettings) == 'undefined') var pageSettings = { }

	var viewModel = {
		savingsGoalAmount: ko.observable(pageSettings.defaultSavingsGoal || 0), // dollars
		savingsMaxDuration: ko.observable(6), // months
	};

	viewModel.savingsTargetPerMonth = ko.dependentObservable(function() {
		var result = 0;
		if (this.savingsMaxDuration() > 0) {
			result = this.savingsGoalAmount() / this.savingsMaxDuration();
		}
		return result;
	}, viewModel);

	return viewModel;
}

Note that ko.dependentObservable takes a function as a parameter as you would expect, but can also take a second optional parameter used to define the meaning of this inside the derived function. Typically we always pass the variable containing our viewModel.

Over time we can add more business logic to our sgs.mode.savingsgoal module.

5. Create the Savings Goal View Mediator

If you have not yet created the ViewMediators folder under the scripts folder, do that now. And then create a file named: sgs.mediator.savings-goal.js.
This is the module where we’ll place our data-binding logic as well as any code related to mediating access between the page, the savings goal view, and its view model.

Here is a diagram summarizing what we’re about to implement:

Let’s define our namespace:

// Lazy initialize our namespace context: sgs.mediator.savingsgoal
if (typeof(sgs) == 'undefined') sgs = { }
if (typeof(sgs.mediator) == 'undefined') sgs.mediator = { }
if (typeof(sgs.mediator.savingsgoal) == 'undefined') sgs.mediator.savingsgoal = { }

if (typeof(console) != 'undefined' && console) console.info("sgs.mediator.savingsgoal loading!");

Now as a convention, let’s create a new function for our mediator named createViewMediator
which we will eventually invoke from the InitializeApplication method in application.js.

The createViewMediator function will have 3 responsibilities:

Instantiate a view model for the savings goal view
Declare the data-binding between the HTML elements of the view and their corresponding value models in the view model
Ask KnockoutJS to make the bindings effective (they will be live right after that)
Save off the view model so we can access it from other parts of the app

So let’s implement the first responsibility to instantiate a view model for the savings goal view (using the initializeViewModel function we just created in the savings goal view model module).

sgs.mediator.savingsgoal.createViewMediator = function (pageSettings) {
	// Create the view Savings Goal view-specific view model
	var viewModel = sgs.model.savingsgoal.initializeViewModel(pageSettings);
}

Now let’s declare each of the 3 data-bindings we need:

sgs.mediator.savingsgoal.createViewMediator = function (pageSettings) {
	// Create the view Savings Goal view-specific view model
	var viewModel = sgs.model.savingsgoal.initializeViewModel(pageSettings);

	// Declare the HTML element-level data bindings
	$("#savings-goal-amount").attr("data-bind","value: savingsGoalAmount");
	$("#savings-max-duration").attr("data-bind","value: savingsMaxDuration");
	$("#savings-target-per-month").attr("data-bind","text: savingsTargetPerMonth()");
}

Now we’ll ask KnockoutJS to “apply”, i.e. register / enable our bindings.

sgs.mediator.savingsgoal.createViewMediator = function (pageSettings) {
	// Create the view Savings Goal view-specific view model
	var viewModel = sgs.model.savingsgoal.initializeViewModel(pageSettings);

	// Declare the HTML element-level data bindings
	$("#savings-goal-amount").attr("data-bind","value: savingsGoalAmount");
	$("#savings-max-duration").attr("data-bind","value: savingsMaxDuration");
	$("#savings-target-per-month").attr("data-bind","text: savingsTargetPerMonth()");

	// Ask KnockoutJS to data-bind the view model to the view
	var viewNode = $('#savings-goal-view')[0];
	ko.applyBindings(viewModel, viewNode);
}

This is where KnockoutJS is performing some heavy lifting behind the covers such as:

Setting observers on the actual HTML elements
Connecting these observers with the value models of the view model
Getting the initial value of each value model
Initializing each HTML element with that corresponding initial value

To make it possible to store and retrieve our view model later we’ll leverage the jQuery data API.
So let’s create 2 functions in the savings goal mediator (since it is acting as an intermediate between the browser, page, view and the model:

sgs.mediator.savingsgoal.getViewModel = function() {
	return $(document).data("sgs.model.savingsgoal.viewmodel");
}

sgs.mediator.savingsgoal.setViewModel = function(viewModel) {
	$(document).data("sgs.model.savingsgoal.viewmodel", viewModel);
}

Now we can use the setViewModel function inside createViewMediator to save off our freshly-created view model.

sgs.mediator.savingsgoal.createViewMediator = function (pageSettings) {
	// Create the view Savings Goal view-specific view model
	var viewModel = sgs.model.savingsgoal.initializeViewModel(pageSettings);

	// Declare the HTML element-level data bindings
	$("#savings-goal-amount").attr("data-bind","value: savingsGoalAmount");
	$("#savings-max-duration").attr("data-bind","value: savingsMaxDuration");
	$("#savings-target-per-month").attr("data-bind","text: savingsTargetPerMonth()");

	// Ask KnockoutJS to data-bind the view model to the view
	var viewNode = $('#savings-goal-view')[0];
	ko.applyBindings(viewModel, viewNode);

	// Save the view model
	sgs.mediator.savingsgoal.setViewModel(viewModel);	

	if (typeof(console) != 'undefined' && console) console.info("sgs.mediator.savingsgoal ready!");
}

6. Link the Page and the View Mediator

Here is a diagram summarizing how we’ll be linking our parts:

Ok now we’re at a point to start testing our first draft, we just need to add a call to the overall page InitializeApplication function (located in scripts/application.js) to our savings goal createViewMediator function like so:

function InitializeApplication() {
	if (typeof(console) != 'undefined' && console)
		console.info("InitializeApplication starting ...");

	// Initialize our page-wide settings
	var pageSettings = { defaultSavingsGoal: 500 }

	// Create / launch our view mediator(s)
	sgs.mediator.savingsgoal.createViewMediator(pageSettings);

	if (typeof(console) != 'undefined' && console)
		console.info("InitializeApplication done ...");
}

So now you should be able to load your index.html page in Firefox with the Firebug console on and watch the debug statement and finally our view displays with our initial data as well as the initial derived data for the “Savings Target Per Month” when you tab out of the amount or max number of months input fields:

7. Apply Data Formatting / Masking Business Rules

So far we have a nice simplistic example but if you build a solid app you will want to format and ensure our amounts are correct / valid / displayed according to conventional rules.
To my knowledge (having researched these types of libraries for a while), only library from PengoWorks has currency masking capabilities and will format the amount as you type it.
Since that library stopped being maintained in 2007, I started updating it (after checking with the original author, David Switzer) to make it work with current browsers). The resulting library is called CurrencyMask JS.
So let’s download the latest version to our ./scripts/vendor folder, and add a code snippet in our LAB section:


	
	$LAB
		// ...
		.script("scripts/vendor/currency-mask-0.5.0-min.js").wait()
		.script("scripts/application.js").wait(function(){
			// When ALL scripts have been loaded AND executed:
			InitializeApplication();
		});

To apply masking to a field, you instantiate a Mask object with the format you want (e.g. “$#,###” for amounts up to $9,999 without decimals) and you attach it to the targetted HTML element like so:

    var savingsGoalAmountMask = new Mask("$#,###", "number");
    savingsGoalAmountMask.attach($("#savings-goal-amount")[0]);

Let’s add the mask instantiation snippet to the savings goal view model (at the end of the initializeViewModel function in sgs.model.savings-goal.js). Also note that we will need to perform the initialization of savingsGoalAmount based on pageSettings later on in the mediator – so here we’ll set the default value of savingsGoalAmountFormatted to an empty string:

sgs.model.savingsgoal.initializeViewModel = function (pageSettings) {
	// ...

	var viewModel = {
		savingsGoalAmountFormatted: ko.observable(""),
		savingsGoalAmountMask: new Mask("$#,###", "number"),
		// ...
	};

	// ...
}

And let’s add the “attach” snippet to the savings goal view mediator in the createViewMediator function in sgs.mediator.savings-goal.js, right after the bindings declarations:

sgs.mediator.savingsgoal.createViewMediator = function (pageSettings) {
	// ...

	// Declare the HTML element-level data bindings
	// ...

	// Apply masking to the savings goal amount input field
    viewModel.savingsGoalAmountMask.attach($("#savings-goal-amount")[0]);

	// ...
}

And if we refresh the page and start typing 1500 in the amount it should format as we type along and prevent any other character input, ensuring the amount is valid.

But … we just introduced an issue (see the infamous NAN displayed in the Savings Target Per Month)!
Well, once formatted the savingsGoalAmount value model will now be a string containing currency and thousands delimiter characters.
So let’s recognize that semantic change by re-naming our savingsGoalAmount value model as savingsGoalAmountFormatted value model:

sgs.model.savingsgoal.initializeViewModel = function (pageSettings) {
	// ...

	var viewModel = {
		savingsGoalAmountFormatted: ko.observable(pageSettings.defaultSavingsGoal || 0), // dollars
		// ...
	};

Now what we need to re-create a new savingsGoalAmount value model, and make it act as a two-way adapter to convert back and forth between formatted and unformatted values.
KnockoutJS can help us with that, using a “dependentObservable“. KnockoutJS also allows a hash to be passed to ko.dependentObservable. That hash can include the following key-value pairs:

owner – will specify the value of this
read – a function which can perform some post-processing and ultimately return the value of the observable
write – a function which can perform some pre-processing of a value and ultimately store it

So here is a skeleton of what the savingsGoalAmount value model would look like as a dependentObservable:

viewModel.savingsGoalAmount = ko.dependentObservable({
	owner: viewModel,
	read: function () {
		// some post processing code
	},
	write: function (value) {
		// some pre processing code
	}
});

Let’s tackle the read function first. It will need to:

Get the current value model from savingsGoalAmountFormatted
Ask the savingsGoalAmountMask for a stripped (unformatted) value
Return a valid float value

Here is what the code looks like for the “read”:

	read: function () {
		// Get the current formatted value model
		// Important Note: Even though we don't use the formatted_amt variable
		// in the rest of the function, we need to let KnockoutJS "know"
		// that this closure has a dependency on savingsGoalAmountFormatted
		// otherwise the closure will never be invoked on a read.
		var formatted_amt = this.savingsGoalAmountFormatted();

		// Unformat the value
		var amt = this.savingsGoalAmountMask.strippedValue;

		// Convert the result to a float
		if (amt.length == 0) { amt = 0 };
		return parseFloat(amt);
	},

Now let’s tackle the write function first. It will need to:

Ask the savingsGoalAmountMask to format the value
Set the savingsGoalAmountFormatted to the formatted value
Return the passed value

Here is what the code looks like for the “write”:

	write: function (value) {
		// Format the passed in value using the mask
		var formatted_value = this.savingsGoalAmountMask.updateFormattedValue(value);

		// Update the savingsGoalAmountFormatted value model
		this.savingsGoalAmountFormatted(formatted_value);
		return value;
	}

The complete and refactored savingsGoalAmount dependentObservable will now look like this:

viewModel.savingsGoalAmount = ko.dependentObservable({
	owner: viewModel,
	read: function () {
		// Get the current formatted value model
		var formatted_amt = this.savingsGoalAmountFormatted();

		// Unformat the value
		var amt = this.savingsGoalAmountMask.strippedValue;

		// Convert the result to a float
		if (amt.length == 0) { amt = 0 };
		return parseFloat(amt);
	},
	write: function (value) {
		// Format the passed in value using the mask
		var formatted_value = this.savingsGoalAmountMask.updateFormattedValue(value);

		// Update the savingsGoalAmountFormatted value model
		this.savingsGoalAmountFormatted(formatted_value);
		return value;
	}
});

Now refreshing the index.html page should allow you to enter amounts and see the calculated value!

Here is a diagram summarizing how we restructured the various parts using the dependent observables and the mask:

I will leave the exercise for you dear reader to follow the same pattern for the “Savings Max Duration (In Months)” input field.
In that case the mask will be a little simpler since we need at most 2 digits.

8. Apply Custom Masking Rules

For custom masking needs, such as for example a phone number, social security id, special identifier,
I strongly recommend Josh Bush‘ Masked Input Plugin.

For dates I suggest using Masked Input together with jQuery Datepicker since the calendar makes it easy to select a date but does not provide masking features.

9. Applying Formatting Rules

When using our simple view you might have noticed that the “Savings Target Per Month” may show some numbers with many decimals. This is because the element is data-bound to the savingsTargetPerMonth dependentObservable which returns a float. So we have two options:

Apply formatting to the float inside savingsTargetPerMonth
Or create another dependentObservable named savingsTargetPerMonthFormatted, in which we can apply the needed formatting logic. Then we would change the data binding for the to use our new value model.

The cleanest approach is #2 since it also allows you in the future to build other dependentObservables on top of savingsTargetPerMonth. But if you don’t think you will need that ability then #1 will work and is very simple.

Approach 1 would require us to format the calculated value using the formatMoney function of Accounting.js like so:

		var result = this.savingsGoalAmount() / this.savingsMaxDuration();
		var formattedResult = accounting.formatMoney(result, "$", 2, ",", ".");  ;
		return formattedResult;

Approach 2 would require us to add a new dependentObservable named savingsTargetPerMonthFormatted in our savings goal view model:

sgs.model.savingsgoal.initializeViewModel = function (pageSettings) {
	// ...

	viewModel.savingsTargetPerMonthFormatted = ko.dependentObservable(function() {
		var result = 0;
		if (this.savingsMaxDuration() > 0) {
			result = this.savingsGoalAmount() / this.savingsMaxDuration();
		}
		var formattedResult = accounting.formatMoney(result, "$", 2, ",", ".");  ;
		return formattedResult;
	}, viewModel);
}

And we then need to update the data-binding code in the createViewMediator function of our mediator module:

sgs.mediator.savingsgoal.createViewMediator = function (pageSettings) {
	// ...

	$("#savings-target-per-month").attr("data-bind","text: savingsTargetPerMonthFormatted()");

	// ...
}

Let’s refresh the index.html page and now when we enter $500 and 7 months, the max per month updates to dollar formatted two-decimal amount: $71.43!

10. Applying Visual Feedback Cues

When web pages require a round-trip to the server, the user waits and then sees the whole page refreshing, but in rich interactive apps since processing happens often very fast without a page refresh, we need to provide visual cues when changes occur. For quick feedback logic (e.g. not requiring an Ajax call or processing longer than a second) I recommend using a jQuery UI “effect”, such a temporary highlight using a soft color, like so:

		$("#savings-target-per-month")
			.effect('highlight', { color: 'LightGreen' }, 3000); // for 3 seconds

Logically the code belongs to the mediator, so let’s subscribe to the savingsTargetPerMonthFormatted value model changes
inside our createViewMediator function.

sgs.mediator.savingsgoal.createViewMediator = function (pageSettings) {
	// ...

	// Subscribe to interesting value model changes
	viewModel.savingsTargetPerMonthFormatted.subscribe(function() {
		$("#savings-target-per-month")
			.effect('highlight', { color: 'LightGreen' }, 3000); // for 3 seconds
	});

	// ...
}

Let’s refresh index.html, and whenever we see the xxx recalculate, the light green highlight of the result should fade in and out during our 3-second timeframe!

Overall Recap

So at this point we have built a reasonably solid foundation for our app even though it contains only one view. The architectural steps we took to decouple view, viewmodel, view mediator and the page will yield some benefits once we add continue adding features to our app (in part 3).

So here is a quick recap of the steps we followed:

#	To Do	Area (Module)
1	Create a Shell Application	Main app
2	Organize your Application Code	Main App
3	Break down each independent panel into Views	View
4	Create a ViewModel for each View	View Model
5	Create a View Mediator for each View	View Mediator
6	Link the Page and the View Mediator(s)	Main App
7	Apply Data Formatting / Masking Business Rules	View
8	Apply Custom Masking Rules	View Mediator
9	Applying Formatting Rules	View Mediator
10	Providing Visual Feedback Cues	View Mediator

So What?

Many KnockoutJS tutorials focus on giving you the basics to run simple scenarios. My approach here although more “architected” is geared at building rich interactive apps made of multiple panels/views with solid interactions.

The modularization of our code base will also lend itself better to unit testing and even BDD testing using Javascript test frameworks like Jasmine and Jasmine-Species. They will allow us to write tests against our view models and to a certain degree some of the various Javascript modules.

We have focused on a one-view increment for the app but in Part 3 we will cover the following topics:

Adding more views, viewmodels and mediators to our basic app
Sharing data across views and mediators
Implementing masking and formatting
Incorporating rudimentary elements of usability
… and more!

So stay tuned!

References and Resources

Patterns

Frameworks And Blogs

Javascript Loaders

jQuery Plugins

Other Javascript Libraries

Javascript Test Frameworks

My Other Related Posts:

Full Source Of The Savings Goal Simulator (KnockoutJS Demo)

The whole application is available on Github under techarch / savings-goal-simulator.

Credits

Special thanks for Thibaut Barrère and Susan Potter for their feedback while I was working on drafts for this tutorial! :-)

If you enjoyed this post, I would love it if you could check out mySkillsMap, my skills management app.

Creating Rich Interactive Web Apps With KnockoutJS – Part 1

techarch — Sat, 17 Sep 2011 21:35:28 +0000

Intro

With the advent of online games, social apps, Flash/AIR apps, and rich instant-feedback sites
like Google Search and GMail, consumers are demanding more and more interactivity.

While interacting with your app customer now expect:

Browser-side processing (calculation, business rules, …)
Instant validation
Instant visual feedback: animation/effect while making changes (add/remove/update)
Dynamic clues on what to do next
More same / on page functionality (without the need to refresh or navigate to other pages)

For a while adding a sprinkling of AJAX and localized visual refresh using jQuery UI was sufficient.
But richer application interactions introduce more elaborate technical approaches:

Present more related data at the same time
Leverage graphs and other data visualization techniques
Offer more on-page functionality
Allow interactions with one panel to cause updates on other panels
Support asynchronous back-end interactions

Extending the Model View Controller Pattern

Here is a reminder of what typically happens in a traditional MVC web app (e.g. Ruby On Rails, Ruby Camping, ASP.NET MVC, Cake PHP, Django Python, etc.):

The routing engine identifies the appropriate controller
The controller retrieves the model
The view engine renders the view
The view contains HTML, CSS, and Javascript code
Rich browser-side applications typically have event handlers to allow page-level interactions to
handle validation, hide/show elements, perform some processing / calculations, executebusiness rules, invoke AJAX services, update content

Note that the last bullet represents quite a bit of logic (possibly in the 500 to several thousand lines of Javascript code).
The logic gets even more complex once you have multiple panels and sets of model elements.
If your AJAX services return complex objects you also need to keep track of these objects,
their binding to panel elements/controls, and their inter-dependencies / impact on each other when a change occurs.

Key take-away:

We need to organize our browser-side code (markup, CSS, and JS) according to their concern, i.e. model representation, business rules, display, user interaction, event handling, server interaction, etc..

This is where the notion of ViewModel and Observables come in to help us out.
Let’s break things down:

The ViewModel is a specialized browser-side Javascript model representing a group of data elements a given page or panel (View) will display or facilitate interaction with.

Benefits:
- Partitioning: each page / page can have its own clean model
- Testability: the View and ViewModel can be tested independently from the server logic
- Modularity: ViewModels code can be namespaced and contained in their own .js file
Each attribute of a ViewModel will be mapped to an Observable so that any value change can be broadcasted (a.k.a. “published” in the publish/subscribe terminology) to any interested subscriber. (So essentially a ViewModel attribute is what is called a Value Model)

Benefits:
- Fast UI: derived values or content can be produced on-the-fly based on observed attributes
- Increased responsiveness: asynchronous server interactions can be triggered in the background and cause ViewModels to be updated
The scenario where a UI element subscribe to a ViewModel attribute (Value Model) is known as “Data-Binding“.
This allows a clean separation between logic related to the ViewModel (calculations, derivations, retrieval, server interaction) and UI-specific presentation logic.

Benefits:
- Synchronization: HTML elements and ViewModel attributes are kept in synch
- Instant visual feedback: elements on the page can update visually as you interact / update data

Introducing KnockOutJS

KnockOutJS is a Javascript framework created by Steve Sanderson to provide support for ViewModel, Observable, and Data-Binding using jQuery.
For more details, check out the KnockOutJS site as well as the Learning Playground.

Let’s dig into the basic infrastructure provided by KnockOutJS and then we’ll build up to more complex scenarios.

Basics

In KnockoutJS, a ViewModel is defined as a Javascript Object Literal. Value Models are defined using ko.observable() and an initial value as follows:
```
var viewModel = {
	savingGoalAmount: ko.observable(500), // dollars
	// ... more attributes ...
};
```
The example ViewModel has one attribute: savingGoalAmount, with an initial value of 500.

You can programmatically “subscribe” to changes in a ViewModel attribute (a Value Model) like this:

// Set up the ViewModel
var viewModel = {
	savingGoalAmount: ko.observable(500), // dollars
	// ... more attributes ...
};

viewModel.savingGoalAmount.subscribe(function(newValue) {
	// Show the updated value on the FireBug's console
	console.info("savingGoalAmount is now " + newValue);
});

// Get KnockoutJS to apply bindings / subscriptions
ko.applyBindings(viewModel);	

// Test by changing the amount
viewModel.savingGoalAmount(600); // Should display in the console

The subscribe function takes a callback function it will invoke upon any change on the value of the savingGoalAmount Value Model.

The ko.applyBindings function tells KnockoutJS to start the dependency tracking. From that point on all subscribers will be notified of any changes.

KnockoutJS makes it easy to setup data binding between any HTML element (e.g. INPUT) and a ViewModel attribute (Value Model) using the data-bind syntax and the value: keyword
KnockoutJS uses the data-bind attribute to let us specify the type of binding needed.
In this example we’re binding the value of the INPUT element to the savingGoalAmount Value Model.
We’ll see later on that there are other types of data-binding such as specific attributes, visibility, styling, etc. although you can see the full reference in the documentation.

Note that the data-bind syntax is just “syntactic sugar” for use in our markup. If you prefer a clean separation between markup and Javascript, you can declare your data-bindings like so:
```
$("#saving-goal-amount")
	.attr("data-bind","value: savingGoalAmount");
```
You just need to make sure these declarations are performed before you get KnockoutJS to apply the bindings (using ko.applyBindings).

You can play and run the examples above on this jsFiddle.net page.

Building Up

Now that we have a basic understanding of KnockoutJS, let’s add a few more building blocks:

If a ViewModel attribute needs to store an array, KnockoutJS provides a specialized type of Observable called an ko.observableArray:
```
var viewModel = {
	savingGoalObjectives: ko.observableArray([ 'Discretionary', 'Expensive Purchase', 'Investment']),
	// ... more attributes ...
};
```
Adding / removing items in the array will cause KnockoutJS to trigger an update to all observers of this Value Model.

In addition to attributes (Value Models), ViewModels can expose “behaviors” such as:

Derived attributes, resulting from a calculation, or a business rule.

KnockoutJS refers to them as dependentObservables:
```
var viewModel = {
	savingGoalAmount: ko.observable(500), // dollars
	savingMaxDuration: ko.observable(6), // dollars
	// ... more attributes ...
};

// Derived data
viewModel.savingTargetPerMonth = ko.dependentObservable(function() {
	return this.savingGoalAmount() / this.savingMaxDuration();
}, viewModel)
```
Whenever either savingGoalAmount or savingMaxDuration change, the derived savingTargetPerMonth function will be re-evaluated.
If savingTargetPerMonth is data-bound to the UI, the corresponding element will redisplay.

Note that you can create dependentObservable functions on top of dependent observables or plain observables!

Formatted version of the data

var viewModel = {
	savingGoalAmount: ko.observable(500), // dollars
	// ... more attributes ...
};

// Derived formatted display data
viewModel.savingGoalAmountAsCurrency = ko.dependentObservable(function() {
	return accounting.formatMoney(this.savingGoalAmount(),
			"$", 2, ",", ".");  ;
}, viewModel)

Above is an example using the Accounting.js library to format our savingGoalAmount Value Model within our dependent observable so that we can display a nicely formatted currency representation on the UI.

Add / remove logic on arrays

var viewModel = {
	myItems: ko.observableArray(),
	// ... more attributes ...
};

// Add / remove behaviors
viewModel.addItem = function (newItem) {
	var valid = validateItem(newItem); // custom logic
	if (valid) {
		this.myItems.push(newItem);
	}
}

In this example, addItem is a custom behavior attached to the ViewModel which can be invoked to add new valid items.

Any other business logic related to an overall ViewModel

var viewModel = {
	savingGoalAmount: ko.observable(500), // dollars
	// ... more attributes ...
};

viewModel.reset = function() {
	this.savingGoalAmount(500);
}

To allow other parts of our browser-side logic to access our ViewModels, we need to have a way to access them.

We can save ViewModels in the DOM, either at the document level or at a panel level using the jQuery.data API:

var viewModel1 = { }
var viewModel2 = { }

ko.applyBindings(viewModel1);
ko.applyBindings(viewModel2);	

$(document).data("MyDocumentViewModel", viewModel1);
$("#my-panel").data("MyPanelViewModel", viewModel2);

This allows us to access a specific ViewModel later, outside data-binding logic (e.g. in an event handler) like so:

var viewModel1 = $(document).data("MyDocumentViewModel");
var viewModel2 = $("#my-panel").data("MyPanelViewModel");

To keep our code organized we’ll want to create accessor functions such as for example:

	MyApp.Model.GetMyDocumentViewModel = function() {
		return $(document).data("MyDocumentViewModel");
	}

	MyApp.Model.SetMyDocumentViewModel = function(viewModel) {
		$(document).data("MyDocumentViewModel", viewModel);
	}

So that we can just access our ViewModel from other modules:

// Initialization
var viewModel = { }
ko.applyBindings(viewModel);
MyApp.Model.SetMyDocumentViewModel(viewModel);

// Later on in a different module:
MyApp.Model.GetMyDocumentViewModel()
	.savingGoalAmount.subscribe(myCallBackFunction);

The attributes (Value Models) of the ViewModel can be updated using data returned by an AJAX call to a controller

$.getJSON('ajax/myapi.json',
			parms,
			function(data) {
	// Assumption: we have saved the original viewModel
	var viewModel = $(document).data("MyViewModel");
	viewModel.savingGoalAmount(data.amount);
});

The ViewModel can also aggregate a subset of attributes from one or even several server-side [MVC] Models

Arbitrary Javascript functions can also subscribe to Value Model changes:

// Set up the ViewModel
var viewModel = {
	savingGoalAmount: ko.observable(500), // dollars
	// ... more attributes ...
};

function GraphSavingScenario(newValue) {
	// some graphing logic
}

viewModel.savingGoalAmount.subscribe(GraphSavingScenario);

So What?

KnockoutJS can help organize browser-side logic by facilitating the creation of panels (Views),
each logically data-bound to ViewModels built on top of a local publish/subscribe mechanism using Observables.

Data-binding, combined with derived data / behaviors, and AJAX will boost the interactivity level of the application.

Part 2 of the series on “Creating Rich Interactive Web Apps” will be a tutorial on how to build a moderate complexity application with KnockoutJS.
We will cover the following topics:

Enabling / disabling rules
Condition display
Leveraging jQuery templates
Extracting views into templates
… and more!

So stay tuned!