backbone.databinding

Backbone.DataBinding

The plugin implements a two-way data binding between views and models/collections.

Dependencies:

• Backbone >= 1.1.0
• Underscore >= 1.5.2
• jQuery >= 2.0.3

Getting Started

Create view and model

Define the view and the model. They should be an instances of Backbone.View/Backbone.Model or their inheritors.

var view = new Backbone.View(), model = new Backbone.Model();

Create model binder

Backbone.ModelBinder is a decorator. Just pass the view and the model into constructor of class to getting started.

var modelBinder = new Backbone.ModelBinder(view, model);

Define bindings

Use modelBinder.watch(binding, options) method to define bindings between view and model. If you want to define a lot of bindings in one action use modelBinder.watch(bindings) option.

Binding types

Type html

<output name="html-content"></output>

modelBinder.watch('html: html-content', {
    selector: '[name="html-content"]'
});

model.set('html-content', 'HTML');

<output name="html-content">HTML</output>

Type text

<output name="text-content"></output>

modelBinder.watch('text: text-content', {
    selector: '[name="text-content"]'
});

model.set('text-content', 'Text');

<output name="text-content">Text</output>

Type value

Text input

<input type="text" name="text-field-value">

modelBinder.watch('value: text-field-value', {
    selector: '[name="text-field-value"]'
});

model.set('text-field-value', 'Value');

<input type="text" name="text-field-value" value="Value">

Text area

<textarea name="textarea-value"></textarea>

modelBinder.watch('value: textarea-value', {
    selector: '[name="textarea-value"]'
});

model.set('textarea-value', 'Text');

<textarea name="textarea-value">Text</textarea>

Single select

<select name="single-select-value">
    <option value="A">Option A</option>
    <option value="B">Option B</option>
    <option value="C">Option C</option>
</select>

modelBinder.watch('value: single-select-value', {
    selector: '[name="single-select-value"]'
});

model.set('single-select-value', 'A');

<select name="single-select-value">
    <option value="A" selected>Option A</option>
    <option value="B">Option B</option>
    <option value="C">Option C</option>
</select>

Multiple select

<select name="multiple-select-value" multiple>
    <option value="A">Option A</option>
    <option value="B">Option B</option>
    <option value="C">Option C</option>
</select>

modelBinder.watch('value: multiple-select-value', {
    selector: '[name="multiple-select-value"]'
});

model.set('multiple-select-value', ['A', 'B', 'C']);

<select name="multiple-select-value" multiple>
    <option value="A" selected>Option A</option>
    <option value="B" selected>Option B</option>
    <option value="C" selected>Option C</option>
</select>

Type checked

Single checkbox

<input type="checkbox" name="single-checkbox-checked">

modelBinder.watch('checked: single-checkbox-checked', {
    selector: '[name="single-checkbox-checked"]'
});

model.set('single-checkbox-checked', true);

<input type="checkbox" name="single-checkbox-checked" checked>

Multiple checkboxes

<input type="checkbox" name="checkbox-group-checked" value="A">
<input type="checkbox" name="checkbox-group-checked" value="B">
<input type="checkbox" name="checkbox-group-checked" value="C">

modelBinder.watch('checked: checkbox-group-checked', {
    selector: '[name="checkbox-group-checked"]'
});

model.set('checkbox-group-checked', ['A', 'B', 'C']);

<input type="checkbox" name="checkbox-group-checked" value="A" checked>
<input type="checkbox" name="checkbox-group-checked" value="B" checked>
<input type="checkbox" name="checkbox-group-checked" value="C" checked>

Radio buttons

<input type="radio" name="radio-button-checked" value="A">
<input type="radio" name="radio-button-checked" value="B">
<input type="radio" name="radio-button-checked" value="C">

modelBinder.watch('checked: radio-button-checked', {
    selector: '[name="radio-button-checked"]'
});

model.set('radio-button-checked', 'A');

<input type="radio" name="radio-button-checked" value="A" checked>
<input type="radio" name="radio-button-checked" value="B">
<input type="radio" name="radio-button-checked" value="C">

Type visible

<button type="button" name="button-visible" hidden>Visible</button>

modelBinder.watch('visible: button-visible', {
    selector: '[name="button-visible"]'
});

model.set('button-visible', true);

