Backbone View Mediator

npm install backbone-view-mediator

The BackboneViewMediator makes management of your Backbone Views simple.

1. You have some layout html that describes the containers for your views (or 'regions')
2. You need a simple way to render a batch of views on route change
3. Whenever you render a set of views, you need to clean up any views you don't need anymore

To accomplish this with Backbone, you generally need to keep track of what views you have rendered and what are not render. This way you can clean up and call undelegateEvents on views being removed, and render on views being added. You may also want to not re-render views that are common between routes, so more complexity is added there as well.

The BackboneViewMediator manages all of the above, so (for the most part) all you have to do is call .render() and it will take care of the rest.

A Simple Example

The ViewMediator is constructed with a simple configuration object.

var HomeView = require('./views/HomeView'),
    AboutView = require('./views/AboutView'),
    NavbarView = require('./views/NavbarView')

var bvm = new BackboneViewMediator({
    el: 'body',
    layout: "<div id='navbar-region'></div><div id='content-region'></div>",
    views: {
        'HomeView': HomeView,
        'AboutView': AboutView,
        'NavbarView': NavbarView
    }
})

el
The query-selector string for the element the ViewMediator should mount to.

layout
A string representing the html used by the ViewMediator. Should simply contain the arrangement of regions you'd like to render your views in. These should be identifiable by id's or unique queryable attribute.

views
This an object with Backbone.View factory constructors indexed by the names the ViewMediator will refer to them by henceforth.

The Views

The ViewMediator does not attach anything to your views. Instead it expects them to have several functions which will be called as the ViewMediator manages their cycle. In the above example, here is what the "HomeView" may look like:

var HomeView = Backbone.View.extend({

    template: _.template("<h3><%- model.attributes.message %></h3>"),

    initialize: function (params) {
        this.model = new Backbone.Model({
            message: params.message
        })

        this.listenTo(this.model, 'change', this.render.bind(this))
    },

    render: function () {
        this.$el.html(
            this.template({model: this.model})
        )
    },

    update: function (params) {
        this.model.set('message', params.message)
    },

    remove: function () {
        this.undelegateEvents()
        this.stopListening()
    }

})

initialize
Will be called when the ViewMediator constructs a new instance of the view from its constructor, in preperation for mounting the resulting instance of that view. If any params are passed to the view

render
This is called after initialization. Between this point and render, the ViewMediator automatically calls setElement for the view, so the el and $el attribute of the view is available. Neither initialize or render will be called if the view has previously been told to rendered and not removed since. The exception is if a view was previously rendered to a different host-region and it is being moved. In this case it will be removed and re-rendered.

update
The ViewMediator is smart enough to not tell a view to re-render if it is already rendered. However, often you will want a view to update in response to a route change.

routes: {
    'articles/:id': function (articleId) {
        bvm.render({
            'NavbarView': '#navbar-region',
            'ArticleView': {
                el: '#content-region',
                params: {articleId: articleId}
            }
        })
    }
}

In the above case, a user might go from route articles/5 to articles/24. The ViewMediator has already rendered "ArticleView" so it will not re-render it. However, the second time it will call .update so you can respond to these changes accordingly. If a view does not have an update function (it is optional) nothing will be done.

A good pattern is to create a local Backbone Model when a view is initialized. Have that model listen for updates and respond by re-calling render. The update function of the view can then call set on the model and the view will re-render appropriately ( see the first "HomeView" example).

The update functions receieves the params as its first argument, just as the initialize function.

remove
This function is called whenever the ViewMediator removes the view. The conditions in which this happens are either the view is no longer present in a subsequent call to render, or the region of the view has changed since last render so it must be removed from it's current node.

Whenever a view is not present in a .render() call to the ViewMediator, it will be removed.