README
Backbone Model Decorator
Backbone Model Decorator is a Backbone.js plugin that decorates Backbone.Model
with properties
property that plays role of Model Facade and contains model attributes in form of properties.
var DecoratedModel = ModelDecorator.extend({
defaults: {
email: 'default@email.com',
password: ''
}
});
var decorated = new DecoratedModel();
Getting model attribute via such property will return current value of the attribute.
console.log(decorated.properties.email); // default@email.com
decorated.set({password: '@!$^&SEvjH#'});
console.log(decorated.properties.password); // @!$^&SEvjH#
And setting new value to property will immediately change model attribute.
decorated.properties.email = 'other@email.com';
console.log(decorated.get('email')); // other@email.com
decorated.properties.email = '@!$^&SEvjH#';
console.log(decorated.get('password')); // @!$^&SEvjH#
Installation
This package is available via npm
npm install backbone-model-decorator --save
and bower distribution systems
bower install backbone-model-decorator --save
Also you can download it as single file with comments or minified from this repository.
Usage
To start using decorator you should extend model from ModelDecorator
instead of Backbone.Model.
var decorated = ModelDecorator.extend({
...
});
With extending from ModelDecorator
, extended model gains new properties and methods.
properties
-- Facade object with all generated propertiespropertyOptions
-- Object containing options for model attributes that should be used by default when setting new value via setter functionvalidateProperties()
-- Method that allows creating bunch of properties on Facade object by going through passed object's property namesproperty()
-- Method that allows adding or changing single property on Facade object
Worth noting that Model should know
about possible attributes it might have to properly initialize Facade properties.
Facade object is populated with properties when model initialization occurs, so it has 3 sources for possible properties:
- Model
attributes
object - Model
defaults
object - Model
propertyOptions
object that contains default options applied on property set These objects are checked for property names and each found property will be mirrored on facade object as possible Model attribute.
There are two ways to add properties to Facade after model initialization
- Using
Model.validateProperties()
- Using
Model.property()
Also its possible to re-define property viaModel.property()
adding custom getter/setter functions or making read-only properties.
Model.properties
Default place where Model Facade object will be stored is properties
field in Model object. This can be changed in 2 ways.
Set ModelDecorator
to create properties using Model object without creating Facade object. All newly created properties will be available directly from model.
ModelDecorator.facadeType = ModelDecorator.USE_MODEL;
var DecoratedModel = ModelDecorator.extend({
defaults: {
value: 'this is value',
name: 'this is name'
}
});
var decorated = new DecoratedModel();
console.log(decorated.properties); // null
console.log(decorated.value); // this is value
console.log(decorated.name); // this is name
decorated.value = 'new value';
decorated.set({name: 'update name'});
console.log(decorated.get('value')); // new value
console.log(decorated.name); // update name
Note: Creating properties on model may cause name collisions with internal Backbone Model instance fields.
Or change Facade property name, by default its properties
. In this case Facade will be created and stored in field with specified name. All created properties will be stored in Facade object.
ModelDecorator.facadeFieldName = 'props';
var DecoratedModel = ModelDecorator.extend({
defaults: {
value: 'this is value',
name: 'this is name'
}
});
var decorated = new DecoratedModel();
console.log(decorated.properties); // null
console.log(decorated.props); // ModelFacade {}
console.log(decorated.props.value); // this is value
console.log(decorated.props.name); // this is name
decorated.props.value = 'new value';
decorated.set({name: 'update name'});
console.log(decorated.get('value')); // new value
console.log(decorated.props.name); // update name
Note: Renaming facade property to names used by Backbone Model, like attributes
, may cause unexpected errors.
Model.validateProperties()
validateProperties()
does lookup for names on passed object and uses this names to create new properties on facade.
It will not apply values from passed objects, so new model properties will be created but not initialized.
var DecoratedModel = ModelDecorator.extend({});
var decorated = new DecoratedModel();
decorated.validateProperties({value:'any value here', name: '#$%#