One Collection, different models, mapped easy via configuration.
Backbone.Chosen gives your Backbone Collections multiple personalities. It is related to the following Backbone Issue (it´s more a feature request) #1148
It gives you the ability to have a collection with instances of different models prototypes. Lets outline this with a small example that backbone can´t handle on its own:
You fetch a set of json data, lets say some filesystem contents:
[
{
"id": 1,
"name": "afile.txt",
"size": 24234,
"type": "file"
},
{
"id": 2,
"name": "adir",
"type": "dir"
}
]Then you create a collection containing all of this entries, but you want to create different models for files and directories.
With the standard behaviour of Backbone, this is not possible. Backbone.Chosen to the rescue.
Project Page
Docs
Tests
NPM registry
You can download the raw source code from the "src" folder above, or grab one of the builds from the root directory.
To get the latest stable release, use these links which point to the 'master' branch's builds:
Development: backbone.chosen.js Production: backbone.chosen.min.js
$ volo add Backbone.Chosen$ npm install Backbone.ChosenNote: This plugin is UMD compatible, you can use it in node, amd and vanilla js envs
<script src="underscore.js"></script>
<script src="backbone.js"></script>
<script src="backbone.chosen.js"></script>var _ = require('underscore');
var Backbone = require('backbone');
var Chosen = require('backbone.chosen');define(['underscore', 'backbone', 'backbone.chosen'], function (_, Backbone, Chosen) {
});A simple example how to map some data based on an attribute:
// Set up the models
var SaltyModel = Backbone.Model.extend({
defaults: {
taste: 'salty'
}
});
var SweetyModel = Backbone.Model.extend({
defaults: {
taste: 'sweet'
}
});
var BoringModel = Backbone.Model.extend({
defaults: {
taste: null
}
});
// Set up the collection
var Collection = Backbone.Collection.extend({
model: {
chosen: {
attr: 'spice',
defaults: BoringModel,
map: {
salt: SaltyModel,
sugar: SweetyModel
}
}
}
});
// Set up the data
var flavours = [{
id: 1,
spice: 'salt'
}, {
id: 2,
spice: 'sugar'
}];
// Init collection with static data
var collection = new Collection(flavours);
collection.get(1) instanceof SaltyModel // true
collection.get(2) instanceof SweetyModel // trueIf none of your mappings matches, you always have to insert a fallback aka. default model:
// Set up test models
var SaltyModel = Backbone.Model.extend({
defaults: {
taste: 'salty'
}
});
var SweetyModel = Backbone.Model.extend({
defaults: {
taste: 'sweet'
}
});
var BoringModel = Backbone.Model.extend({
defaults: {
taste: null
}
});
// Set up test collection
var Collection = Backbone.Collection.extend({
model: {
chosen: {
attr: 'spice',
defaults: BoringModel,
map: {
salt: SaltyModel,
sugar: SweetyModel
}
}
}
});
// Set up the mock data
var flavours = [{
id: 1,
spice: 'salt'
}, {
id: 2,
spice: 'sugar'
}, {
id: 3,
spice: 'sour'
}];
// Init collection with mock data
var collection = new Collection(flavours);
collection.get(3) instanceof BoringModel // trueIf the attribute your trying to map, is deeper nested in your incoming JSON, the deeper nested attributes mapping makes smth. like this possible:
// Set up some models
var SaltyModel = Backbone.Model.extend({
defaults: {
taste: 'salty'
}
});
var SweetyModel = Backbone.Model.extend({
defaults: {
taste: 'sweet'
}
});
var BoringModel = Backbone.Model.extend({
defaults: {
taste: null
}
});
// Set up a collection
var Collection = Backbone.Collection.extend({
model: {
chosen: {
// NOTICE this deeper nested attr.
attr: 'spices.type.names.displayName',
defaults: BoringModel,
map: {
salt: SaltyModel,
sugar: SweetyModel
}
}
}
});
// Set up the static data
var flavours = [{
id: 1,
spices: {
type: {
names: {
displayName: 'salt'
}
},
origin: 'belgium'
}
}, {
id: 2,
spices: {
type: {
names: {
displayName: 'sugar'
}
},
origin: 'netherlands'
}
}, {
id: 3,
spices: {
type: {
names: {
displayName: 'sour'
}
},
origin: 'germany'
}
}];
var collection = new Collection(flavours);
// check instances
collection.get(1) instanceof SaltyModel // true
collection.get(2) instanceof SweetyModel // true
collection.get(3) instanceof BoringModel // trueIf the standard mapping isnt enough for you, you can specify your own mapping function
// Set up some models
var SaltyModel = Backbone.Model.extend({
defaults: {
taste: 'salty'
}
});
var SweetyModel = Backbone.Model.extend({
defaults: {
taste: 'sweet'
}
});
var BoringModel = Backbone.Model.extend({
defaults: {
taste: null
}
});
// Set up a collection
var Collection = Backbone.Collection.extend({
model: {
chosen: function (rawData) {
if (rawData.spice === 'salt') {
return SaltyModel;
}
if (rawData.spice === 'sugar') {
return SweetyModel;
}
return BoringModel;
}
}
});
// Set up the static data
var flavours = [{
id: 1,
spice: 'salt'
}, {
id: 2,
spice: 'sugar'
}, {
id: 3,
spice: 'sour'
}];
// Init collection with mock data
var collection = new Collection(flavours);
collection.get(1) instanceof SaltyModel // true
collection.get(2) instanceof SweetyModel // true
collection.get(3) instanceof BoringModel // true If you're interested in helping with code and questions, please see the issues list and stack overflow tag here, you can also reach me on twitter:
If you have an idea to improve Backbone.Chosen or want to report a bug, please use the issues list.
Theses libraries are required for the use, development, testing and documentation of Backbone.Chosen.
Backbone.Chosen currently works with the following versions of these libraries:
- Backbone v0.9.2
- Underscore v1.3.3
Backbone.Chosen has not been tested against any other versions of these libraries. You may or may not have success if you use a version other than what it listed here.
I use a number of tools to build, test and maintain Backbone.Chosen, including but not limited to:
The Grunt project is used to generate the builds for Backbone.Chosen.
Backbone.Chosen is also tested with the QUnit JavaScript test utility, using the PhantomJS runner.
Backbone.Chosen uses Travis CI as a post commit hook, to ensure that it´s tests are passing and assures that the coding guidelines are passed using JSHint
I'm using Docco to generate the annotated source code together with the great DocMaps service.
- Added: A bunch of tests covering the basic functionality
- Added: Examples and documentation in the readme
- Added: A few more inline type tests to check the types of the chosen properties
- Initial realease
Copyright (c) 2012 Sebastian Golasch, asciidisco
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.