View

View

View

Constructor

new View()

Source:
Author:
  • ariel.wexler@vecna.com, kent.willis@vecna.com
See:

Overrides constructor to create needed fields and invoke activate/render after initialization

Generic View that deals with:

  • Creation of private collections
  • Lifecycle of a view

Extends

Members

viewState :ViewStateCell

Source:

Cell that can be used to save state for rendering the view.

Type:

Methods

_activate()

Source:

Method to be invoked when activate is called. Use this method to turn on any
custom timers, listenTo's or on's that should be activatable. The default implementation is a no-op.

_attached()

Source:

Method to be invoked when the view is fully attached to the DOM (NOT just the parent). Use this method to manipulate the view
after the DOM has been attached to the document. The default implementation is a no-op.

_deactivate()

Source:

Method to be invoked when deactivate is called. Use this method to turn off any
custom timers, listenTo's or on's that should be deactivatable. The default implementation is a no-op.

_detached()

Source:

Method to be invoked when the view is detached from the DOM (NOT just the parent). Use this method to clean up state
after the view has been removed from the document. The default implementation is a no-op.

_dispose()

Source:

Method to be invoked when dispose is called. By default calling dispose will remove the
view's element, its on's, listenTo's, and any registered children.
Override this method to destruct any extra

_prepare(context) → {Object}

Source:

Extension point to augment the template context with custom content.

Parameters:
Name Type Description
context

the context you can modify
Returns:

[Optional] If you return an object, it will be merged with the context

Type
Object

activate()

Source:

Resets listeners and events in order for the view to be reattached to the visible DOM

attachTo($elopt, optionsopt) → {Promise}

Source:

If detached, will replace the element passed in with this view's element and activate the view.

Parameters:
Name Type Attributes Description
$el external:jQuery <optional>

the element to attach to. This element will be replaced with this view.
If options.replaceMethod is provided, then this parameter is ignored.
options Object <optional>

optional options

Properties
Name Type Attributes Default Description
replaceMethod Fucntion <optional>

if given, this view will invoke replaceMethod function
in order to attach the view's DOM to the parent instead of calling $el.replaceWith
discardInjectionSite Booleon <optional>
 false

if set to true, the injection site is not saved.
Returns:

promise that when resolved, the attach process is complete. Normally this method is synchronous. Transition effects can
make it asynchronous.

Type
Promise

attachTrackedViews() → {Promise|Array.<Promise>}

Source:

Hook to attach all your tracked views. This hook will be called after all DOM rendering is done so injection sites should be available.
This method can be overwritten as usual OR extended using .prototype.attachTrackedViews.apply(this, arguments);

Returns:

you can optionally return one or more promises that when all are resolved, all tracked views are attached. Useful when using this.attachView with useTransition=true.

Type
Promise | Array.<Promise>

attachView($el, view, optionsopt) → {Promise}

Source:

Registers the view as a tracked view (defaulting as a child view), then calls view.attachTo with the element argument
The element argument can be a String that references an element with the corresponding "inject" attribute.
When using attachView with options.useTransition:
Will inject a new view into an injection site by using the new view's transitionIn method. If the parent view
previously had another view at this injections site, this previous view will be removed with that view's transitionOut.
If this method is used within a render, the current views' injection sites will be cached so they can be transitioned out even
though they are detached in the process of re-rendering. If no previous view is given and none can be found, the new view is transitioned in regardless.
If the previous view is the same as the new view, it is injected normally without transitioning in.
The previous view must has used an injection site with the standard "inject=" attribute to be found.
When the transitionIn and transitionOut methods are invoked on the new and previous views, the options parameter will be passed on to them. Other fields
will be added to the options parameter to allow better handling of the transitions. These include:
{
newView: the new view
previousView: the previous view (can be undefined)
parentView: the parent view transitioning in or out the tracked view
}

Parameters:
Name Type Attributes Description
$el external:jQuery | string

the element to attach to OR the name of the injection site. The element with the attribute "inject=" will be used.
view View

The instantiated view object to be attached
options Object <optional>

optionals options object. If using transitions, this options object will be passed on to the transitionIn and transitionOut methods as well.

Properties
Name Type Attributes Default Description
noActivate boolean <optional>
 false

if set to true, the view will not be activated upon attaching.
shared boolean <optional>
 false

if set to true, the view will be treated as a shared view and not disposed during parent view disposing.
useTransition boolean <optional>
 false

if set to true, this method will delegate attach logic to this.__transitionNewViewIntoSite
addBefore boolean <optional>
 false

if true, and options.useTransition is true, the new view's element will be added before the previous view's element. Defaults to after.
previousView View <optional>

