search

AmpersandJS / ampersand-view

A smart base view for Backbone apps, to make it easy to bind collections and properties to the DOM.
http://ampersandjs.com
MIT License
92 stars 39 forks source link
ampersand

readme

ampersand-view

Lead Maintainer: Rick Butler

A set of common helpers and conventions for using as a base view for ampersand.js apps.

What does it do?

  1. Gives you a proven pattern for managing/binding the contents of an element.
  2. Simple declarative property/template bindings without needing to include a template engine that does it for you. This keeps your logic out of your templates and lets you use a string of HTML as a fully dynamic template or just a simple function that returns an HTML string.
  3. The view's base element is replaced (or created) during a render. So, rather than having to specify tag type and attributes in javascript in the view definition you can just include that in your template like everything else.
  4. A way to render a collection of models within an element in the view, each with their own view, preserving order, and doing proper cleanup when the main view is removed.
  5. A simple way to render sub-views that get cleaned up when the parent view is removed.

Part of the Ampersand.js toolkit for building clientside applications.

install

npm install ampersand-view

API Reference

Note that this is a fork of Backbone's view so most of the public methods/properties here still exist: http://backbonejs.org/#View.AmpersandView extends AmpersandState so it can have it's own props values for example and can be bound directly to the template without a backing model object.

extend AmpersandView.extend([properties])

Get started with views by creating a custom view class. Ampersand views have a sane default render function, which you don't necessarily have to override, but you probably will wish to specify a template, your declarative event handlers and your view bindings.

var PersonRowView = AmpersandView.extend({
    template: "<li> <span data-hook='name'></span> <span data-hook='age'></span> <a data-hook='edit'>edit</a> </li>",

    events: {
        "click [data-hook=edit]": "edit"
    },

    bindings: {
        "model.name": {
            type: 'text',
            hook: 'name'
        },

        "model.age": {
            type: 'text',
            hook: 'age'
        }
    },

    edit: function () {
        //...
    }
});

template AmpersandView.extend({ template: "<div><input></div>" })

The .template is a property for the view prototype. It should either be a string of HTML or a function that returns a string of HTML or a DOM element. It isn't required, but it is used as a default for calling renderWithTemplate.

The important thing to note is that the returned string/HTML should not have more than one root element. This is because the view code assumes that it has one and only one root element that becomes the .el property of the instantiated view.

For more information about creating, and compiling templates, read the templating guide.

autoRender AmpersandView.extend({ autoRender: true })

The .autoRender property lets you optionally specify that the view should just automatically render with all the defaults. This requires that you at minimum specify a template string or function.

By setting autoRender: true the view will simply call .renderWithTemplate for you (after your initialize method if present). So for simple views, if you've got a few bindings and a template your whole view could just be really declarative like this:

var AmpersandView = require('ampersand-view');

module.exports = AmpersandView.extend({
    autoRender: true,
    template: '<div><span id="username"></span></div>',
    bindings: {
        name: '#username'
    }
});

Note: if you are using a template function (and not a string) the template function will get called with a context argument that looks like this, giving you access to .model, .collection and any other props you have defined on the view from the template.

this.renderWithTemplate(this, this.template);

events AmpersandView.extend({ events: { /* ...events hash... */ } })

The events hash allows you to specify declarative callbacks for DOM events within the view. This is much clearer and less complex than calling el.addEventListener('click', ...) everywhere.

Using the events hash has a number of benefits over manually binding events during the render call:

var DocumentView = AmpersandView.extend({

  events: {
    //bind to a double click on the root element
    "dblclick"                : "open",

    //bind to a click on an element with both 'icon' and 'doc' classes
    "click .icon.doc"         : "select",

    "contextmenu .icon.doc"   : "showMenu",
    "click .show_notes"       : "toggleNotes",
    "click .title .lock"      : "editAccessLevel",
    "mouseover .title .date"  : "showTooltip"
  },

  open: function() {
    window.open(this.model.viewer_url);
  },

  select: function() {
    this.model.selected = true;
  },

  //...

});

