backbone.schema v1.0.2

Backbone.Schema

This plugin allow you define schemas for your models. It provides type control, computable properties, references between models and collections, filters and localization.

Dependencies:

• Backbone >= 1.1.0
• Underscore >= 1.5.2

For date/number formatting:

• Globalize >= 0.1.1

Globalize is not a hard dependency, it is only needed if you wish to use date and numbers formatting, or localization features.

Getting Started

Create model and schema

First you need to define model and schema.

var model = new Backbone.Model(), schema = new Backbone.Schema(model);

Define properties

Now you got instances of model and schema and you can start defining properties of the model. Use schema.define(attribute, options) method to do it.

Option type

Type string

Converts value to string. Represents as is.

schema.define('string-property', { type: 'string' });

model.set('string-property', 999999.99); // --> "999999.99"
model.get('string-property'); // <-- "999999.99"

Type boolean

Converts value to boolean. Represents as is.

schema.define('boolean-property', { type: 'boolean' });

model.set('boolean-property', 'true'); // --> true
model.get('boolean-property'); // <-- true

Type number

Converts value to number. Represents as is, or as formatted string (depends from option format).

Additional options:

• format - see more about number formatting
• culture - see more about cultures

schema.define('number-property', { type: 'number', format: 'n', culture: 'en' });

model.set('number-property', '999,999.99'); // --> 999999.99
model.get('number-property'); // <-- "999,999.99"

Type datetime

Converts value to Date, ISO 8601, or Unix time. Represents as is, or as formatted string (depends from option format).

Additional options:

• format - see more about date formatting
• standard (available values are iso and unix) - defines in which way date will be stored in the model (if not specified, date will be stored as Date)
• culture - see more about cultures

schema.define('datetime-property', { type: 'datetime', format: 'd', standard: 'unix', culture: 'en' });

model.set('datetime-property', '12/12/2012'); // --> 1355263200000
model.get('datetime-property'); // <-- "12/12/2012"

Type locale

Converts value to key of localization. Represents as is, or as string of localization (depends from availability of localization).

Additional options:

• culture - see more about cultures and localization

Globalize.addCultureInfo('en', {
    messages: {
        'HELLO_WORLD': 'Hello, World!'
    }
});

schema.define('locale-property', { type: 'locale', culture: 'en' });

model.set('locale-property', 'Hello, World!'); // --> "HELLO_WORLD"
model.get('locale-property'); // <-- "Hello, World!"

Define properties of array type

Option array

Besides listed above data types you can define arrays. To do this just use option array instead of type. For example: { array: 'string' }, { array: 'number' } etc. In this case each item in array will be processed by corresponding handler.

Define computed property

You can define a computed properties with your own custom logic.

Options getter and setter

Manipulate these two options to describe behavior of a computed property.

var User = Backbone.Model.extend({
    initialize: function () {
        var schema = new Backbone.Schema(this);

        schema.define('fullName', {
            getter: function (attribute, value) {
                var firstName = this.model.get('firstName'),
                    lastName = this.model.get('lastName');

                return firstName + ' ' + lastName;
            },

            setter: function (attribute, value) {
                var fullName = value.match(/\S+/g);

                return {
                    firstName: fullName[0],
                    lastName: fullName[1]
                };
            }
        });
    }
});

var user = new User({
    firstName: 'Dmytro',
    lastName: 'Nemoga'
});

user.get('fullName'); // <-- "Dmytro Nemoga"
user.set('fullName', 'Andriy Serputko'); // --> firstName: "Andriy", lastName: "Serputko"

Define nested models and collections

Option model

Converts value to model, using value as a set of attributes. Represents as is.

Additional options:

• clear - if true, model removes an existing attributes before setting new (otherwise merges them)

schema.define('nested-model', { model: Backbone.Model });

model.set('nested-model', { id: 0, value: 'foo' }); // --> new Backbone.Model({ id: 0, value: 'foo' })
model.get('nested-model'); // <-- instance of Backbone.Model

Option collection

Converts value to collection, using value as a set of attributes. Represents as is.

Additional options:

• reset - if true, collection removes an existing models before creating new (otherwise merges them)

schema.define('nested-collection', { collection: Backbone.Collection });

model.set('nested-collection', [ // --> new Backbone.Collection([
    { id: 1, value: 'bar' },     //         { id: 1, value: 'bar' },
    { id: 2, value: 'baz' },     //         { id: 2, value: 'baz' },
    { id: 3, value: 'qux' }      //         { id: 3, value: 'qux' }
]);                              //     ])

model.get('nested-collection'); // <-- instance of Backbone.Collection

Define reference models and collections

Before using reference models or collections make sure that you have a source collection.