<button type="button" name="button-visible">Visible</button>

Type hidden

<button type="button" name="button-hidden">Hidden</button>

modelBinder.watch('hidden: button-hidden', {
    selector: '[name="button-hidden"]'
});

model.set('button-hidden', true);

<button type="button" name="button-hidden" hidden>Hidden</button>

Type enabled

<button type="button" name="button-enabled" disabled>Enabled</button>

modelBinder.watch('enabled: button-enabled', {
    selector: '[name="button-enabled"]'
});

model.set('button-enabled', true);

<button type="button" name="button-enabled">Enabled</button>

Type disabled

<button type="button" name="button-disabled">Disabled</button>

modelBinder.watch('disabled: button-disabled', {
    selector: '[name="button-disabled"]'
});

model.set('button-disabled', true);

<button type="button" name="button-disabled" disabled>Disabled</button>

Option selector

Specify selector to find element in the view's DOM tree. Leave selector empty to bind attribute to the root element of the view.

modelBinder.watch('...', {
    selector: 'div.foo' // Any jQuery selector
});

Option event

Specify events that you want to listen (by default equal to 'change').

modelBinder.watch('...', {
    event: 'change input keyup' // Space separated event list
});

Options getter and setter

If you want to define one-way binding you can disable getter (view-to-model binding) or setter (model-to-view binding).

modelBinder.watch('...', {
    getter: false // In this case the model will not synchronizes with the element
});

modelBinder.watch('...', {
    setter: false // In this case the element will not synchronizes with the model
});

Create view and collection

Define the view and the collection. They should be an instances of Backbone.View/Backbone.Collection or their inheritors.

var view = new Backbone.View(), collection = new Backbone.Collection();

Create collection binder

Backbone.CollectionBinder is a decorator. Just pass the view and the collection into constructor of class to getting started. Don't forget about options.

var collectionBinder = new Backbone.CollectionBinder(view, collection, {
    view: Backbone.View.extend({ ... }),
    dummy: Backbone.View.extend({ ... }),

    selector: '...'
});

Option view

It should be an instance of Backbone.View or its inheritor. It will represent each model in collection.

Option dummy

It should be an instance of Backbone.View or its inheritor. It will used in case if collection is empty and no items to be shown.

Option selector

If specified, views will be inserted into element corresponding this selector. If not, views will be inserted just to the root element of the view.

Start listening

By default Backbone.CollectionBinder listens four collection events: add, remove, reset and sort.

collectionBinder.listen();

If you don't want to listen some events you should use an additional options.

collectionBinder.listen({
    sort: false // In this case DOM will not react on collection's sorting
});

Changelog

0.4.5

• Backbone.ModelBinder and Backbone.CollectionBinder could be extended

0.4.4

• Added CommonJS support

0.4.3

• Fixed a lot of issues

0.4.2

• Renaming method define to watch
• Update API to getting views

0.4.0

• Backbone.ModelBinder and Backbone.CollectionBinder configures with any model/collection

0.3.9

• Fixed checked binding
• Using attr() instead of prop() for standard bindings

0.3.7

• Renaming types to handlers
• Method refresh moved from view to binders
• Removed backward reference to binders

0.3.4

• Fixed visible, hidden, enabled, disabled bindings

0.3.3

• Plugin implemented as decorator, not a class
• Readers and writers merged into types
• Added new binding types hidden, enabled, disabled
• A lot of fixes

0.2.9

• Readers and writers runs in context this
• Added binding type visible

0.2.7

• Method reset renamed to syncToCollection
• Changed signature of method binding

0.2.5

• Added public method reset for refreshing a list manually

0.2.4

• Added views allocation inside the root element

0.2.3

• Methods sort and reset are private

0.2.2

• ViewCollection is sortable
• Method reset is public
• Removed binding type data

0.1.9

• Items removes via collection's listener and not model's
• Added binding type data

0.1.7

• Properties readers and writers are static

0.1.6

• Removed CommonJS support
• Databinding moved to Backbone.ViewModel class
• Added Backbone.ViewCollection class

0.1.3

• Added CommonJS support

0.1.2

• Methods delegateBindings and undelegateBindings are public

0.1.1

• Method addBinding renamed to binding

0.1.0

• Initial release