Client-Side Chaos - Part III : The ViewModel

This is the third and final installment in the series Client-Side Chaos. It examines the ViewModel object internals.

Let's start with the constructor :

function ViewModel(alertOnError, errorCallback) { // >>> for private ViewModel access by methods var viewModel = this; // elevate request JsonResult prop to ViewModel level viewModel["errorMessage"] = ko.observable(""); // establish error callback if specified viewModel.notifier = null; // create error notification subscription when opting for callbacks over alerts if (!alertOnError && typeof errorCallback != 'undefined') { viewModel.notifier = ko.observable(""); // notifier is failure message viewModel.notifier.subscribe(errorCallback); viewModel.notifier.extend({ notify: 'always' }); } // extend jquery with function to get object from form or list // callers could supply themselves if they thought of it... $.fn.serializeObject = function() { var o = {}; var a = this.serializeArray(); $.each(a, function() { if (o[this.name] !== undefined) { if (!o[this.name].push) { o[this.name] = [o[this.name]]; } o[this.name].push(this.value || ''); } else { o[this.name] = this.value || ''; } }); return o; };

• "this" is established as a private variable named viewModel which can be accessed by public methods contained in the eventHandlers public object.
• errorMessage, a JsonResult property that must be returned from every post request, is established as an observable property of the ViewModel instance.
• If specified an error callback is established as a subscription event to be fired whenever the errorMessage observable changes.
• jQuery is extended with a serializeObject method that can be used to create post input objects using selectors that yield either a single element (in which case the resulting object contains properties having values for all of the specified element's child elements) or a list of elements (in which case the resulting object contains properties having values for only the selected elements).

Encapsulated in the public eventHandlers object are 3 methods :

• post
this.eventHandlers = { // post optional input POJO to url and return POJO post: function LoadViewModel(url, input, successCallback, shouldMap, element) { url = "http://" + location.host + "/" + url; debugger; $.post(url, { data: JSON.stringify(input) }, getSuccessHandler()(viewModel, url, successCallback, shouldMap)) // pass map to success and fail .fail(getErrorHandler()(viewModel, url, shouldMap)); },

• post takes required parameters of url and successCallback, and optional parameters of shouldMap and element.
• shouldMap defaults to false and controls whether the returned JsonResult object is mapped to an equivalent object containing only observables and observableArrays.
• element is used only when shouldMap == true and limits binding to the specified element which defaults to window.document.
• successCallback will be called with two parameters, url and the returned JsonResult object which is mapped when shouldMap == true.


• map
// create observable object from POJO map: function (modelObject) { var vm = {}; return pvt.innerMap(vm, modelObject); },

• map calls the private innerMap helper to obtain a mapped object without databinding. See innerMap description below for more information


• unMap
unMap: function (viewModelObject, modelObject) { for (prop in viewModelObject) { var modelObjectPropType = Object.prototype.toString.call(modelObject[prop]); if (modelObjectPropType == '[object Array]' || modelObjectPropType == '[object Object]') modelObject[prop] = viewModel.eventHandlers.unMap(viewModelObject[prop], modelObject[prop]); else modelObject[prop] = viewModelObject[prop](); } return modelObject; } }

• unMap creates an equivalent POJO from an object consisting solely of observable and observableArray type properties, maintaining object hierarchy and structure

Encapsulated within the private pvt object are 4 methods and one property. The alertOnErrorproperty is retained from the constructor parameter having the same name. The methods are:

• errorHandler
// jquery / ajax / xhr error errorHandler: function (vm, url, shouldMap, element) { return function (jqXHR, textStatus, errorThrown) { var errorMessage = "Post error. status= \"" + textStatus + "\", error= \"" + errorThrown + "\""; var errorObject = { url: url, reason: errorThrown, errorMessage: errorMessage }; vm.errorMessage(errorMessage); if (shouldMap) pvt.map(vm, url, errorObject, element); console.log(errorMessage); if (alertOnError) // should I make errorMessage prop name variable? alert(errorMessage); else vm.notifier != null ? vm.notifier(errorObject) : {} ; } },
• sets ViewModel errorMessage observable
• maps and databinds the errorObject if mapping was specified
• logs to console
• then either issues alert or calls view errorHandler


• successHandler
  Note that successHandler will be called for some server errors.
// no ajax error but maybe "not found" or server exception... successHandler: function (vm, url, successCallback, shouldMap, element) { return function (model, textStatus, jqXHR) { if (shouldMap) pvt.map(vm, url, model, element); if (model.status != "success") { var errorObject = { url: url, reason: "Controller Error", message: model.errorMessage }; console.log(model.errorMessage); if (alertOnError) alert(model.errorMessage); else vm.notifier != null ? vm.notifier(errorObject) : {} ; } else if (typeof successCallback == 'function') successCallback(url, model); } },
• maps and databinds returned JsonResult object if indicated by post shouldMap parameter
• if error log to console
• if error alert user if constructor parameter alertOnError == true
• if successful call the successCallback if one was passed on the post request


• map
  The private map method is called to databind the mapped object
// map model to ViewModel property having name based on url map: function (viewModel, url, model, element) { // create prop for sub-ViewModel by replacing forward slashes var subVmName = url.replace("http://" + location.host, ""); subVmName = subVmName.replace(/\//g, ""); viewModel[subVmName] = {}; viewModel[subVmName] = pvt.innerMap(viewModel[subVmName], model); element = element == null ? window.document.body : element; ko.applyBindings(viewModel[subVmName], element); },
• viewModel is the object to which a sub-View Model object will be added as a property
• url is the url that had been used to obtain a model object that will be mapped to the sub-View Model. It is also used to derive the sub-View Model property name.
• model is the object returned from post to the url and which will be mapped to the sub-View Model via a call to pvt.innerMap
• element is optional and the HTML element that will be used in databinding with the sub-ViewModel as can be seen in the call to ko.applyBindings.


• innerMap
var newObservable; for (var prop in modelObject) { // already observable or observable array? if (typeof viewModelObject[prop] != "function") { var modelObjectPropType = Object.prototype.toString.call(modelObject[prop]); // if object or array recur to make children observable if (modelObjectPropType === '[object Array]' || modelObjectPropType === '[object Object]') { if (modelObjectPropType === '[object Array]') viewModelObject[prop] = []; else viewModelObject[prop] = {}; newObservable = pvt.innerMap(viewModelObject[prop], modelObject[prop]); } // make current prop observable or observableArray, depending... if (modelObjectPropType === '[object Array]') viewModelObject[prop] = ko.observableArray(newObservable); else if (modelObjectPropType === '[object Object]') viewModelObject[prop] = ko.observable(newObservable); else viewModelObject[prop] = ko.observable(modelObject[prop]); } else // already observable or observable array so just update viewModelObject[prop](modelObject[prop]); } return viewModelObject; } } innerMap is a helper for the public map method which accepts a model object and recursively iterates properties descendant properties while adding those properties and their values to a corresponding View Model object as observables and observableArrays. This View Model object has identical structure and hierarchy as the input model object.

This concludes the series. The full working, zipped Visual Studio solutions may be downloaded from SkyDrive and include both Visual Studio projects and a database creation script. Other-platform developers can still salvage the ViewModel object from the zip file.

As always, feedback is appreciated.

Click here for the VS2012 solution.
Click here for the VS2010 solution.