FormModel

FormModel

new FormModel()

Source:
Mixes In:
Author:
  • kent.willis@vecna.com
See:

Generic Form Model

Extends

Members

mapping :Object

Source:
Properties:
Name Type Description
mapping

Map from aliases (either model names or computed value names) to mappings.
Please refer to the documentation on the constructor about the form and options for this field.

Type:
  • Object

models :Object

Source:
Properties:
Name Type Description
models

Map from model aliases to model instances.
Please refer to the documentation on the constructor about the form and options for this field.

Type:
  • Object

pollTimeoutId

Source:
Inherited From:
Mixes In:
Properties:
Name Type Description
pollTimeoutId number

The id from when setTimeout was called to start polling.

Methods

_dispose()

Source:
Inherited From:
Mixes In:

Dispose hook meant to be used by prototypes that extend this one that need to provide their own dispose logic.

checkIfModelsAreStale() → {Array}

Source:
Returns:

an array of the object models that have been updated since the last pull from this form model

Type
Array

constructor(optionsopt)

Source:

Constructor the form model. Can take in attributes to set initially. These will override any pulled values from object models
on initialization. On initialization the object model's values will be pulled once.
For the options, here are needed definitions:
mapping: {
modelName: 'foo bar baz' // track a model by providing an alias for a name and a space seperated list of fields to track as a String
modelName2: true // to track all fields
... // can have many model mappings
computedName: {
modelName: 'taz raz', // mappings for models that will be used for this computed mapping.
... // can have many model mappings for a computed
pull: function(models) {}, // a callback that will be invoked when pulling data from the Object model. Passes in a map of model alias/name to shallow copies of fields being tracked on that model.
push: function(models) {} // a callback that will be invoked when pushing data to the Object model. Passes in a map of model alias/name to object model being tracked under that alias.
}
},
models: {
modelName: modelInstance, // optionally, provide a set of model instance to model name (aliases) to start tracking
modelName2: modelInstance2 // provide as many aliases to model instances as you'd like
}

Parameters:
Name Type Attributes Description
options Object <optional>
Properties
Name Type Attributes Default Description
mapping Object <optional>

map from aliases (either model names or computed value names) to mappings.
A model mapping can bind an alias to a space seperated list of fields to track as a String r the boolean true if it is mapping all the
fields. A computed mapping can bind an alias to a set of model mappings required for this computed value and both a pull and/or push method
that are used to compute different values to or from object model(s).
models Object <optional>

Because the options.mapping parameter only allows you to define the mappings to aliases, this options allows
you to bind model instances to aliases. Setting model instances to aliases are required to actually begin pulling/pushing values.
startUpdating boolean <optional>
 false

set to true if you want to immediately set up listeners to update this form
model as the object model updates. You can always toggle this state with startUpdating() and stopUpdating().
validation Object <optional>

A Backbone.Validation plugin hash to dictate the validation rules
labels Object <optional>

A Backbone.Validation plugin hash to dictate the attribute labels

dispose()

Source:
Inherited From:
Mixes In:

Default dispose for model-like objects (Models, Cells, and ServiceCells).
Removes listeners and calls out to _dispose() for child specific dispose logic.
Triggers 2 events - "before-dispose" and "after-dispose".

getMapping(alias)

Source:
Parameters:
Name Type Description
alias string

the alias of the mapping - either a model mapping or a computed mapping
Returns:

the mapping config for that alias

getMappings()

Source:
Returns:

all the current mapping configs

getTrackedModel(alias) → {external:Backbone-Model}

Source:

Returns the object model currently bound to the given name/alias.

Parameters:
Name Type Description
alias string

the name/alias used by the mappings.
Returns:

the model currently bound to the alias

Type
external:Backbone-Model

getTrackedModels()

Source:

Returns all the currently tracked object models

Returns:

all the currently tracked object models

isModelStale(model, staleModelsopt, currentHashValuesopt) → {boolean}

Source:
Parameters:
Name Type Attributes Description
model Backbone.Model

the backbone model that is being checked
staleModels Object <optional>

a hash that will be updated to contain this model if it is stale in the form: cid -> model.
currentHashValues Object <optional>

If passed an object, it will look in this cache for the current value of the object model
instead of calculating it. It should be key'ed by the model's cid
Returns:

