BFF

Module: bff/view

Encapsulates typical MVC view functionality. Note that BFF lacks a separate controller module and it is not wrong put controller logic in BFF Views.

The intended way to combine BFF Records/Lists and Views into some kind or MVC-like pattern is as follows:

  • Views listen to DOM events, and reacts to those by mutating data layer entities (such as models or lists of models)
  • Views also listen to data layer events and reacts to those, possibly by further mutating the data layer (i.e. controller logic), but most importantly by re-rendering themselves.

Another way of describing the above is that the views should, besides listening to user generated events, always strive to visually represent the data layer as truthfully as possible. A powerful and simple approach to achieving this is to re-render the whole view whenever the data layer changes.

The three major issues to deal with when re-rendering an entire view are:

  • Loss of view state. This is a generic problem, that thankfully has an easy solution; store all application state in the data layer. A typical way of doing this is to assign a view state model to views that are not stateless.
  • Loss of event listeners. The typical solution to this is event delegation, which is also the soliution that BFF Views provide. All event listeners are registered on the view's root element and as long as the root elements is not replaced, the event listeners will be unaffecte by a re-render.
  • Visual flickering. Replacing large chunks of the visual DOM may cause flickering. BFF Views work around this issue by using an approach similar to that of React, namely by differentially updating the DOM. This means doing an offline diff and then only updating the parts of the DOM that have actually changed.

new (require("bff/view"))()

Creates a new View instance.

Mixes In:
  • module:bff/event-emitter
  • module:bff/event-listener
Source:

Members

children :module:bff/list

A list of this view's child views. Initially empty.

Type:
Source:

el :HTMLElement|undefined

The root DOM element of the view. The default implementation of module:bff/view#render assigns to and updates this element. Delegated event listeners, created by calling module:bff/view#listenTo are attached to this element.
Replacing the current element with another will clear all currently delegated event listeners - it is usually a better approach update the element (using e.g. module:bff/patch-dom) instead of replacing it.

Type:
  • HTMLElement | undefined
Source:

Methods

<static> makeSubclass(properties)

Creates a subclass constructor function, that will create view instances with the properties (typically functions) provded to this function.

Parameters:
Name Type Description
properties Object

The properties with which the View subclass' prototype will be extended.
Source:
Returns:
Type
function

$(queryString)

Scoped query selector, that only queries this view's DOM subtree.

Parameters:
Name Type Description
queryString string

CSS selector string
Source:

addChild(childView [, optional])

Adds another view as a child to the view. A child view will be automatically added to this view's root element and destroyed whenever its parent view is destroyed.

Parameters:
Name Type Argument Description
childView module:bff/view

The view that will be added to the list of this view's children.
optional HTMLElement | boolean <optional>

An element to which the child view's root element will be appended. If not specified, it will be appended to this view's root element. Can also be false, in which case the child view will not be appended to anything.
Source:

destroy()

Destroys a view instance by removing its children, stop listening to all events and finally removing itself from the DOM.

Source:

destroyChildren()

Destroy all child views of this view.

Source:

forceRepaint( [el])

Helper function that forces the view's root element to be repainted. Useful when re-triggering CSS animations.

Parameters:
Name Type Argument Description
el HTMLElement <optional>

Element that will be forced to repaint. If not specified, will default to the view's root element.
Source:
Returns:

Useless/arbitrary value, but the function needs to return it to prevent browser JS optimizations from interfering with the forced repaint.

Type
number

getHtml()

Returns an HTML string representation of the view in its current state. Its is used by the default implementation of render(), where its return value is parsed and becomes the view's DOM representation.

Source:

listenTo(selectorStr, eventName, callback [, context])

Augments bff/event-listener#listenTo with functionality for listening to delegated DOM events, by specifying a CSS selector string instead of an event emitter. The actual listener will implicitly be registered on this view's root element. Not the the "mouseenter" and "mouseleave" events does not bubble, so they might not behave as expected - "mouseover" and "mouseout" events on the other hand do bubble.

Parameters:
Name Type Argument Description
selectorStr string | Object | Array | NodeList

The CSS selector string that will be used to filter all events bubbling up to the listener. If anything other than a string passed, the original listenTo implementation will be used.
eventName string | Array

One or more string identifiers for events that will be listented to.
callback function

The function that will be called when the event is emitted.
context any <optional>

The context with which the callback will be called (i.e. what "this" will be).
Will default to the caller of .listenTo, if not provided.
Source:

parseHtml(htmlString, returnAll)

Helper function that parses an HTML string into an HTMLElement hierarchy and returns the first element in the NodeList, unless the returnAll flag is true, in which case the whole node list is returned.

Parameters:
Name Type Description
htmlString string

The string to be parsed
returnAll boolean

If true will return all top level elements
Source:

render( [patchOptions])

Creates a DOM element representation of the view, based on the HTML string returned by the getHtml() function and then assigns it to the view's el property. If the view already has an el, it will be patched instead of replaced, so that delegated event listeners will be preserved.

Parameters:
Name Type Argument Description
patchOptions Object <optional>

Options object forwarded to the patch() function, in case it is called.
Source:

requestRender()

Requests an animation frame, in which render() is called. Can be called several times during a tick witout any performance penalty.

Source:

stopListening( [selectorStr] [, eventName])

Augments bff/event-listener#stopListening with functionality for stop listening to delegated DOM events.

Parameters:
Name Type Argument Description
selectorStr string | Object <optional>

If provided, only delegated event callbacks for the given selector string will be removed. The special wildcard value * means any selector. If anything other than a string passed, the original stopListening implementation will be used.
eventName string <optional>

If provided, only callbacks attached to the given event name will be removed.
Source:

toString()

Source:
Returns:

A human readable representation of the View, containing valuable debugging information.

Type
string