Note that the events definition is not merged with the superclass definition. If you want to merge events from a superclass, you have to do it explicitly:

var SuperheroRowView = PersonRowView.extend({
  events: _.extend({}, PersonRowView.prototype.events, {
    'click [data-hook=edit-secret-identitiy]': 'editSecretIdentity'
  })
});

bindings

The bindings hash gives you a declarative way of specifying which elements in your view should be updated when the view's model is changed.

For a full reference of available binding types see the ampersand-dom-bindings section.

For example, with a model like this:

var Person = AmpersandModel.extend({
    props: {
        name: 'string',
        age: 'number',
        avatarURL: 'string'
    },
    session: {
        selected: 'boolean'
    }
});

and a template like this:

<!-- templates.person -->
<li>
  <img data-hook="avatar">
  <span data-hook="name"></span>
  age: <span data-hook="age"></span>
</li>

you might have a binding hash in your view like this:

var PersonView = AmpersandView.extend({
    templates: templates.person,

    bindings: {
        'model.name': {
            type: 'text',
            hook: 'name'
        },

        'model.age': '[data-hook=age]', //shorthand of the above

        'model.avatarURL': {
            type: 'attribute',
            name: 'src',
            hook: 'avatar'
        },

        //no selector, selects the root element
        'model.selected': {
            type: 'booleanClass',
            name: 'active' //class to toggle
        }
    }
});

Note that the bindings definition is not merged with the superclass definition. If you want to merge bindings from a superclass, you have to do it explicitly:

var SuperheroRowView = PersonRowView.extend({
  bindings: _.extend({}, PersonRowView.prototype.bindings, {
    'model.secretIdentity': '[data-hook=secret-identity]'
  })
});

el view.el

All rendered views have a single DOM node which they manage, which is acessible from the .el property on the view. Allowing you to insert it into the DOM from the parent context.

var view = new PersonView({ model: me });
view.render();

document.querySelector('#viewContainer').appendChild(view.el);

constructor new AmpersandView([options])

The default AmpersandView constructor accepts an optional options object, and:

Typical use-cases for the options hash:

initialize new AmpersandView([options])

Called by the default view constructor after the view is initialized. Overwrite initialize in your views to perform some extra work when the view is initialized. Initially it's a noop:

var MyView = AmpersandView.extend({
    initialize: function (options) {
        console.log("The options are:", options);
    }
});

var view = new MyView({ foo: 'bar' });
//=> logs 'The options are: {foo: "bar"}'

If you want to extend the initialize function of a superclass instead of redefining it completely, you can explicitly call the initialize of the superclass at the right time:

var SuperheroRowView = PersonRowView.extend({
  initialize: function () {
    PersonRowView.prototype.initialize.apply(this, arguments);
    doSomeOtherStuffHere();
  })
});

render view.render()

Render is a part of the Ampersand View conventions. You can override the default view method when extending AmpersandView if you wish, but as part of the conventions, calling render should:

The default render looks like this:

render: function () {
    this.renderWithTemplate(this);
    return this;
}

If you want to extend the render function of a superclass instead of redefining it completely, you can explicitly call the render of the superclass at the right time:

var SuperheroRowView = PersonRowView.extend({
  render: function () {
    PersonRowView.prototype.render.apply(this, arguments);
    doSomeOtherStuffHere();
  })
});

ampersand-view triggers a 'render' event for your convenience, too, if you want to set listeners for it. The 'render' and 'remove' events emitted by this module are merely convenience events, as you may listen solely to change:rendered in order to capture the render/remove events in just one listener.

renderCollection view.renderCollection(collection, ItemView, containerEl, [viewOptions])

This method will maintain this collection within that container element. Including proper handling of add, remove, sort, reset, etc.

