An extensible and fast object mapping plugin for KnockoutJS
An extensible and fast object mapping plugin for KnockoutJS.
It is based on handlers (ignore, copy, object, array...) that converts knockout models toJS and fromJS in different ways.
Every handler knows how to convert from JS and to JS.
On Knockout Mapper you define the handler/options on each property:
var mapping = {
'propertyA': 'ignore',
'propertyB': 'ignore'
};
and you can also pass extra-options:
var mapping = {
$default: 'ignore',
'propertyC': 'auto'
};
It is NOT compatible with Knockout Mapping syntax.
NEW! Performance comparision: http://jsperf.com/ko-viewmodel-vs-ko-mapping-complex-viewmodel-creation/25
Fiddle with basic usage: http://jsfiddle.net/LucasLorentz/tC5rE/
Fiddle comparing it with Knockout Mapping: http://jsfiddle.net/LucasLorentz/h8hsx/
You can also read our tests to understand all behaviors of the library: https://github.com/LucasLorentz/knockout.mapper/blob/master/tests/tests.js
Parameters:
When a handler is not specified, this handler is used by default.
Options:
Options:
You can call fromJS passing only the data that will be transformed
var model = ko.mapper.fromJS(data);
Passing a mapping options:
var model = ko.mapper.fromJS(data, mapping);
You can also pass just the handler name:
var model = ko.mapper.fromJS(data, 'object');
Updating an existent model:
ko.mapper.fromJS(data, mapping, model);
You can call toJS passing only the model that will be transformed
var data = ko.mapper.toJS(model);
Passing a mapping options:
var datal = ko.mapper.toJS(model, mapping);
You can also pass just the handler name:
var model = ko.mapper.toJS(data, 'object');
All examples below will consider the following data:
var data = {
firstName: 'John',
lastName: 'Doe',
age: 25,
children: [
{
firstName: 'Maria',
lastName: 'Doe',
age: 9
},
{
firstName: 'William',
lastName: 'Doe',
age: 10
}
]
};
Changing the handler of specific properties:
var mapping = {
'lastName': 'copy',
'age': 'ignore'
};
Specifying the root handler:
var mapping = {
$handler: 'object',
'lastName': 'copy',
'age': 'ignore'
};
Changing the default configuration for all properties:
var mapping = {
$default: 'ignore',
'firstName': 'auto'
};
Array mapping options:
var mapping = {
'children': {
$key: 'firstName',
$merge: true,
$itemOptions: {
'age': 'ignore'
}
}
};
$itemOptions can be a function:
var mapping = {
'children': {
$key: 'firstName',
$merge: true,
$itemOptions: function(){ return mapping; }
}
};
Using a model type:
var Model = function(){
var self = this;
self.firstName = ko.observable();
self.lastName = ko.observable();
self.fullName = ko.computed(function(){
return self.firstName() + self.lastName();
});
};
var mapping = {
$type: Model
};
Adding custom handlers:
ko.mapper.handlers.importOnce = {
fromJS: function (value, options, target, wrap) {
if (!target || !target.imported) {
var result = ko.mapper.handlers.auto.fromJS(value, options, target, wrap);
result.imported = true;
return result;
} else {
return ko.mapper.ignore;
}
},
toJS: function (observable, options) {
return ko.mapper.handlers.auto.toJS(observable, options);
}
};
var mapping = {
'age': 'importOnce'
};
Licensed under the MIT License. http://opensource.org/licenses/mit-license.php