backbone.viewdsl

Backbone.ViewDSL

Backbone.ViewDSL provides declarative view technology on top of Backbone.

The main feature of Backbone.ViewDSL is an extensible DOM templating engine which allows you to

• Interpolate string or DOM values
• Instantiate sub-views directly from inside templates
• Bind data to DOM text nodes or element attributes
• Automatically setup references for DOM nodes being rendered
• Create custom directives as custom HTML tags or attributes

To give a taste of these features there's a basic example

class App extends Backbone.ViewDSL.View
  template: """
    <h1 element-id="$header">{{bind:user.name}}'s todos</h1>
    <view name="views:UserCard" model="user"></view>
    <foreach collection="todos">
      <view name="views:TodoView"></view>
    </foreach>
    """

This work was mainly inspired by Angular.js but tries to stay as close to Backbone style as possible so it is very easy to use in your application in a completely non-intrusive way.

Installation

You can grab compiled JavaScript code from the repo or use npm:

% npm install backbone.viewdsl

or bower package managers:

% bower install backbone.viewdsl

The only dependencies are jQuery, Backbone and underscore.js — if you use one of the package managers they will be installed automatically, otherwise you should download them by hand.

Backbone.ViewDSL designed to work in CommonJS environment as well as with any available AMD loader (such as RequireJS). If you don't use nor AMD neither CommonJS loading strategies then all the public API will be available through the Backbone.ViewDSL browser global.

Basic usage

The main usage pattern is exposed via Backbone.ViewDSL.View subclass of Backbone.View with a custom implementation of render() method.

Usually you want to define a new subclass of it and set a template attribute:

class Message extends Backbone.ViewDSL.View
  template: """
    {{greeting}}, {{options.name}}!
    """

  greeting: ->
    'Hello'

view = new Message(name: 'World')
view.render()

This template uses string interpolation to insert options.name value and a result of greeting() method call inside the DOM text node. That way view's el DOM element will have a form of <div>Hello, World!</div>.

Templates are always rendered in the context of a view so we can reference any view's attribute inside them or call any methods without arguments. If you need to reach some nested attribute or method then you can use usual dotted-path like a.b.c.

Sub-views instantiation

Backbone doesn't have an opinion on how to manage view hierarchies inside your application so usually you cook something by yourself.

Backbone.ViewDSL tries to make this task a lot easier by providing you with a view directive which allows instantiating sub-views right from inside templates. The directive can be used as a <view> DOM element or view DOM attribute.

The example would be

class App extends Backbone.ViewDSL.View
  template: """
    <view name="views.Sidebar" model="user" id="sidebar"></view>
    <footer view="views.Footer" view-model="user" view-id="footer"></footer>
    """

app = new App
app.render()

This snippet of code alone makes a lot of things under the hood.

View views.Sidebar will be rendered and app.user will be passed into its constructor as a model option. After that rendered view will be stored as app.sidebar attribute.

There's a bit different story with views.Footer — it also gets app.user as a constructor model option but instead of creating new DOM node for the view itself it will reuse <footer> element. That could be useful if you don't know before with what kind of element view will be used.

Without using Backbone.ViewDSL all of these would look like this:

class App extends Backbone.View

  render: ->
    this.sidebar = new Sidebar(model: this.user)
    this.sidebar.render()
    this.$el.append(this.sidebar.$el)

    this.footer = new Footer(model: this.user, tagName: 'footer')
    this.footer.render()
    this.$el.append(this.footer.$el)

The variant which uses Backbone.ViewDSL.ViewDSL looks a lot cleaner, doesn't it? Also Backbone.ViewDSL.View keeps track of all instantiated sub-views and handles its disposal so no memory leaks will happen.

String and DOM values interpolation

As it was already shown Backbone.ViewDSL allows you to insert specific bits of text inside templates. But what's more interesting — you can also insert entire DOM elements into templates, even with attached event handlers.

class View extends Backbone.ViewDSL.ViewDSL
  template: """
    {{element}} {{jquery}}
    """
  element: ->
    document.createElement('div')
  jquery: ->
    $('<div>').addClass('klass')

Rendered view will have <div></div> <div class="klass"></div> as its content. As you can see you can also insert jQuery objects into template.

Referencing DOM nodes

Sometimes you need to reference DOM element from recently rendered template — you can select it by using this.$ method call but a better way would be to use element-id attribute directive.

class View extends Backbone.ViewDSL.View
  template: """
    <div class="main" element-id="block"></div>
    """

view = new View
view.render()

That way rendered <div> element will be available as view.block attribute.

Other built-in directives

There are a couple of other built-in directives — attr-* and class-* wildcard directives and show-if directive.

The attr-* directive can be used to attach attributes to DOM elements based on some view's value. For example given the template

<img attr-src="model.imageURL">

We will get src attribute set to value of model.imageURL view's attribute. There's also a special case for attributes which has boolean interpretation (checked, contenteditable and so on...) — if expression evaluates to Boolean value then attribute will be present if value is true in case of false value attribute will not be rendered.

class View extends Backbone.ViewDSL.View
  template: """
    <h1 attr-contenteditable="isEditable">title</h1>
    """
  isEditable: ->
    this.model.get('isEditable') and this.user.canEdit(this.model)

Note that isEditable method returns boolean value.

The class-* wildcard directive works like a attr-* directive but instead regulates if element should receive an additional CSS class based on some view's attribute or method.

class View extends Backbone.ViewDSL.View
  template: """
    <h1 class-editable="isEditable">title</h1>
    """
  isEditable: ->
    this.model.get('isEditable') and this.user.canEdit(this.model)

In this example, <h1> will have class editable if and only if isEditable method evaluates to true.

The last of the built-in directives — show-if controls if element is visible based on some expression which evaluates to boolean value:

<div show-if="this.collection.isEmpty">No items"</div>

The <div> element will be displayed only if this.collection.isEmpty() evaluates to true. Methods $.show() and $.hide() are used to correspondingly show and hide elements.

Data-binding

You want your views to react to underlying data changes but manually maintaining a set of change event handlers isn't an option.

For that reason a part of Backbone.ViewDSL directives like attr-*, class-* and show-if as well as interpolation mechanism allows you to bind their action on data changes and react to them accordingly.

To turn data-binding on you have to prefix all expressions with bind: modifier:

class View extends Backbone.ViewDSL.View
  redAllowed: true

  template: """
    <div class-red="bind:isRed">Hello, {{bind:model.name}}!</div>
    """

  isRed: ->
    this.model.get('red') and this.redAllowed

view = new View(model: new Backbone.Model(name: 'World', red: false))
view.render()

That way rendered view's el will have

<div>Hello, World!</div>

as its innerHTML and it will react to data changes according to directive actions. So this snippet of code

view.model.set(name: 'Commrade', red: true)

will result el.innerHTML having different contents

<div class="red">Hello, Commrade!</div>

Remember that bind: modifier also works with attr-* and show-if directives.

Creating custom directives

Rendering collections

Parametrizable views