if using options.useTransition, then you can explicitly define the view that should be transitioned out.
If using transitions and no previousView is provided, it will look to see if a view already is at this injection site and uses that by default.
Returns:

resolved when all transitions are complete. No payload is provided upon resolution. If no transitions, then returns a resolved promise.

Type
Promise

deactivate()

Source:

Maintains view state and DOM but prevents view from becoming a zombie by removing listeners
and events that may affect user experience. Recursively invokes deactivate on child views

delegateEvents()

Source:

Overrides the base delegateEvents
Binds DOM events with the view using events hash while also adding feedback event bindings

detach()

Source:

If attached, will detach the view from the DOM.
This method will only separate this view from the DOM it was attached to, but it WILL invoke the _detach
callback on each tracked view recursively.

detachTrackedViews(optionsopt)

Source:

Detach all tracked views or a subset of them based on the options parameter.
NOTE: this is not recursive - it will not separate the entire view tree.

Parameters:
Name Type Attributes Default Description
options Object <optional>
 {}

Optional options.

Properties
Name Type Attributes Default Description
shared boolean <optional>
 false

If true, detach only the shared views. These are views not owned by this parent. As compared to a child view
which are disposed when the parent is disposed.
child boolean <optional>
 false

If true, detach only child views. These are views that are owned by the parent and dispose of them if the parent is disposed.

dispose()

Source:

Removes all listeners, disposes children views, stops listening to events, removes DOM.
After dispose is called, the view can be safely garbage collected. Called while
recursively removing views from the hierarchy.

get()

Source:

Alias to this.viewState.get()

getBehavior(alias) → {Torso.Behavior}

Source:
Parameters:
Name Type Description
alias string

the name/alias of the behavior
Returns:

the behavior instance if one exists with that alias

Type
Torso.Behavior

getTrackedView(viewCID)

Source:
Parameters:
Name Type Description
viewCID string

the cid of the view
Returns:

the view with the given cid. Will look in both shared and child views.

getTrackedViews(optionsopt) → {List.<View>}

Source:

Returns all tracked views, both child views and shared views.

Parameters:
Name Type Attributes Default Description
options Object <optional>
 {}

Optional options.

Properties
Name Type Attributes Default Description
shared boolean <optional>
 false

If true, get only the shared views. These are views not owned by this parent. As compared to a child view
which are disposed when the parent is disposed.
child boolean <optional>
 false

If true, get only child views. These are views that are owned by the parent and dispose of them if the parent is disposed.
Returns:

all tracked views (filtered by options parameter)

Type
List.<View>

has()

Source:

Alias to this.viewState.has()

hasTrackedViews(optionsopt) → {boolean}

Source:
Parameters:
Name Type Attributes Default Description
options Object <optional>
 {}

Optional options.

Properties
Name Type Attributes Default Description
shared boolean <optional>
 false

If true, only check the shared views. These are views not owned by this parent. As compared to a child view
which are disposed when the parent is disposed.
child boolean <optional>
 false

If true, only check the child views. These are views that are owned by the parent and dispose of them if the parent is disposed.
Returns:

true if this view has tracked views (limited by the options parameter)

Type
boolean

invokeFeedback(to, evtopt, indexMapopt)

Source:

Invokes a feedback entry's "then" method

Parameters:
Name Type Attributes Description
to string

the "to" field corresponding to the feedback entry to be invoked.
evt Event <optional>

the event to be passed to the "then" method
indexMap Object <optional>

a map from index variable name to index value. Needed for "to" fields with array notation.

isActive() → {boolean}

Source:
Returns:

true if the view is active

Type
boolean

isAttached() → {boolean}

Source:

NOTE: depends on a global variable "document"

Returns:

true if the view is attached to the DOM

Type
boolean

isAttachedToParent() → {boolean}

Source:
Returns:

true if the view is attached to a parent

Type
boolean

isDisposed() → {boolean}

Source:
Returns:

true if the view was disposed

Type
boolean

postrender() → {Promise|Array.<Promise>}

Source:

Hook during render that is invoked after all DOM rendering is done and tracked views attached.
This method can be overwritten as usual OR extended using .prototype.postrender.apply(this, arguments);
NOTE: if you require the view to be attached to the DOM, consider using _attach callback

Returns:

you can optionally return one or more promises that when all are resolved, postrender is finished. Note: render logic will not wait until promises are resolved.

Type
Promise | Array.<Promise>

prepare() → {Object}

Source:

prepareFields can be used to augment the default render method contents.
See __getPrepareFieldsContext() for more details on how to configure them.

Returns:

