C class

Relation

Constructor

new Relation(klass)
klass : Record

A Model class, not an instance of the klass

Instance Properties

P   bindedObjects: Object.<string, Object>

Object containing references to objects this instance is listening to

P   eventListeners: Object.<string, Array>

Object containing all event listeners

P   listenerId: string

Unique identifier for this event bus instance

Instance Methods

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   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   groupBy(on) → Object

Group the results by a attribute

Parameters

on : *

Attributes to group the results by

Returns

F   initialize()

placeholder function for extending

F   load(eventParameters) → Promise.<Record>>

Load and return the relation.

If the relation is loaded the loaded relation will be returned and no events will be fired.

Use [reload]{@linkcode Relation#reload} if you wish to fetch the relation from the server again.

If there is currently a request in flight to fetch the relation from the server the result of that request will be returned after the original load finishes. A new request will not be sent.

Parameters

eventParameters : *

Parameters to pass to events fired in this function

Returns

Promise.Record>>
F   reload(eventParameters) → Array.<Record>

Load the relation from the server even if it's in memory.

If there is currently a request in flight to fetch the relation it will be cancelled and a new request will be sent. The result of the new request will be used to fullfill the promise of the original request before fulling the promise of the new request.

Parameters

eventParameters : *

Parameters to pass to events fired in this function

Returns

Array.<Record>
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   resolveTarget(response) → Array.<Record>

Resolves an array of attribute hashes into Record instances, reusing records already in target when their primary key matches while updating them with the response and instantiating new records otherwise.

Parameters

response : Array.<Object>

An array of attribute hashes

Returns

Array.<Record>
F   setTarget(records, eventParameters)

Sets the records of this relation, removing and adding records as necessary.

Parameters

records : Array.<Record>
eventParameters : *

Parameters to pass to events fired in this function

F   toPath(options) → string

Build the path for fetching this relation from the server.

Constructs the path from the Record connection's path and appends a query string built from the relation's current state (where, order, limit, offset, etc.). Any keys in options are merged over the generated params, letting callers override individual query values.

If options.extension is provided it is used to append a file extension to the path (e.g. "csv") before the query string is appended.

Parameters

options : Object optional
extension : string optional

Converted to a path extension.

params : Object optional

Param overrides merged over the generated query params.

Returns

string

Events

E   afterAdd

Fired when records are added to the relation. Will not be called for any records already in memory.

Parameters

addedRecords : Array.<Record>

The records that were added to the relation

eventParameters : *

optional parameters from the {@link Relation#setTarget} call that gets passed to the callbacks.

E   afterLoad

Fired after the request to the server has been returned and processed and the models are loaded.

Parameters

records : Array.<Record>

The current records in memory

eventParameters : *

optional parameters from the {@link Relation#load} call that get passed to the callbacks.

E   afterRemove

Fired when records are removed to the relation.

Parameters

removedRecords : Array.<Record>

The records that were removed from the relation

eventParameters : *

optional parameters from the {@link Relation#setTarget} call that gets passed to the callbacks.

E   beforeLoad

Fired before sending the request to the server to load the records.

Parameters

records : Array.<Record>

The current records in memory

eventParameters : *

optional parameters from the {@link Relation#load} call that get passed to the callbacks.

E   beforeSetTarget

Fired before setting (adding or removing) the records of the relation.

Parameters

newRecords : Array.<Record>

The records that are being set

currentRecords : Array.<Record>

The records that are currently loaded

eventParameters : *

optional parameters from the {@link Relation#setTarget} call that gets passed to the callbacks.

E   changed

An attribute of the relation was changed

Parameters

attribute : "distinct" | "limit" | "offset" | "order" | "where"

The attribute on the query/relation that changed

newValue : *

The new value of the attribute

E   changed:[attribute]

attribute of the relation was changed; where attribute is any of the following "distinct", "limit", "offset", "order", "where"

Parameters

newValue : *

The new value of the attribute

E   record:afterSync

Fired on each collection containing this record after the record has been synced with the server.

Parameters

record : Record

The record that was synced

savedChanges : Object

The changes that were synced

E   record:afterSync:{attribute}

Fired on each collection containing this record after a specific attribute on the record has been synced.

Parameters

record : Record

The record that was synced

oldValue : *

The previous value of the attribute

newValue : *

The new value of the attribute

E   record:changed

Fired on each collection containing this record when the record's attributes change.

Parameters

record : Record

The record that was changed

changes : Object

The changes made, with [oldValue, newValue] pairs

E   record:changed:{attribute}

Fired on each collection containing this record when a specific attribute on the record is changed.

Parameters

record : Record

The record that was changed

oldValue : *

The previous value of the attribute

newValue : *

The new value of the attribute