Skip to content
This repository

Knockout-inspired declarative bindings for Backbone.js

tree: 805a62d43c

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 examples
Octocat-spinner-32 lib
Octocat-spinner-32 spec
Octocat-spinner-32 README.md
Octocat-spinner-32 TODO
Octocat-spinner-32 outback.js
README.md

outback is a JavaScript library that extends Backbone.js with support for Knockout-inspired declarative bindings.

tl;dr

Sprinkle data-bind attributes into your templates:

<!-- adds the CSS class 'editing' to the div when the 
     viewModel's isEditing attribute is true, removes it
     when it isn't -->

<div data-bind-view="css: { editing: @isEditing }">

    <!-- the input's value is two-way bound to the model's todo
         attribute, and the focus state of the control is two-way 
         bound to the viewModel's isEditing attribute -->

    <input  type="text" 
            class="todo-input" 
            data-bind="value: @todo" 
            data-bind-view="hasfocus: @isEditing">

</div>

Then setup up your view:

class TodoModel extends Backbone.Model
    defaults:
        todo: 'Learn outback.js'

class TodoView extends Backbone.View
    model: TodoModel

    # use a viewModel for transient state (optional)
    viewModel: new Backbone.Model
        isEditing: false

    @render: ->
        Backbone.outback.bind @

    @remove: ->
        Backbone.outback.unbind @

Can I configure the bindings in code instead?

Yes, outback bindings can be setup in either code or markup; feel free to mix and match.

class TodoView extends Backbone.View
    model: TodoModel

    # modelBindings (viewModelBindings) are bound to your model (viewModel)
    modelBindings:
        '#edit .todo-input': 
            value: Backbone.outback.modelRef 'todo'

    @render: ->
        Backbone.outback.bind @

    @remove: ->
        Backbone.outback.unbind @

Does this work with regular JavaScript?

Yes.

Which bindings are currently supported?

visible, text, html, css, style, attr, click, event, submit, enable, disable, value, hasfocus, checked

Can I add my own custom bindings?

Yes.

Backbone.outback.bindingHandlers['custom'] = ->

    # init is called when the view is rendered
    init: (element, valueAccessor, allBindingsAccessor) ->
        # element is a jQuery selection
        $el = element               

        # register for DOM updates
        $el.on 'change', (e) ->
            value = valueAccessor()     
            value $el.val()

    # update is called when the model changes
    update: (element, valueAccessor, allBindingsAccessor) ->
        $el = element               

        value = valueAccessor()     
        $el.val value()

    # remove is called when the view is unbound (removed)
    remove: (element, valueAccessor, allBindingsAccessor) ->
        $el = element
        $el.off 'change'

Can I include arbitrary JavaScript expressions in my data-binds?

No.

  1. data-bind attributes are handled by rj which recognizes a small superset of JSON. Specifically, the @name notation is parsed using the rules for JavaScript identifiers.
  2. Personally, I don't think it's a good idea to put that kind of logic in markup.

XSS?

The text, value, and attr bindings use model.escape instead of model.get to help defend against XSS attacks. This feature may be turned off by including escape: false in the binding configuration. The html binding uses jQuery's natural mechanism and is not overridable.

<!-- prevent outback from mangling the url -->
<a data-bind="attr: { href: @url, hrefOptions: { escape: false } }"></a>

Todos?

In progress

A little more documentation would be helpful...

Working on it, but for now refer to the examples, specs, and source.

License

The MIT License

Copyright (c) 2012 David Zarlengo 

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.
Something went wrong with that request. Please try again.