true if the model passed in has been changed since the last pull from the object model.

Type
boolean

isPolling()

Source:
Inherited From:
Mixes In:

Returns true if the poll is active

isTrackingAnyObjectModel()

Source:
Returns:

true if this form model is backed by an Object model. That means that at least one object model was bound to an mapping alias.

isUpdating()

Source:
Returns:

true if any updates to an object model will immediately copy new values into this form model.

isValid()

Source:
Mixes In:

Check to see if an attribute, an array of attributes or the
entire model is valid. Passing true will force a validation
of the model.

polledFetch()

Source:
Inherited From:
Mixes In:

By default, the polled fetching operation is routed directly
to backbone's fetch all.

preValidate(attr, valueopt) → {undefined|string|Object}

Source:
Mixes In:

Check whether an attribute or a set of attributes are valid. It will default to use the model's current values but
you can pass in different values to use in the validation process instead.

Parameters:
Name Type Attributes Description
attr string | Object | Array.<string>

Either the name of the attribute, an array containing many attribute names, or
on object with attribute name to values
value Any <optional>

a value to use for the attribute value instead of using the model's value.
Returns:

undefined if no errors, a validation exception if a single attribute, or an object with attribute name as key
and the error as the value

Type
undefined | string | Object

pull()

Source:

Pulls the most recent values of every object model that this form model tracks including computed values
NOTE: using this method can override user-submitted data from an HTML form. Use caution.

push()

Source:

Pushes values from this form model back to the object models it is tracking. This includes invoking the push callbacks from
computed values

resetUpdating()

Source:

If updating, it will reset the updating events to match the current mappings.

save(optionsopt)

Source:

If FormModel has a "url" property defined, it will invoke a save on the form model, and after successfully
saving, will perform a push.
If no "url" property is defined then the following behavior is used:
Pushes the form model values to the object models it is tracking and invokes save on each one. Returns a promise.
NOTE: if no url is specified and no models are being tracked, it will instead trigger a 'save-fail' event and reject the returned promise
with a payload that mimics a server response: {none: { success: false, response: [{ responseJSON: { generalReasons: [{messageKey: 'no.models.were.bound.to.form'}] }}] }}

Parameters:
Name Type Attributes Description
options Object <optional>
Properties
Name Type Attributes Default Description
rollback boolean <optional>
 true

if true, when any object model fails to save, it will revert the object
model attributes to the state they were before calling save. NOTE: if there are updates that happen
to object models within the timing of this save method, the updates could be lost.
force boolean <optional>
 true

