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
remove
on it..el
property that is the root element of the view..remove()
method that cleans up and unbinds methods accordingly..render()
method it will get called before it's shown.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');
}
});
new ViewSwitcher(element, [options])
element
{Element} The DOM element that should contain the views.options
{Object} [optinal]show
{Function} [optional] A function that gets called when a view is being shown. It's passed the new view.hide
{Function} [optional] A function that gets called when a view is being removed. It's passed the old view and a callback. If you name 2 incoming arguments for example function (oldView, callback) { ... }
the view switcher will wait for you to call the callback before it's considered ready. If you only use one like this: function (oldView) { ... }
it won't wait for you to call a callback.waitForRemove
{Boolean} [default: false
] Whether or not to wait until your hide
animation callback gets called before starting your show
animation.empty
{Function} [optional] A function that gets called any time the view switcher is empty. Including when you instantiate it without giving it a view to start with.view
{View} [optional] A view instance to start with.var switcher = new ViewSwitcher(document.querySelector('#pageContainer'));
var view = new MyView({ model: model });
switcher.set(view);
switcher.set(viewInstance)
viewInstance
{View} The new view to render.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);
switcher.clear(callback)
callback
{Function} [optional] An optional callback when removed. Useful if you're doing custom animations.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();