restmod

Class: RecordApi

RecordApi

new RecordApi()

Provides record synchronization and manipulation methods. This is the base API for every restmod record.

TODO: Talk about the object lifecycle.

Object lifecycle hooks

For $fetch:

  • before-fetch
  • before-request
  • after-request[-error]
  • after-feed (only called if no errors)
  • after-fetch[-error]

For $save when creating:

  • before-render
  • before-save
  • before-create
  • before-request
  • after-request[-error]
  • after-feed (only called if no errors)
  • after-create[-error]
  • after-save[-error]

For $save when updating:

  • before-render
  • before-save
  • before-update
  • before-request
  • after-request[-error]
  • after-feed (only called if no errors)
  • after-update[-error]
  • after-save[-error]

For $destroy:

  • before-destroy
  • before-request
  • after-request[-error]
  • after-destroy[-error]
Properties:
Name Type Description
$scope object

The record's scope (see ScopeApi)
$pk mixed

The record's primary key
$pk mixed

The record primary key
$scope object

The collection scope (hierarchical scope, not angular scope)
Source:
  • module/api/record-api.js, line 44

Extends

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:
Source:
  • module/api/common-api.js, line 413
Returns:

self

Type
CommonApi

$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:
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:
Source:
  • module/api/common-api.js, line 261
Returns:

$q promise

Type
promise

$buildScope(_for, _partial) → {RelationScope}

Default item child scope factory.

By default, no create url is provided and the update/destroy url providers attempt to first use the unscoped resource url.

// TODO: create special api to hold scope (so it is not necessary to recreate the whole object every time.)

Parameters:
Name Type Description
_for mixed

Scope target type, accepts any model class.
_partial string

Partial route.
Source:
  • module/api/record-api.js, line 144
Returns:

New scope.

Type
RelationScope

$buildUrl() → {string}

Called the resource's scope $urlFor method to build the url for the record using the proper scope.

By default the resource partial url is just its $pk property. This can be overriden to provide other routing approaches.

Source:
  • module/api/record-api.js, line 126
Returns:

The resource partial url

Type
string

$cancel() → {CommonApi}

Cancels all pending actions registered with $action.

Inherited From:
Source:
  • module/api/common-api.js, line 446
Returns:

self

Type
CommonApi

$decode(_raw, _mask) → {RecordApi}

Feed raw data to this instance.

Parameters:
Name Type Description
_raw object

Raw data to be fed
_mask string

'CRU' mask
Source:
  • module/api/record-api.js, line 179
Returns:

this

Type
RecordApi

$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:
Source:
  • module/api/common-api.js, line 188
Returns:

self

Type
CommonApi

$destroy() → {RecordApi}

Begin a server request to destroy the resource.

The request's promise can be accessed using the $asPromise method.

Source:
  • module/api/record-api.js, line 362
Returns:

this

Type
RecordApi

$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:
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:
Source:
  • module/api/common-api.js, line 239
Returns:

Dispatcher evaluator

Type
function

$each(_fun) → {RecordApi}

Iterates over the object non-private properties

Parameters:
Name Type Description
_fun function

Function to call for each
Source:
  • module/api/record-api.js, line 160
Returns:

self

Type
RecordApi

$encode(_mask) → {string}

Generate data to be sent to the server when creating/updating the resource.

Parameters:
Name Type Description
_mask string

'CRU' mask
Source:
  • module/api/record-api.js, line 195
Returns:

raw data

Type
string

$extend(_other) → {RecordApi}

Copyies another object's non-private properties.

This method runs inside the promise chain, so calling

Bike.$find(1).$extend({ size: "L" }).$save();

Will first fetch the bike data and after it is loaded the new size will be applied and then the updated model saved.

Parameters:
Name Type Description
_other object

Object to merge.
Source:
  • module/api/record-api.js, line 244
Returns:

self

Type
RecordApi

$fetch(_params) → {RecordApi}

Begin a server request for updated resource data.

The request's promise can be accessed using the $asPromise method.

Parameters:
Name Type Description
_params object

Optional list of params to be passed to object request.
Source:
  • module/api/record-api.js, line 211
Returns:

this

Type
RecordApi

$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:
Source:
  • module/api/common-api.js, line 334
Returns:

self

Type
CommonApi

$hasPendingActions() → {Boolean}

Returns true if object has queued actions

Inherited From:
Source:
  • module/api/common-api.js, line 464
Returns:

Object request pending status.

Type
Boolean

$initialize()

Called by record constructor on initialization.

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

Source:
  • module/api/record-api.js, line 108

$moveTo(_to) → {RecordApi}

Changes the location of the object in the bound collection.

If object hasn't been revealed, then this method will change the index where object will be revealed at.

Parameters:
Name Type Description
_to integer

New object position (index)
Source:
  • module/api/record-api.js, line 403
Returns:

this

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:
Source:
  • module/api/common-api.js, line 157
Returns:

self

Type
CommonApi

$reveal(_show) → {RecordApi}

Reveal in collection

If instance is bound to a collection and it hasnt been revealed (because it's new and hasn't been saved), then calling this method without parameters will force the object to be added to the collection.

If this method is called with _show set to false, then the object wont be revealed by a save operation.

Parameters:
Name Type Description
_show boolean

Whether to reveal inmediatelly or prevent automatic reveal.
Source:
  • module/api/record-api.js, line 426
Returns:

this

Type
RecordApi

$save(_patch) → {RecordApi}

Begin a server request to create/update/patch resource.

A patch is only executed if model is identified and a patch property list is given. It is posible to change the method used for PATCH operations by setting the patchMethod configuration.

If resource is new and it belongs to a collection and it hasnt been revealed, then it will be revealed.

The request's promise can be accessed using the $asPromise method.

Parameters:
Name Type Description
_patch array

Optional list of properties to send in update operation.
Source:
  • module/api/record-api.js, line 283
Returns:

this

Type
RecordApi

$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:
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:
Source:
  • module/api/common-api.js, line 286
Returns:

self

Type
CommonApi

$update(_other) → {RecordApi}

Shortcut method used to extend and save a model.

This method will not force a PUT, if object is new $update will attempt to POST.

Parameters:
Name Type Description
_other object

Data to change
Source:
  • module/api/record-api.js, line 264
Returns:

self

Type
RecordApi

$url(_for) → {string}

Gets this resource url.

Parameters:
Name Type Description
_for string

Intended usage for the url (optional)
Inherited From:
Source:
  • module/api/common-api.js, line 50
Returns:

The resource url.

Type
string