Also, when the parent view gets .remove()'ed any event handlers registered by the individual item views will be properly removed as well.

Each item view will only be .render()'ed once (unless you change that within the item view itself).

The collection view instance will be returned from the function.

Example:

// some views for individual items in the collection
var ItemView = AmpersandView.extend({ ... });
var AlternativeItemView = AmpersandView.extend({ ... });

// the main view
var MainView = AmpersandView.extend({
    template: '<section class="page"><ul class="itemContainer"></ul></section>',
    render: function (opts) {
        // render our template as usual
        this.renderWithTemplate(this);

        // call renderCollection with these arguments:
        // 1. collection
        // 2. which view to use for each item in the list
        // 3. which element within this view to use as the container
        // 4. options object (not required):
        //      {
        //          // function used to determine if model should be included
        //          filter: function (model) {},
        //          // boolean to specify reverse rendering order
        //          reverse: false,
        //          // view options object (just gets passed to item view's `initialize` method)
        //          viewOptions: {}
        //      }
        // returns the collection view instance
        var collectionView = this.renderCollection(this.collection, ItemView, this.el.querySelector('.itemContainer'), opts);
        return this;
    }
});

// alternative main view
var AlternativeMainView = AmpersandView.extend({
    template: '<section class="sidebar"><ul class="itemContainer"></ul></section>',
    render: function (opts) {
        this.renderWithTemplate(this);
        this.renderCollection(this.collection, function (options) {
            if (options.model.isAlternative) {
                return new AlternativeItemView(options);
            }

            return new ItemView(options);
        }, this.el.querySelector('.itemContainer'), opts);
        return this;
    }
});

renderWithTemplate view.renderWithTemplate([context], [template])

This is shortcut for the default rendering you're going to do in most every render method, which is: use the template property of the view to replace this.el of the view and re-register all handlers from the event hash and any other binding as described above.

var view = AmpersandView.extend({
    template: '<li><a></a></li>',
    bindings: {
        'name': 'a'
    },
    events: {
        'click a': 'handleLinkClick'
    },
    render: function () {
        // this does everything
        // 1. renders template
        // 2. registers delegated click handler
        // 3. inserts and binds the 'name' property
        //    of the view's `this.model` to the <a> tag.
        this.renderWithTemplate();
    }
});

query view.query('.classname')

Runs a querySelector scoped within the view's current element (view.el), returning the first matching element in the dom-tree.

notes:

var view = AmpersandView.extend({
    template: '<li><img class="avatar" src="https://github.com/AmpersandJS/ampersand-view/raw/master/"></li>',
    render: function () {
        this.renderWithTemplate(this);

        // cache an element for easy reference by other methods
        this.imgEl = this.query(".avatar");

        return this;
    }
});

queryByHook view.queryByHook('hookname')

A convenience method for retrieving an element from the current view by it's data-hook attribute. Using this approach is a nice way to separate javascript view hooks/bindings from class/id selectors that are being used by CSS.

notes:

var view = AmpersandView.extend({
    template: '<li><img class='avatar-rounded' data-hook="avatar" src="https://github.com/AmpersandJS/ampersand-view/raw/master/"></li>',
    render: function () {
        this.renderWithTemplate(this);

        // cache an element for easy reference by other methods
        this.imgEl = this.queryByHook('avatar');

        return this;
    }
});

queryAll view.queryAll('.classname')

Runs a querySelectorAll scoped within the view's current element (view.el), returning an array of all matching elements in the dom-tree.

notes:

queryAllByHook view.queryAllByHook('hookname')

Uses queryAll method with a given data-hook attribute to retrieve all matching elements scoped within the view's current element (view.el), returning an array of all matching elements in the dom-tree or an empty array if no results has been found.

cacheElements view.cacheElements(hash)

A shortcut for adding reference to specific elements within your view for access later. This is avoids excessive DOM queries and makes it easier to update your view if your template changes. It returns this.

