Class: CollectionApi

Extends

• ScopeApi
• CommonApi

Methods

$action() → {CommonApi}

Registers a new action to be executed in the promise queue.

Registered pending actions can be canceled using $cancel

$cancel will also cancel any ongoing call to $send (will not abort it yet though...)

Inherited From:

• CommonApi#$action

Source:

• module/api/common-api.js, line 413

Returns:

self

Type

CommonApi

$add(_obj) → {CollectionApi}

Adds an item to the back of the collection. This method does not attempt to send changes to the server. To create a new item and add it use $create or $build.

Triggers after-add callbacks.

Parameters:

Name	Type	Description
_obj	RecordApi	Item to be added

Source:

• module/api/collection-api.js, line 150

Returns:

self

Type

CollectionApi

$always(_fun) → {CommonApi}

Promise chaining method, similar to then but executes same callback in success or error.

Usage:

col.$fetch().$always(function() { });

Parameters:

Name	Type	Description
_fun	function	success/error callback

Inherited From:

• CommonApi#$always

Source:

• module/api/common-api.js, line 314

Returns:

self

Type

CommonApi

$asPromise() → {promise}

Returns this object last promise.

If promise does not exist, then a new one is generated that resolves to the object itsef. The new promise is not set as the current object promise, for that use $then.

Usage:

col.$fetch().$asPromise();

Inherited From:

• CommonApi#$asPromise

Source:

• module/api/common-api.js, line 261

Returns:

$q promise

Type

promise

$build(_init) → {RecordApi}

Builds a new instance of this model, does not assign a pk to the created object.

ATTENTION: item will not show in collection until $save is called. To reveal item before than call $reveal.

Parameters:

Name	Type	Description
_init	object	Initial values

Inherited From:

• ScopeApi#$build

Source:

• module/api/scope-api.js, line 53

Returns:

single record

Type

RecordApi

$buildRaw(_raw) → {RecordApi}

Builds a new instance of this model using undecoded data.

ATTENTION: does not automatically reveal item in collection, chain a call to $reveal to do so.

Parameters:

Name	Type	Description
_raw	object	Undecoded data

Inherited From:

• ScopeApi#$buildRaw

Source:

• module/api/scope-api.js, line 67

Returns:

single record

Type

RecordApi

$cancel() → {CommonApi}

Cancels all pending actions registered with $action.

Inherited From:

• CommonApi#$cancel

Source:

• module/api/common-api.js, line 446

Returns:

self

Type

CommonApi

$clear() → {CollectionApi}

Resets the collection's contents

Source:

• module/api/collection-api.js, line 99

Returns:

self

Type

CollectionApi

$collection(_params, _scope) → {CollectionApi}

Builds a new collection bound to this scope.

If scope is another collection then it will inherit its parameters

Collections are bound to an api resource.

Parameters:

Name	Type	Description
_params	object	Additional query string parameters
_scope	object	Scope override (optional)

Inherited From:

• ScopeApi#$collection

Source:

• module/api/scope-api.js, line 111

Returns:

Model Collection

Type

CollectionApi

$create(_attr) → {RecordApi}

Builds and saves a new instance of this model

Parameters:

Name	Type	Description
_attr	object	Data to be saved

Inherited From:

• ScopeApi#$create

Source:

• module/api/scope-api.js, line 94

Returns:

single record

Type

RecordApi

$decode(_raw, _mask) → {CollectionApi}

Feeds raw collection data into the collection.

This method is for use in collections only.

Parameters:

Name	Type	Description
_raw	array	Data to add
_mask	string	'CRU' mask

Source:

• module/api/collection-api.js, line 62

Returns:

self

Type

CollectionApi

$decorate(_hooks, _fun) → {CommonApi}

Registers hooks to be used only inside the given function (decorated context).

// special fetch method that sends a special token header.
restmod.mixin({
  $fetchWithToken: function(_token) {
    return this.$decorate({
      'before-fetch': function(_req) {
        _req.headers = _req.headers || {};
        _req.headers['Token'] = _token;
      }
    ), function() {
      return this.$fetch();
    })
  }
});

