FormView

FormView

new FormView(args)

Source:
Author:
  • ariel.wexler@vecna.com
See:

Generic Form View

Parameters:
Name Type Description
args Object

options argument

Properties
Name Type Attributes Default Description
model FormModel <optional>
 new this.FormModelClass()

a form model for binding that defaults to class-level
model or instantiates a FormModelClass
FormModelClass function <optional>
 FormModel

the class (that extends FormModel) that will be used as the FormModel. Defaults to a class-level
definition or FormModel if none is provided
template external:Handlebars-Template <optional>

overrides the template used by this view
events Object <optional>

events hash: merge + override the events hash used by this view
fields Object <optional>

field hash: merge + override automated two-way binding field hash used by this view
bindings Object <optional>

binding hash: merge + override custom epoxy binding hash used by this view

Extends

Members

bindings :Object

Source:

Stickit bindings hash

Type:
  • Object

events :Object

Source:

Backbone events hash

Type:
  • Object

fields :Object

Source:

Two-way binding field customization

Type:
  • Object

FormModelClass :FormModel.prototype

Source:

The class to be used when instantiating the form model

Type:
  • FormModel.prototype

template :external:Handlebars-Template

Source:

Handlebars template for form

Type:

viewState :ViewStateCell

Source:
Inherited From:

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

Type:

Methods

_activate()

Source:
Inherited From:

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:
Inherited From:

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:
Inherited From:

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:
Inherited From:

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:
Inherited From:

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:
Inherited From:

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:
Inherited From:

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

attachTo($elopt, optionsopt) → {Promise}

Source:
Inherited From:

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:
Inherited From:

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:
Inherited From:

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:
Overrides:

Deactivate callback that removes bindings and other resources
that shouldn't exist in a dactivated state

delegateEvents()

Source:
Overrides:

Override the delegate events and wrap our custom additions

detach()

Source:
Inherited From:

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:
Inherited From:

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:
Inherited From:

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:
Inherited From:

Alias to this.viewState.get()

getBehavior(alias) → {Torso.Behavior}

Source:
Inherited From:
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:
Inherited From:
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:
Inherited From:

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:
Inherited From:

Alias to this.viewState.has()

hasTrackedViews(optionsopt) → {boolean}

Source:
Inherited From:
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

invalid()

Source:

Default method called on validation failure.

invokeFeedback(to, evtopt, indexMapopt)

Source:
Inherited From:

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:
Inherited From:
Returns:

true if the view is active

Type
boolean

isAttached() → {boolean}

Source:
Inherited From:

NOTE: depends on a global variable "document"

Returns:

true if the view is attached to the DOM

Type
boolean

isAttachedToParent() → {boolean}

Source:
Inherited From:
Returns:

true if the view is attached to a parent

Type
boolean

isDisposed() → {boolean}

Source:
Inherited From:
Returns:

true if the view was disposed

Type
boolean

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

Source:
Inherited From:

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:
Overrides:

Prepare the formview's default render context

Returns:

{Object.errors} A hash of field names mapped to error messages
{Object.success} A boolean value of true if validation has succeeded

Type
Object

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

Source:
Inherited From:

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:
Inherited From:

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:
Inherited From:

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

resetModelListeners(model, stopListeningopt)

Source:

Resets the form model with the passed in model. Stops listening to current form model
and sets up listeners on the new one.

Parameters:
Name Type Attributes Default Description
model Torso.FormModel

the new form model
stopListening boolean <optional>
 false

if true, it will stop listening to the previous form model

set()

Source:
Inherited From:

Alias to this.viewState.set()

templateRender()

Source:
Inherited From:

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

toJSON()

Source:
Inherited From:

Alias to this.viewState.toJSON()

transitionIn(attach, done, options)

Source:
Inherited From:

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:
Inherited From:

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:
Inherited From:

Overrides undelegateEvents
Unbinds DOM events from the view.

unregisterTrackedView(view) → {View}

Source:
Inherited From:

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:
Inherited From:

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:
Inherited From:

Alias to this.viewState.unset()

updateClassName(newClassName)

Source:
Inherited From:

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:
Inherited From:

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.

valid()

Source:

Default method called on validation success.