var sourceCollection = new Backbone.Collection([
    { id: 0, value: 'foo' },
    { id: 1, value: 'bar' },
    { id: 2, value: 'baz' },
    { id: 3, value: 'qux' }
]);

Option source

If you pass collection in this option, plugin tries to get model from it.

Type model

Converts value (a model ID in the source collection) to model, keeping reference to original model. Represents as is.

schema.define('reference-model', { type: 'model', source: sourceCollection });

model.set('reference-model', 0); // --> sourceCollection.get(0)
model.get('reference-model'); // <-- instance of Backbone.Model

Type collection

Converts value (a set of model IDs in the source collection) to collection, keeping references to original models. Represents as is.

schema.define('reference-collection', { type: 'collection', source: sourceCollection });

model.set('reference-collection', [ // --> new Backbone.Collection([
    1,                              //         sourceCollection.get(1),
    2,                              //         sourceCollection.get(2),
    3                               //         sourceCollection.get(3)
]);                                 //     ])

model.get('reference-collection'); // <-- instance of Backbone.Collection

Option toJSON

Backbone.Schema allows you to choose between several alternatives for the JSON representation of an attribute.

Possible values:

• true (default) - the default Backbone behavior. The value will be the same value that is kept in the model.attributes array. In Backbone.Scheme context this is value after a setter method have set the value.
• 'getter' - JSON will be the value that is returned from a getter function, either an explicit getter, or an implicit getter of a Backbone.Scheme type.
• function - a function of the form function(attribute, value, options) will return the JSON representation.

• false - The attribute will not appear in the JSON representation.

  Examples:

    schema.define({
        'json-getter': { type: 'datetime', format: 'd', toJSON: 'getter' },
        'json-function': { type: 'string', toJSON: function(attribute, value, options){
            return value.toLowerCase();
        } },
        'json-false': {type: 'string', toJSON: false},
  
        'json-getter-array': { array: 'datetime', format: 'd', toJSON: 'getter' },
        'json-function-array': { array: 'string', toJSON: function(attribute, value, options){
            return value.toLowerCase();
        } },
        'json-false-array': { array: 'string', toJSON: false}
    })
  
    model.set({
      'json-getter': '12/12/2012',
      'json-function': 'Hello World',
      'json-false': 'Should not be in json',
  
      'json-getter-array': ['12/12/2012', '11/11/2011'],
      'json-function-array': ['Hello', 'World'],
      'json-false-array': ['should', 'not', 'be', 'in', 'json']
    })
  
    model.toJSON() // returns:
      'json-getter': '12/12/2012',
      'json-function': 'hello world',
  
      'json-getter-array': ['12/12/2012', '11/11/2011'],
      'json-function-array': ['hello', 'world']
    {
  
    }

Keeping integrity

The plugin prevents setting undefined values, instead of this it assigns a default value or null for regular properties, {} for models and [] for collections and arrays.

Changelog

1.0.0

• Added AMD support
• Added toJSON option
• bugfixes

0.4.10

• Fixed issue with nested models and collections

• Removed Globlize as hard dependency.

0.4.9

• Fixed issue with nested models and collections

0.4.8

• Backbone.Schema could be extended

0.4.7

• Added CommonJS support

0.4.6

• Removed text type
• number and datetime requires format option for string output

0.4.4

• Fixed behavior for model and collection types

0.4.3

• Renaming option reset to clear for model type
• Changed default behavior for model and collection types

0.4.1

• Renaming types to handlers
• Method refresh moved from model to schema
• Removed backward reference to schema

0.3.8

• refresh affects only registered attributes
• model and collection attributes cannot be null

0.3.6

• Option arrayOf renamed to array
• Option fromSource renamed to source

0.3.4

• Added option to use a custom culture

0.3.3

• Fixed serious issue with model type

0.3.2

• Handlers currency and percent merged into number

0.3.1

• Plugin implemented as decorator, not a class
• Option reset for model and collection types

0.2.9

• Properties are configurable with additional options
• Formatters and converters merged into types
• Added support of reference models and collections
• A lot of fixes

0.2.5

• Added support of nested models and collections

0.2.4

• Support of arrays
• Added type locale
• Removed method toJSON

0.2.1

• Formatters and converters takes only value argument

0.2.0

• Static methods runs in correct context, now they may be used as independent helpers

0.1.9

• Properties formatters and converters is static

0.1.8

• Removed CommonJS support

0.1.7

• Added CommonJS support

0.1.6

• Integration with project Backbone.Accessors
• Method defineProperty renamed to property
• Methods addGetter/addSetter merged to method computed
• Option advanced of toJSON method renamed to schema

0.1.2

• Removed argument options of defineProperty method's

0.1.1

• Method addProperty renamed to defineProperty

0.1.0

• Initial release