C class

View

The View class provides a structure for organizing DOM elements and their events.

Views in Viking are similar to traditional MVC views - they represent a logical part of the user interface. A View manages a DOM element (this.el) and any events that occur within it. Views can be nested using the subView system.

Viking Views are designed to be declarative - you define your DOM events in an events hash, and the View handles binding those to the appropriate handlers. This makes it easy to organize code related to a specific part of the UI.

Constructor

new View(options)
options : Object optional

Options for the view

el : Element | string optional

The element for the view

id : string optional

The ID to set on the view's element

className : string optional

The CSS class name for the view's element

attributes : Object optional

HTML attributes to set on the view's element

tagName : string optional

The HTML tag name for the view's element

events : Object optional

Event handlers to bind to the view's element

record : Object optional

The record associated with this view

Examples

class UserView extends View {
  static events = {
    'click .edit-button': 'editUser',
    'submit form': 'saveUser'
  };
  
  initialize() {
    // Setup code runs when the view is created
    this.render();
  }
  
  render() {
    this.el.innerHTML = `
      <h2>${this.record.name}</h2>
      <button class="edit-button">Edit</button>
      <form style="display: none;">
        <input name="name" value="${this.record.name}">
        <button type="submit">Save</button>
      </form>
    `;
    return this;
  }
  
  editUser() {
    this.$('form').style.display = 'block';
  }
  
  saveUser(e) {
    e.preventDefault();
    this.record.name = this.$('input[name="name"]').value;
    this.render();
  }
}

Instance Properties

P   _domEvents: Array.<Object>

Internal storage for DOM event listeners

P   assignableProperties: Array.<string>

Properties from the options object that will be assigned directly to the view instance

P   attributes: Object

HTML attributes to set on the view's element

P   bindedObjects: Object.<string, Object>

Object containing references to objects this instance is listening to

P   className: string | function

The CSS class name(s) to set on the view's element

P   defaults: Object

Default property values for the view

P   el: Element | string | function

The DOM element for the view, can be a CSS selector, HTML element, or function returning either

P   eventListeners: Object.<string, Array>

Object containing all event listeners

P   events: Object

Event map defining DOM events and their handlers Format: {'event selector': 'handlerMethod'}

P   id: string | function

The ID attribute to set on the view's element

P   listenerId: string

Unique identifier for this event bus instance

P   staticAttributeAccessors: Array.<string>

Properties that should be copied from the static class to the instance

P   subViews: Array.<View>

An array for storing subViews attached to this view

P   tagName: string

The HTML tag name to use when creating the view's element

P   template: string | function

Template for the view

Instance Methods

F   _removeElement()

Removes the view's element from the DOM

F   $(selector) → Element | null

Finds an element within the view's element using a CSS selector

Parameters

selector : string

CSS selector to search for

Returns

Element | null

The first matching element or null if not found

F   addEventListener(name, callback, options) → EventBus

Bind an event to a callback function. Passing "*" will bind the callback to all events fired.

If the options.once is true, the event will only be triggered a single time. After the first time the callback is invoked, its listener will be removed. If multiple events are passed in as an array, the handler will fire once for each event, not once for a combination of all events.

Parameters

name : string | Array.<string> | object

Event name(s) or object of event/callback pairs

callback : function | object

Callback function or options object if name is an object

options : object optional

Event options

once : boolean optional

Whether the event should only trigger once

context : object optional

The context to bind the event to

listener : object optional

The listener object

Returns

EventBus

Returns this for chaining

F   addEventListenerFor(obj, name, callback, options) → EventBus

Tell this object to listen to an event in another object, while keeping track of what it's listening to for easier unbinding later.

Parameters

obj : object | NodeList

The object to listen to events on

name : string | Array.<string> | object

Event name(s) or object of event/callback pairs

callback : function | object

Callback function or options object if name is an object

options : object optional

Event options

once : boolean optional

Whether the event should only trigger once

context : object optional

The context to bind the event to

Returns

EventBus

Returns this for chaining

F   delegateEvents(events) → View

Set up event delegation for the view

This method binds event handlers defined in the events hash to the view's element. The events hash format is: {'event selector': handler}

Callbacks will be bound to the view with this set properly. Omitting the selector binds the event to the view's element itself.

Parameters

events : Object optional

Event map to use instead of the view's events property

Returns

View

The view instance for chaining

Examples

{
  'mousedown .title': 'edit',
  'click .button': 'save',
  'click .open': function(e) { ... },
  'click .title': ['edit', false],
  'click .title': ['edit', {passive: true}]
}
F   dispatchEvent(name, args) → EventBus

Trigger one or many events, firing all bound callbacks. Callbacks are passed the same arguments as dispatchEvent is, apart from the event name (unless you're listening on "*", which will cause your callback to receive the true name of the event as the first argument).

Parameters

name : string | Array.<string>

Event name or array of event names

args : *

Arguments to pass to the event handlers

Returns

EventBus

Returns this for chaining

F   initialize()

Called after the DOM element is created Override this method to perform initialization after the view's element is set up

F   remove() → View

Removes this view and all subviews from the DOM

This method removes the view's element from the DOM, cleans up any event listeners, and recursively removes all subviews.

Returns

View

The view instance for chaining

F   removeEventListener(name, callback, options) → EventBus

Remove one or many callbacks that match the arguments. If called with no arguments, removes all callbacks for all events.

Parameters

name : string | Array.<string> | object | null optional

Event name(s) or object of event/callback pairs

callback : function | object | null optional

Callback function or options object if name is an object

options : object optional

Event options

once : boolean optional

Match only events set to trigger once

context : object optional

Match only events bound to this context

listener : object optional

Match only events bound by this listener

Returns

EventBus

Returns this for chaining

F   removeEventListenerFor(obj, name, callback, options) → EventBus

Tell this object to stop listening to either specific events or to every object it's currently listening to.

Parameters

obj : object | NodeList optional

The object to stop listening to; if omitted, stops listening to all objects

name : string | Array.<string> | object optional

Event name(s) or object of event/callback pairs

callback : function optional

Callback function to remove

options : object optional

Event options

once : boolean optional

Match only events set to trigger once

context : object optional

Match only events bound to this context

Returns

EventBus

Returns this for chaining

F   removeSubView(view)

Removes a subview from this view

This method removes the subview by calling its remove method, which will ultimately trigger the afterRemove event, causing it to be removed from the subViews array.

Parameters

view : View

The subview to remove

F   render() → View

Renders the view's content

This is the core function that your view should override to populate its element with the appropriate HTML. The convention is for render to always return this to enable method chaining.

Returns

View

The view instance for chaining

F   setElement(element) → Element

Change the view's element and re-delegate events

This method changes the view's element (this.el property) and re-delegates the view's events on the new element.

Parameters

element : Element | NodeList | string

The new element, can be a CSS selector, Element node, or NodeList (the first item will be used)

Returns

Element

The new element

F   setup()

Called before the DOM element is created Override this method to perform initialization before the view's element is set up

F   subView(SubView, args) → View

Creates a subview and adds it to this view's subviews array

Parameters

SubView : Class

The view class to instantiate

args : *

Arguments to pass to the subview constructor

Returns

View

The created subview instance

F   subViewRemoved(view)

Handler for a subview's afterRemove event

Parameters

view : View

The removed subview

F   undelegateEvents() → View

Remove all event listeners from the view's element

This method clears all callbacks previously bound to the view by delegateEvents. It's automatically called when changing elements or removing the view.

Returns

View

The view instance for chaining

Static Methods

F   getEvents() → Object

Get the events hash for this view, merging with parent class events

Returns

Object

The merged events hash