ampersand-view-switcher [source]

This module does one thing: it helps you swap out views inside of an element. It's compatible with ampersand-view, backbone views and any view that has an .el, .render() and .remove()

What might you do with it?

What it does

Example

Here's an example of how you might use the view switcher to handle page views within your ampersand app.

mainview.js

var AmpersandView = require('ampersand-view');
var ViewSwitcher = require('ampersand-view-switcher');
var templates = require('./templates');

module.exports = AmpersandView.extend({
    template: templates.body,
    render: function () {
        // render our template
        this.renderWithTemplate();

        // grab the element without our template based on its "data-hook" attribute
        this.pageContainer = this.queryByHook('page-container');

        // set up our page switcher for that element
        this.pageSwitcher = new ViewSwitcher(this.pageContainer, {
            // here we provide a few things we'd like to do each time
            // we switch pages in the app.
            show: function (view) {
                // set our document title
                document.title = view.pageTitle || 'my awesome app';
                // scroll to the top
                document.body.scrollTop = 0;
                // perhaps store a reference to our current page on our
                // app global for easy access from the browser console.
                app.currentPage = view;
            }
        });
    } 
});

Or if you wanted to animate them you can do it asynchronously like so:

// set up our page switcher for that element
this.pageSwitcher = new ViewSwitcher(this.pageContainer, {
    // whether or not to wait for remove to be done before starting show
    waitForRemove: true,
    // here we provide a few things to do before the element gets
    // removed from the DOM.
    hide: function (oldView, cb) {
        // it's inserted and rendered for me so we'll add a class 
        // that has a corresponding CSS transition.
        oldView.el.classList.add('animateOut');
        // give it time to finish (yes there are other ways to do this)
        setTimeout(cb, 1000);
    },
    // here we provide a few things we'd like to do each time
    // we switch pages in the app.
    show: function (newView) {
        // it's inserted and rendered for me
        document.title = newView.pageTitle || 'app name';
        document.body.scrollTop = 0;

        // store an additional reference, just because
        app.currentPage = newView;

        newView.el.classList.add('animateIn');
    }
});

API Reference

constructor new ViewSwitcher(element, [options])

var switcher = new ViewSwitcher(document.querySelector('#pageContainer'));

var view = new MyView({ model: model });

switcher.set(view);

set switcher.set(viewInstance)

The instantiated view switcher has this one main method. Simply call it with the new view you wish to show.

This is most likely going to be an instantiated ampersand-view or Backbone.View, but can be anything that has a .el property that represents that view's root element and .remove() method that cleans up after itself. In addition if your custom view object has a .render() method it will get called before the view is added to the DOM.

var switcher = new ViewSwitcher(document.querySelector('#pageContainer'));

var view = new MyView({ model: model });

switcher.set(view);

clear switcher.clear(callback)

Removes the current view from the view switcher. Calls callback when done if one was provided.`

var switcher = new ViewSwitcher(document.querySelector('#pageContainer'));

var view = new MyView({ model: model });

switcher.set(view);

switcher.clear();