Skip to main content

AdditionalResourcesV2Mixin

Provides support for the setting URL query parameter flags as introduced by the api/v2/nodes/:id or api/v2/nodes/:id/nodes (V2) resources.

Server responses can contain associated resources to avoid requesting every associated resource by an additional server call, or other data, which may not be needed every time. For example:

perspective : Include the perspective configuration, if the resource can carry one.

metadata : Include the definitions of object properties.

How to apply the mixin to a model​

var MyModel = Backbone.Model.extend({

  constructor: function MyModel(attributes, options) {
    Backbone.Model.prototype.constructor.apply(this, arguments);
    this
      .makeConnectable(options)
      .makeAdditionalResourcesV2Mixin(options);
  },

  url: function () {
    var url = Url.combine(this.connector.connection.url, 'myresource'),
        query = Url.combineQueryString(
          this.getAdditionalResourcesUrlQuery()
        );
    return query ? url + '?' + query : url;
  }
  
});

ConnectableMixin.mixin(MyModel.prototype);
AdditionalResourcesV2Mixin.mixin(MyModel.prototype);

This mixin us usually combined together with the ConnectableMixin or with another cumulated mixin which includes it.

How to use the mixin​

Set up the URL parameters by calling includeResources and excludeResources and fetch the model:

// Set the inclusion when creating the model
var model = new MyModel(undefined, {
      connector: connector,
      includeResources: ['perspective']
    });
model.fetch();

// Set the inclusion after creating the model
model.includeResources('perspective');
model.fetch();

makeAdditionalResourcesV2Mixin(options) : this​

Must be called in the constructor to initialize the mixin functionality. Expects the Backbone.Model or Backbone.Collection constructor options passed in.

Recognized option properties:

includeResources : One or more resources to include. The value is handled the same way as the includeResources method does it. An empty array is the default.

_additionalResources​

Resources to get included in the response in the response (array of strings, empty by default, read-only).

includeResources(names) : void​

Makes one or more resources included. The names parameter can be either string, or an array of strings. The string can contain a comma-delimited list, in which case it will be split to an array.

// Have a resources included, option 1
model.includeResources('perspective');
// Have a resource included, option 2
model.includeResources(['perspective']);

excludeResources(names) : void​

Prevents one or more resources from being included. The names parameter can be either string, or an array of strings, or nothing. The string can contain a comma-delimited list, in which case it will be split to an array. If nothing is specified, all inclusions will be removed (disabled).

// Cancel all inclusions and fetch the fresh data
model.excludeResources();
model.fetch();

getAdditionalResourcesUrlQuery() : string​

Formats the URL query parameters for the resource inclusion. They can be concatenated with other URL query parts (both object literals and strings) by Url.combineQueryString.

var url = ...,
    query = Url.combineQueryString(
      ...,
      this.getAdditionalResourcesUrlQuery()
    );
if (query) {
  url = Url.appendQuery(url, query);
}

See Also​

ConnectableMixin, ResourceMixin