context for a render method. Defaults to:
{view: this.viewState.toJSON(), model: this.model.toJSON()}

Type
Object

prerender() → {Promise|Array.<Promise>}

Source:

Hook during render that is invoked before any DOM rendering is performed.
This method can be overwritten as usual OR extended using .prototype.prerender.apply(this, arguments);
NOTE: if you require the view to be detached from the DOM, consider using _detach callback

Returns:

you can optionally return one or more promises that when all are resolved, prerender is finished. Note: render logic will not wait until promises are resolved.

Type
Promise | Array.<Promise>

registerTrackedView(view, optionsopt) → {View}

Source:

Binds the view as a tracked view - any recursive calls like activate, deactivate, or dispose will
be done to the tracked view as well. Except dispose for shared views. This method defaults to register the
view as a child view unless specified by options.shared.

Parameters:
Name Type Attributes Default Description
view View

the tracked view
options Object <optional>
 {}

Optional options.

Properties
Name Type Attributes Default Description
shared boolean <optional>
 false

If true, registers view as a shared view. These are views not owned by this parent. As compared to a child view
which are disposed when the parent is disposed. If false, registers view as a child view which are disposed when the parent is disposed.
Returns:

the tracked view

Type
View

render() → {Promise}

Source:

Rebuilds the html for this view's element. Should be able to be called at any time.
Defaults to using this.templateRender. Assumes that this.template is a javascript
function that accepted a single JSON context.
The render method returns a promise that resolves when rendering is complete. Typically render
is synchronous and the rendering is complete upon completion of the method. However, when utilizing
transitions/animations, the render process can be asynchronous and the promise is useful to know when it has finished.

Returns:

a promise that when resolved signifies that the rendering process is complete.

Type
Promise

set()

Source:

Alias to this.viewState.set()

templateRender()

Source:

Hotswap rendering system reroute method.
See Torso.templateRenderer#render for params

toJSON()

Source:

Alias to this.viewState.toJSON()

transitionIn(attach, done, options)

Source:

Override to provide your own transition in logic. Default logic is to just attach to the page.
The method is passed a callback that should be invoked when the transition in has fully completed.

Parameters:
Name Type Description
attach function

callback to be invoked when you want this view to be attached to the dom.
If you are trying to transition in a tracked view, consider using this.transitionInView()
done function

callback that MUST be invoked when the transition is complete.
options

optionals options object

Properties
Name Type Description
currentView View

the view that is being transitioned in.
previousView View

the view that is being transitioned out. Typically this view.
parentView View

the view that is invoking the transition.

transitionOut(done, options)

Source:

Override to provide your own transition out logic. Default logic is to just detach from the page.
The method is passed a callback that should be invoked when the transition out has fully completed.

Parameters:
Name Type Description
done function

callback that MUST be invoked when the transition is complete.
options

optionals options object

Properties
Name Type Description
currentView View

the view that is being transitioned in.
previousView View

the view that is being transitioned out. Typically this view.
parentView View

the view that is invoking the transition.

undelegateEvents()

Source:

Overrides undelegateEvents
Unbinds DOM events from the view.

unregisterTrackedView(view) → {View}

Source:

Unbinds the tracked view - no recursive calls will be made to this shared view

Parameters:
Name Type Description
view View

the shared view
Returns:

the tracked view

Type
View

unregisterTrackedViews(optionsopt) → {View}

Source:

Unbinds all tracked view - no recursive calls will be made to this shared view
You can limit the types of views that will be unregistered by using the options parameter.

Parameters:
Name Type Attributes Default Description
options Object <optional>
 {}

Optional options.

Properties
Name Type Attributes Default Description
shared boolean <optional>
 false

If true, unregister only the shared views. These are views not owned by this parent. As compared to a child view
which are disposed when the parent is disposed.
child boolean <optional>
 false

If true, unregister only child views. These are views that are owned by the parent and dispose of them if the parent is disposed.
Returns:

the tracked view

Type
View

unset()

Source:

Alias to this.viewState.unset()

updateClassName(newClassName)

Source:

Updates this view element's class attribute with the value provided.
If no value provided, removes the class attribute of this view element.

Parameters:
Name Type Description
newClassName string

the new value of the class attribute

updateDOM()

Source:

Produces and sets this view's elements DOM. Used during the rendering process. Override if you have custom DOM update logic.
Defaults to using the stanrdard: this.templateRender(this.$el, this.template, this.prepare(), templateRendererOptions);
this.templateRendererOptions is an object or function defined on the view that is passed into the renderer.
Examples include: views with no template or multiple templates, or if you wish to use a different rendering engine than the templateRenderer or wish to pass options to it.