C class

Application

The Application class serves as the main entry point for a Viking.js application. It handles routing, layout management, and content display.

Constructor

new Application(options)
options : Object

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

Default event bindings for the application

P   helpers: Object | function | undefined

Define properties to be included when calling layout or display a template

P   id: string | function

The ID attribute to set on the view's element

P   layout: function

Define a layout function to wrap the view content, is called everytime layout changes

Parameters

locals : Object

Properties of the view with a property called "content" assigned as the displayed template

Returns

Elements | Boolean

Elements to append, return false to not render layout

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

P   title: string

The default title for the application

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   display(template, locals, options) → null

Display content

Parameters

template : function

Function returning element(s), receives merger of locals and helpers as arugment

locals : Object

Properties passed to template

options : DisplayOptions

Options for display

Returns

null

Examples

this.display(userShow, {user: user}, {layout: false})
F   initialize()

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

F   navigateTo(path)

Navigates to the specified path using the application's router

Parameters

path : string

The path to navigate to

F   pushState(e)

Event handler for link clicks that uses pushState for navigation when possible Allows the application to handle internal navigation without page reloads

Parameters

e : Event

The click event

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()

Sets up the application by initializing the router and running initializers Called automatically during construction

F   start() → Application

Starts the application and its router if one exists

Returns

Application

Returns the application instance for chaining

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