Parameters:

Name	Type	Description
_hooks	object | function	Hook mapping object or hook execution method.
_fun	function	Function to be executed in with decorated context, this function is executed in the callee object context.

Inherited From:

• CommonApi#$decorate

Source:

• module/api/common-api.js, line 188

Returns:

self

Type

CommonApi

$dispatch(_hook, _args, _ctx) → {CommonApi}

Executes a given hook callbacks using the current dispatcher context.

This method can be used to provide custom object lifecycle hooks.

Usage:

var mixin = restmod.mixin({
  triggerDummy: function(_param) {
    this.$dispatch('dummy-hook', _param);
  }
});

// Then hook can be used at model definition to provide type-level customization:
var Bike $resmod.model('/api/bikes', mixin, {
  '~dummy-hook': function() {
    alert('This is called for every bike');
  }
};

// or at instance level:
var myBike = Bike.$build();
myBike.$on('dummy-hook', function() {
  alert('This is called for myBike only');
});

// or event at decorated context level
myBike.$decorate({
  'dummy-hook': function() {
    alert('This is called for myBike only inside the decorated context');
  }
}, fuction() {
 // decorated context
});

Parameters:

Name	Type	Description
_hook	string	Hook name
_args	array	Hook arguments
_ctx	object	Hook execution context override

Inherited From:

• CommonApi#$dispatch

Source:

• module/api/common-api.js, line 108

Returns:

self

Type

CommonApi

$dispatcher() → {function}

Retrieves the current object's event dispatcher function.

This method can be used in conjuction with $decorate to provide a consistent hook context during async operations. This is important when building extensions that want to support the contextual hook system in asynchronic operations.

For more information aboout contextual hooks, see the CommonApi#decorate documentation.

Usage:

restmod.mixin({
  $saveAndTrack: function() {
    var dsp = this.$dispatcher(), // capture the current dispatcher function.
        self = this;
    this.$save().$then(function() {
      this.$send({ path: '/traces', data: 'ble' }, function() {
        this.$decorate(dsp, function() {
          // the event is dispatched using the dispatcher function available when $saveAndTrack was called.
          this.$dispatch('trace-stored');
        });
      });
    });
  }
})

Inherited From:

• CommonApi#$dispatcher

Source:

• module/api/common-api.js, line 239

Returns:

Dispatcher evaluator

Type

function

$encode(_mask) → {CollectionApi}

Encodes array data into a its serialized version.

Parameters:

Name	Type	Description
_mask	string	'CRU' mask

Source:

• module/api/collection-api.js, line 82

Returns:

self

Type

CollectionApi

$fetch(_params) → {CollectionApi}

Begin a server request to populate collection. This method does not clear the collection contents by default, use $refresh to reset and fetch.

This method is for use in collections only.

Parameters:

Name	Type	Description
_params	object | function	Additional request parameters, not stored in collection, if a function is given, then it will be called with the request object to allow requet customization.

Source:

• module/api/collection-api.js, line 117

Returns:

self

Type

CollectionApi

$finally(_cb) → {CommonApi}

Promise chaining, keeps the model instance as the chain context.

Calls ´$q.finally´ on the collection's last promise, updates last promise with finally result.

Usage:

col.$fetch().$finally(function() { });

Parameters:

Name	Type	Description
_cb	function	callback

Inherited From:

• CommonApi#$finally

Source:

• module/api/common-api.js, line 334

Returns:

self

Type

CommonApi

$find(_pk, _params) → {RecordApi}

Attempts to resolve a resource using provided private key.

Parameters:

Name	Type	Description
_pk	mixed	Private key
_params	object	Additional query parameters

Inherited From:

• ScopeApi#$find

Source:

• module/api/scope-api.js, line 82

Returns:

single record

Type

RecordApi

$hasPendingActions() → {Boolean}

Returns true if object has queued actions

Inherited From:

• CommonApi#$hasPendingActions

Source:

• module/api/common-api.js, line 464

Returns:

Object request pending status.

Type

Boolean

$indexOf(_obj) → {number}

Finds the location of an object in the array.

If a function is provided then the index of the first item for which the function returns true is returned.

Parameters:

Name	Type	Description
_obj	RecordApi | function	Object to find

Source:

• module/api/collection-api.js, line 200

Returns:

Object index or -1 if not found

Type

number

$initialize()

Called by collection constructor on initialization.

Note: Is better to add a hook on after-init than overriding this method.

Source:

• module/api/collection-api.js, line 46

$new(_pk, _scope) → {RecordApi}

Builds a new instance of this model, bound to this instance scope, sets its primary key.

Parameters:

Name	Type	Description
_pk	mixed	object private key
_scope	object	scope override (optional)

Inherited From:

• ScopeApi#$new

Source:

• module/api/scope-api.js, line 39

Returns:

New model instance

Type

RecordApi

$on(_hook, _fun) → {CommonApi}

Registers an instance hook.

An instance hook is called only for events generated by the calling object.

var bike = Model.$build(), bike2 = Model.$build();
bike.$on('before-save', function() { alert('saved!'); });

bike.$save(); // 'saved!' alert is shown after bike is saved
bike2.$save(); // no alert is shown after bike2 is saved

Parameters:

Name	Type	Description
_hook	string	Hook name
_fun	function	Callback

Inherited From:

• CommonApi#$on

Source:

• module/api/common-api.js, line 157

Returns:

self

Type

CommonApi

$remove(_obj) → {CollectionApi}

Removes an item from the collection.

This method does not send a DELETE request to the server, it just removes the item locally. To remove an item AND send a DELETE use the item's $destroy method.

Triggers after-remove callbacks.

Parameters:

Name	Type	Description
_obj	RecordApi	Item to be removed

Source:

• module/api/collection-api.js, line 179

Returns:

self

Type

CollectionApi

$search(_params) → {CollectionApi}

Generates a new collection bound to this context and url and calls $fetch on it.

Parameters:

Name	Type	Description
_params	object	Collection parameters

Inherited From:

• ScopeApi#$search

Source:

• module/api/scope-api.js, line 123

Returns:

record collection

Type

CollectionApi

$send(_options, _success, _error) → {CommonApi}

Low level communication method, wraps the $http api.

• You can access last request promise using the $asPromise method.
• Pending requests will be available at the $pending property (array).
• Current request execution status can be queried using the $status property (current request, not last).
• The $status property refers to the current request inside $send _success and _error callbacks.

Parameters:

Name	Type	Description
_options	object	$http options
_success	function	sucess callback (sync)
_error	function	error callback (sync)

Inherited From:

• CommonApi#$send

Source:

• module/api/common-api.js, line 356

Returns:

self

Type

CommonApi

$then(_success, _error) → {CommonApi}

Promise chaining method, keeps the model instance as the chain context.

Calls $q.then on the model's last promise.

Usage:

col.$fetch().$then(function() { });

Parameters:

Name	Type	Description
_success	function	success callback
_error	function	error callback

Inherited From:

• CommonApi#$then

Source:

• module/api/common-api.js, line 286

Returns:

self

Type

CommonApi

$url(_for) → {string}

Gets this resource url.

Parameters:

Name	Type	Description
_for	string	Intended usage for the url (optional)

Inherited From:

• CommonApi#$url

Source:

• module/api/common-api.js, line 50

Returns:

The resource url.

Type

string

$urlFor(_resource) → {string|null}

provides urls for scope's resources.

Parameters:

Name	Type	Description
_resource	mixed	The target resource.

Inherited From:

• ScopeApi#$urlFor

Source:

• module/api/scope-api.js, line 24

Returns:

The url or nill if resource does not meet the url requirements.

Type

string | null