Skip to main content

ExpandableV2Mixin

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

Server responses can contain references to other resources; typically IDs or URLs. The expansion means replacing them with object literals containing the resource information, so that the caller does not have to request every associated resource by an additional server call.

Expanding needs the role to expand from (properties, versions etc.) and optionally the name or names of properties to expand (parent_id, create_user_id etc.).

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)
      .makeExpandableV2(options);
  },

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

ConnectableMixin.mixin(MyModel.prototype);
ExpandableV2Mixin.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 setExpand and resetExpand and fetch the model:

// Set the expansion when creating the model
var model = new MyModel(undefined, {
      connector: connector,
      expand: {
        properties: ['parent_id', 'create_user_id']
      }
    });
model.fetch();

// Set the expansion after creating the model
model.setExpand('properties', ['parent_id', 'create_user_id']);
model.fetch();

makeExpandableV2(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:

expand : One or more resources to expand. Keys and values from the object literal are handled the same way as the setExpand method does the key and value (role and properties). An empty object literal is the default.

expand​

Resources to get expanded in the response (object literal of strings pointing to arrays of strings, empty by default, read-only).

hasExpand(role) : boolean​

Checks if a specific or any resource will be expanded. The role parameter is a string.

// Checks if any resource is expanded
var anythingExpanded = model.hasExpand();
// Checks if any common properties are expancded
var propertiesExpanded = model.hasExpand('properties');

setExpand(role, names) : void​

Makes one or more resources expanded. The role parameter is a string. 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 two resources expanded, option 1
model.setExpand('properties', ['parent_id', 'create_user_id']);
// Have two resources expanded, option 2
model.setExpand('properties', 'parent_id');
model.setExpand('properties', 'create_user_id');
// Have two resource types expanded, option 3
model.setExpand('properties', 'parent_id,create_user_id');

resetExpand(role, names) : void​

Prevents one or more resources from being expanded. The role parameter is a string. If nothing is specified, all roles will be removed (disabled). 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. If nothing is specified, all properties from the role will be removed (disabled).

// Cancel all expansions and fetch the fresh data
model.resetExpand();
model.fetch();

getExpandableResourcesUrlQuery() : string​

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

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

See Also​

ConnectableMixin, ResourceMixin