In your render method. Use it like so:

render: function () {
  this.renderWithTemplate(this);

  this.cacheElements({
    pages: '#pages',
    chat: '#teamChat',
    nav: 'nav#views ul',
    me: '#me',
    cheatSheet: '#cheatSheet',
    omniBox: '[data-hook=omnibox]'
  });

  return this;
}

Then later you can access elements by reference like so: this.pages, or this.chat.

listenToAndRun view.listenToAndRun(object, eventsString, callback)

Shortcut for registering a listener for a model and also triggering it right away.

remove view.remove()

Removes a view from the DOM, and calls stopListening to remove any bound events that the view has listenTo'd. This method also triggers a remove event on the view, allowing for listeners (or the view itself) to listen to it and do some action, like cleanup some other resources being used. The view will trigger the remove event if remove() is overridden.

initialize : function() {
  this.listenTo(this,'remove',this.cleanup);
  // OR this, either statements will call 'cleanup' when `remove` is called
  this.once('remove',this.cleanup, this);
},

cleanup : function(){
  // do cleanup
}

registerSubview view.registerSubview(viewInstance)

This method will:

  1. store a reference to the subview for cleanup when remove() is called.
  2. add a reference to itself at subview.parent
  3. return the subview

renderSubview view.renderSubview(viewInstance, containerEl)

This method is just sugar for the common use case of instantiating a view and putting in an element within the parent.

It will:

  1. fetch your container (if you gave it a selector string)
  2. register your subview so it gets cleaned up if parent is removed and so this.parent will be available when your subview's render method gets called
  3. call the subview's render() method
  4. append it to the container (or the parent view's el if no container given)
  5. return the subview
var view = AmpersandView.extend({
    template: '<li><div class="container"></div></li>',
    render: function () {
        this.renderWithTemplate();

        //...

        var model = this.model;
        this.renderSubview(new SubView({
            model: model
        }), '.container');

        //...

    }
});

subviews view.subviews

You can declare subviews that you want to render within a view, much like you would bindings. Useful for cases where the data you need for a subview may not be available on first render. Also, simplifies cases where you have lots of subviews.

When the parent view is removed the remove method of all subviews will be called as well.

You declare them as follows:

var AmpersandView = require('ampersand-view');
var CollectionRenderer = require('ampersand-collection-view');
var ViewSwitcher = require('ampersand-view-switcher');

module.exports = AmpersandView.extend({
    template: '<div><div></div><ul data-hook="collection-container"></ul></div>',
    subviews: {
        myStuff: {
            selector: '[data-hook=collection-container]',
            waitFor: 'model.stuffCollection',
            prepareView: function (el) {
                return new CollectionRenderer({
                    el: el,
                    collection: this.model.stuffCollection
                });
            }
        },
        tab: {
            hook: 'switcher',
            constructor: ViewSwitcher
        }
    }
});

subview declarations consist of:

delegateEvents view.delegateEvents([events])

Creates delegated DOM event handlers for view elements on this.el. If events is omitted, will use the events property on the view.

Generally you won't need to call delegateEvents yourself, if you define an event hash when extending AmpersandView, delegateEvents will be called for you when the view is initialize.

Events is a hash of {"event selector": "callback"}*

Will unbind existing events by calling undelegateEvents before binding new ones when called. Allowing you to switch events for different view contexts, or different views bound to the same element.

{
  'mousedown .title':  'edit',
  'click .button':     'save',
  'click .open':       function (e) { ... }
}

undelegateEvents view.undelegateEvents()

Clears all callbacks previously bound to the view with delegateEvents. You usually don't need to use this, but may wish to if you have multiple views attached to the same DOM element.

changelog

test coverage?

Why yes! So glad you asked :)

like this?

Follow @HenrikJoreteg on twitter and check out my recently released book: human javascript which includes a full explanation of this as well as a whole bunch of other stuff for building awesome single page apps.

license

MIT