Knockout Viewmodel Plugin

The fastest mapping plugin!

The knockout viewmodel plugin runs several times faster than the knockout mapping plugin. It also allows you to fine tune your viewmodel creation for even more speed. Now you can create complex observable viewmodels easily and with more structure and control than ever before!

You can trust that it works!!!

There is a growing suite of unit-tests that ensures that ko.viewmodel works reliably. Bug fixes always start with one or more new unit test so reliability goes up over time.

Creating a simple viewmodel

This code creates an viewModel with an observable array of users whose properties are observable.

model = {//your model is normally provided via an ajax call
  users:[ 
        {firstName:"John", lastName:"Doe"},
        {firstName:"James", lastName:"Smith"}
    ]
};

viewmodel = ko.viewmodel.fromModel(model);
			

Updating a viewmodel

If you need to update your viewmodel with more recent model data this can be done by calling updateFromModel.

ko.viewmodel.updateFromModel(viewmodel, updatedModel);
                

This method optionally takes a third parameter, makeNoncontiguousObjectUpdates, which can be used to eliminate long running script errors in older browsers. When set to true each object will have an update function created for it which will be called via setTimeout. Given this makeNoncontiguousObjectUpdates should only be set to true if you are getting long running script errors in older browsers. An onComplete method allows you to pass in a callback to be fired when noncontiguous object updates are completed.

ko.viewmodel.updateFromModel(viewmodel, updatedModel, true).onComplete(function(){
    //respond to completion of update
});
                

Note: the onComplete method is only available when makeNoncontiguousObjectUpdates is set to true.

Getting an updated model

At somepoint you'll need to get an updated model to send back up to the server. This can be done by calling toModel.

model = ko.viewmodel.toModel(viewmodel);
        

Extending your viewmodel

Now lets say that you want to extend each object in the users array with an isDeleted flag. You would do this by specifying an extend option.

options:{ 
    extend:{
        "{root}.users[i]": function(user){
            user.isDeleted = ko.observable(false);
        }
    }
};

viewmodel = ko.viewmodel.fromModel(model,options));

If we also wanted to add a delete method to an array we would use the following options:

options:{ 
    extend:{
        "{root}.users[i]": function(user){
            user.isDeleted= ko.observable(false);
        },
        "{root}.users": function(users){
            users.Delete = function(user){
                user.isDeleted(true);
            }
        }
    }
};

Processing Option Paths

Processing options are specified for an item by it's path. Every full path starts with {root}. Items in an array are referred to as [i]. So a path of "{root}.users[i].firstName" would be used to specify custom processing for the firstName property of every object in the users array. That is its full path name, but it's not necessary to refer to every item by it's -full path name. There are three ways of referencing a path:

• Full Path Name - Matches only the specific path, e.g. "{root}.users[i].firstName".
• Parent Child-Name - Matches the parent child combination specified. So "users[i].firstName" will only match the first name property on objects in the users array. Array items have to be referenced as ParentName[i].ChildName but for all other objects the proper reference is ParentName.ChildName
• Property Name - Matches every property with that name. So a partial path of "firstName" would match every firstName property in your model.

Processing Options

There six types of processing options: custom, append, exclude, extend, arrayChildId, and shared.

• custom - the path and all of it's children are processed only as you specify
• append - the path and it's children are appended as is
• exclude - the path is excluded from processing
• extend - the path and it's children are processed normally but then extended/modified as specified
• arrayChildId - used to identify the what property of the array's child objects should to identify them for update purposes
• shared - allows you to reduce duplicate definitions by creating named processing functions that can be used with extend and map.

The only processing types that can be used together on a path are extend and arrayChildId. If multiple processing options are specified for the same path only one will win. Which one will win is subject to internal processing logic that has been organized for performance reasons and should not be relied upon as it is subject to change in future versions.

options:{ 
    extend:{
        "{root}.users[i]": function(user){
            user.isDeleted = ko.observable(false);
            return user;
        }
    }
};
        

options:{ 
    custom:{
        "{root}.users[i]": {
            map:function(mapped){
                mapped.isDeleted= ko.observable(false);
                return mapped;
            },
            unmap:function(unmapped){
            //Because isDeleted was an observable it was unwrapped and added to the model. 
                delete unmapped.isDeleted;
                return unmapped;
            }
        }
    }
};
                    

options:{ 
    custom:{
        "{root}.users[i]": function(user){
            user.isDeleted= ko.observable(false);
            return user;
        }
    }
};
         

options:{ 
    custom:{
        "{root}.users[i]": {
            map:function(user){
                var mapped = ko.viewmodel.fromModel(user);
                mapped().isDeleted= ko.observable(false);
                return mapped;
            },
            unmap:function(user){
                var unmapped = ko.viewmodel.toModel(user);
                delete unmapped.isDeleted;
                return unmapped;
            }
        }
    }
};
        

options:{ 
    append:["{root}.users[i]"]
};
        

options:{ 
    exclude:["{root}.users[i].firstName"]
};
                

options:{ 
    arrayChildId:{
        "{root}.users":"id"
    }
}
                

var model = {
    items:[
        {
            id:256889,
            name:"item Name",
            description:"Description of Item",
            availble:3,
            price:4.25
        }
    ]
};

var viewmodel = ko.viewmodel(model, { 
    arrayChildId:{//child item id
        "{root}.items":"id"
    },
    extend:{
        "{root}.items":function(items){//Toggle function added to array for better performance
            items.ToggleSelect = function (item){
                item.selected(!item.selected);
            }
            return items;
        },
        "{root}.items[i]":function (item){
            item.selected = ko.observable(false);
        }
    }
}
                

var model = {
    movies:[
        {
            id:256889,
            name:"item Name",
            description:"Description of Item",
            showtimes:[
                {start:"11:45am", duration:"120 minutes", soldOut:false, pricingType:"Matinee"},
                {start:"6:45pm", duration:"120 minutes", soldOut:false, pricingType:"Evening"}
            ]
        }
    ]
};

var options = { 
    arrayChildId:{//child item id
        "{root}.movies":"id"
    },
    extend:{
        "{root}.movies[i]":"ExtendWithSelectable",//Reference shared function by name
        "{root}.movies[i].showtimes[i]": function(showtime){

            //Reference shared function directly
            options.shared.ExtendWithSelectable(showtime);

            showtime.price = ko.computed(function(){
                if(showtime.pricingType = "Matinee"){
                    return 6.75;
                }
                else if(showtime.pricingType = "Evening"){
                    return 10.25;
                }
            };
        }
    },
    shared:{
        ExtendWithSelectable:function (item){
            item.selected = ko.observable(false);
            return item;
        }
    }
}

var viewmodel = ko.viewmodel(model, options);
                

Global Options

Global options affect all calls to ko.viewmodel and are access and set via ko.viewmodel.options. Currently there are two global options:

• logging - (default:false) logs viewmodel processing to the console, including all paths processed and mapping options applied.
• makeChildArraysObservable - (default:true) determines if nested arrays are converted to observable arrays. Set to false for compatibility with original mapping plugin or to improve performance.

Observable Array Mapping Methods

• pushFromModel - modifies the object passed in according to the original mapping options, and calls array.push
• unshiftFromModel - modifies the object passed in according to the original mapping options and calls array.unshift
• popToModel - calls array.pop and unmaps and returns the object according to the original mapping options
• shiftToModel - calls array.shift and unmaps and returns the object according to the original mapping options

Think you've found a bug?