Backbone.Mutators
Backbone plugin to override getters and setters with logic
Build Status, Project Page, Annotated Source & Tests
Project Page
Docs
Tests
NPM registry
Introduction
Ever wanted Backbone to have getters and setters you can override with your own logic? Yes?! Then Backbone.Mutators is the missing tool in your chain...
Installation
The plugin itself implements the Universal Module Definition (UMD). You can use it with a CommonJS like loader, or with an AMD loader or via vanilla javascript.
The plugin has two dependencies, underscore.js and backbone.js
Download
You can directly download the Development Version or the Production Version from the root folder
VOLO
$ volo add Backbone.Mutators
NPM
$ npm install Backbone.Mutators
Integration
AMD
// AMD;
CommonJS
// CommonJSvar _ = ;var Backbone = ;var Mutators = ;
Vanilla JS
<!-- Vanilla javascript -->
Usage
Some lines of code explain more then thousand words...
Basic usage
var User = BackboneModel; var user = ; // use get to get the 'mutated' value user // 'Sugar Daddy' // serialize the model and see the 'mutated' value in the resulting JSON user // '{firstname: 'Sugar', lastname: 'Daddy', fullname: 'Sugar Daddy'}'
Override getters
var State = BackboneModel; var state = ; // use get to get the 'mutated' value state // 'Workish' // serialize the model and see the 'mutated' value in the resulting JSON state // '{status: 'Workish'}'
Use setters
var User = BackboneModel; var user = ; // use get to get the 'mutated' value user; // serialize the model and see the 'mutated' value in the resulting JSON user // 'Big Mama' user; // 'Big' user; // 'Mama'
Catch model events
var User = BackboneModel; var user = ; // bind mutator event user; // bind model events user; // bind model events user; // use get to get the 'mutated' value user; // serialize the model and see the 'mutated' value in the resulting JSON user // 'Big Mama' user; // 'Big' user; // 'Mama'
Silence mutator events (while keeping the model events fired)
var User = BackboneModel; var user = ; // bind mutator event // will never be run user; // bind model events // will still run user; // bind model events // will still run user; // use get to get the 'mutated' value user; // serialize the model and see the 'mutated' value in the resulting JSON user // 'Big Mama' user; // 'Big' user; // 'Mama'
Use mutated setters and call the original setter within
var Spicy = BackboneModel; var spicy = ; // use get to get the 'mutated' value spicy; spicy // 'salt'
Define one getter / setter method
var User = BackboneModel;
Define multiple mutators
var User = BackboneModel;
Define a getter as transient
Defining a getter as transient means that it will be omitted when Backbone saves the model. This is
useful if the backend system (whatever Backbone is syncing to) fails if you send it a property that does
not actually exist on the model. Note that this only works for mutators defined with a get()
function.
In the example below, the fullName
property will be available when toJSON is called under
non-syncing circumstances--for example, when providing this model to a template--but will be omitted
from the JSON when sync is called (because you called the sync()
or save()
method), and will not
be sent to the server.
var Model = BackboneModel;
Further reading
James Brown (@ibjhb) has written a blog article about Mutators (Exploring Backbone.Mutators)
Changelog
0.4.5
- Extended mutators check #38
- Allow to specify custom isSaving() method to detect when toJSON() is cal... #36
0.4.4
- Add mutator dependancies and change events #33
0.4.3
0.4.2
- Fixes #20
0.4.1
0.3.1
- Change get context to modal instead of attributes
- Added single getter / setter method
0.3.1
- Change get context to modal instead of attributes
- Added single getter / setter method
0.3.0
- Removed the Cake based build process and moved to grunt
- Mutators now integrates itself to backbone, no more manual extending needed
- Added the {mutator: {silent: true}} option to prevent mutator set events from firering
- Added unit tests for the new features
- Moved from jslint to jshint
- Tweaked docs
- Removed not needed jquery and qunit-logging submodule / npm dependencies
0.2.0
- Added the original Backbone.Model.set function as a fourth paramter for the mutated set
- Added a 'mutators:set:{{YOUR_MUTATOR_PROPERTY}}' event when setting mutated properties
- Added unit tests for the new features
- Extended/fixed documentation
- Added inline version tag [NOTE: Version 0.2.0 is fully backwards compatible]
0.1.0
- Initial Release