if false, the form model will check to see if an update has been made
to any object models it is tracking since it's last pull. If any stale data is found, save with throw an exception
with attributes: {name: 'Stale data', staleModels: [Array of model cid's]}
Returns:

when using a "url", a promise is returned for the save on this form model.
If not using a "url", a promise that will either resolve when all the models have successfully saved in which case the context returned
is an array of the responses (order determined by first the array of models and then the array of models used by
the computed values, normalized), or if any of the saves fail, the promise will be rejected with an array of responses.
Note: the size of the failure array will always be one - the first model that failed. This is a side-effect of $.when

setMapping(alias, mapping, modelsopt, copyopt)

Source:

Define or redefine how the form model pull/pushes or otherwise tracks properties between an object model(s).
Examples:
this.setMapping('modelAlias', true, optional model instance);
this.setMapping('modelAlias, 'foo bar baz', optional model instance);
this.setMapping('computedAlias', {
model1: 'foo',
model2: 'bar',
push: function(models) {
models.model1.set('foo', this.get('foobar')[0]);
models.model2.set('bar', this.get('foobar')[1]);
},
pull: function(models) {
this.set('foobar', [models.model1.foo, models.model2.bar]);
},
}, optional model map)

Parameters:
Name Type Attributes Default Description
alias string

the name for the mapping - either a model mapping or a computed mapping
mapping string | boolean | Object

Provides the mapping for this alias. If trying to map to a model, then either provide
a space delimited list of fields to track as a String or the boolean true to track all the model's fields. If the mapping is for
a computed value, then provide a map from model alias to model mapping for all the fields needed for the computed and a pull method
if you want to change/combine/split object model properties before bringing them into the form model and a push method if you want to
change/combine/split form model properties before pushing them to the object models.
models Object | external:Backbone-Model <optional>

Provides instances to use for this mapping. If mapping is a computed,
provide a map from alias to model instance. If mapping is for a single model, just provide the model instance for that alias.
copy <optional>
 false

if true, will pull values definined by this mapping after setting the mapping. Requires models to be passed in.

setMappings(mappings, modelsopt, copyopt)

Source:

Sets multiple mappings (both model mappings and computed value mappings) with one call.
Uses the same style of mapping syntax as the constructor. Please refer to the documentation on the constructor.
Here is an example:
this.setMappings({
model1: 'foo bar',
model2: 'baz',
ssn: {
model1: 'ssn',
model2: 'lastssn'
push: function(models) {},
pull: function(models) {},
}
}, optional model map)

Parameters:
Name Type Attributes Default Description
mappings Object

Uses the same style of mapping syntax as the constructor. Please refer to the documentation on the constructor.
models Object <optional>

this parameter allows you to immediately bind model instances to aliases. Keys are aliases and values are external:Backbone-Models.
copy <optional>
 false

if true, will pull values definined by this mapping after setting the mapping. Requires models to be passed in.

setTrackedModel()

Source:
Deprecated:
  • Yes
See:

Use FormModel#trackModel instead.

setTrackedModels()

Source:
Deprecated:
  • Yes
See:

Use FormModel#trackModels instead.

startPolling(pollInterval)

Source:
Inherited From:
Mixes In:

Starts polling Model/Collection by calling fetch every pollInterval.
Note: Each Model/Collection will only allow a singleton of polling to occur so
as not to have duplicate threads updating Model/Collection.

Parameters:
Name Type Description
pollInterval Integer

interval between each poll in ms.

startUpdating(pullFirstopt)

Source:

Will add listeners that will automatically pull new updates from this form's object models.

Parameters:
Name Type Attributes Default Description
pullFirst boolean <optional>
 false

if true, the form model will pull most recent values then start listening

stopPolling()

Source:
Inherited From:
Mixes In:

Stops polling Model and clears all Timeouts.

stopUpdating()

Source:

This will stop the form model from listening to its object models.

trackModel(alias, model, copyopt)

Source:

Update or create a binding between an object model and an alias.

Parameters:
Name Type Attributes Default Description
alias string

the alias/name to bind to.
model external:Backbone-Model

the model to be bound. Mappings referencing this alias will start applying to this model.
copy boolean <optional>
 false

if true, the form model will perform a pull on any mappings using this alias.

trackModels(models, copyopt)

Source:

Binds multiple models to their aliases.

Parameters:
Name Type Attributes Default Description
models Object.<string, external:Backbone-Model>

A map from alias/name to model to be bound to that alias.
copy boolean <optional>
 false

if true, the form model will perform a pull on any mapping using these models.

unsetMapping(aliasOrModel, removeModelIfUntrackedopt)

Source:

Remove a mapping (model or computed) by alias

Parameters:
Name Type Attributes Default Description
aliasOrModel string | external:Backbone-Model

if a String is provided, it will unset the mapping with that alias.
If a external:Backbone-Model is provided, it will remove the model mapping that was bound to that model.
removeModelIfUntracked boolean <optional>
 false

If true, after the mapping is removed, the model will also be unset but only if
no other mappings reference it. Note, setting this to true will not remove any computed mappings that also use that model.

unsetMappings()

Source:

Removes all current mappings
Does NOT remove current model being tracked. Call this.untrackModels afterwards if you wish this behavior.

unsetTrackedModel()

Source:
Deprecated:
  • Yes
See:

Use FormModel#untrackModel instead.

unsetTrackedModels()

Source:
Deprecated:
  • Yes
See:

Use FormModel#untrackModels instead.

untrackModel(aliasOrModel)

Source:

Removes the binding between a model alias and a model instance. Effectively stops tracking that model.

Parameters:
Name Type Description
aliasOrModel string | external:Backbone-Model

If a string is given, it will unset the model using that alias. If a model instance
is given, it will unbind whatever alias is currently bound to it.

untrackModels()

Source:

Removes all the bindings between model aliases and model instances. Effectively stops tracking the current models.

validate()

Source:
Mixes In:

This is called by Backbone when it needs to perform validation.
You can call it manually without any parameters to validate the
entire model.