View
A View is simply a JavaScript object that represents a logical chunk of UI in the DOM. The general idea is to organize your interface into logical views, backed by models, each of which can be updated independently when the model changes, without having to redraw the page. This allows you to bind your view's render function to the model's 'change' event — and now everywhere that model data is displayed in the UI, it is always immediately up to date.
Properties​
attributes​
attributes: { [key: string]: string | number };
A hash of attributes that will be set as the HTML attributes on the view's el (id, class, data-properties, etc.), or a function that returns such a hash.
el​
el: DOMElement;
All views have a DOM element at all times (the el property), whether they have already been inserted into the page or not. In this fashion, views can be rendered at any time, and inserted into the DOM all at once, in order to get high-performance UI rendering with as few reflows and repaints as possible.
this.el can be resolved from a DOM selector string or an Element; otherwise it will be created from the view's tagName, className, id and attributes properties. If none of those are set, this.el is an empty div, which is often just fine. An el reference may also be passed in to the view's constructor (see initialize()).
const ShapeView = mvc.View.extend({
el: 'body'
});
const shape = new ShapeView();
console.log(shape.el) // <body>...</body>
events​
events: { [key: string]: string };
The events hash (or method) can be used to specify a set of DOM events that will be bound to methods on your View through delegateEvents(). JointJS will automatically attach the event listeners at instantiation time, right before invoking initialize().
const ENTER_KEY = 13;
const InputView = mvc.View.extend({
tagName: 'input',
events: {
'keydown': 'keyAction',
},
render: function() {
// ...
},
// define event handler:
keyAction: function(e) {
if (e.which === ENTER_KEY) {
this.collection.add({text: this.$el.val()});
}
}
});
style​
style: { [key: string]: any };
A hash of CSS properties that will be set as inline style on the view's el (color: red;, etc.), or a function that returns such a hash.
constructor​
See initialize().
Methods​
delegateEvents()​
view.delegateEvents(events?: { [key: string]: string }): this;
Provide declarative callbacks for DOM events within a view. If an events hash is not passed directly, uses this.events as the source. Events are written in the format { 'event selector': 'callback' }. The callback may be either the name of a method on the view, or a direct function body. Omitting the selector causes the event to be bound to the view's root element (this.el). By default, delegateEvents() is called within the View's constructor for you, so if you have a simple events hash, all of your DOM events will always already be connected, and you will never have to call this function yourself.
The events property may also be defined as a function that returns an events hash, to make it easier to programmatically define your events, as well as inherit them from parent views.
Using delegateEvents() provides a number of advantages. All attached callbacks are bound to the view before being handed off, so when the callbacks are invoked, this continues to refer to the view object. When delegateEvents() is run again, perhaps with a different events hash, all callbacks are removed and delegated afresh — useful for views which need to behave differently when in different modes.
A single-event version of delegateEvents() is available as delegate(). In fact, delegateEvents() is simply a multi-event wrapper around delegate().
initialize()​
view.initialize(options?: { [key: string]: any }): void;
There are several special options that, if passed, will be attached directly to the view: model, collection, el, id, className, tagName, attributes, style and events.
const doc = documents.first();
new DocumentRow({
model: doc,
id: 'document-row-' + doc.id
});
If the view defines an initialize() function, it will be called when the view is first created. initialize() is an empty function by default - you can override it with your own view initialization logic.
If you would like to create a view that references an element already in the DOM, pass in the element as the el option:
new View({
el: existingElement
});
preinitialize()​
view.preinitialize(options?: { [key: string]: any }): void;
For use with views defined as ES classes. If you define a preinitialize() method, it will be invoked when the view is first created, before any instantiation logic is run. preinitialize() is an empty function by default - you can override it with your own view initialization logic.
class View extends mvc.View {
preinitialize({ autoRender }) {
this.autoRender = autoRender;
}
initialize() {
if (this.autoRender) {
this.listenTo(this.model, 'change', this.render);
}
}
}
remove()​
view.remove(): this;
Removes a view and its el from the DOM, and calls stopListening() to remove any events bound to the view via listenTo().
render()​
view.render(): this;
render() is the core function that your view should override, in order to populate its element (this.el property) with the appropriate HTML. The convention is for render to always return this to enable chained calls.
setElement()​
view.setElement(element: $Element): this;
Change the view's element (this.el property) and re-delegate the view's events on the new element.
undelegateEvents()​
view.undelegateEvents(): this;
Removes all of the view's delegated events. Useful if you want to disable or remove a view from the DOM temporarily.
A single-event version of undelegateEvents() is available as undelegate().
Static methods​
extend()​
mvc.View.extend(properties: any, classProperties?: any): any;
Create a custom view class. You will want to override the render() function, specify your declarative events, and perhaps the tagName, className, or id of the View's root element.
const ShapeRow = mvc.View.extend({
tagName: 'li',
className: 'shape-row',
events: {
'click .icon': 'open',
'click .button.edit': 'openEditDialog'
},
initialize: function() {
this.listenTo(this.model, 'change', this.render);
},
render: function() {
// ...
},
// define event handlers:
open: function() {
// ...
},
openEditDialog: function() {
// ...
}
});
Properties like tagName, id, className, el, and events may also be defined as a function, if you want to wait to define them until runtime.