Skip to main content

FieldsV2Mixin

Provides support for the setting fields URL query parameter as introduced by the api/v2/members/favorites or api/v2/members/accessed (V2) resources.

Server responses can contain various properties, which can increase the response size, if all of them were always returned.

Adding a field needs the role, which contains them (properties, versions etc.), and optionally their names too (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)
      .makeFieldsV2(options);
  },

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

ConnectableMixin.mixin(MyModel.prototype);
FieldsV2Mixin.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 setFields and resetFields and fetch the model:

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

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

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

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

fields​

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

hasFields(role) : boolean​

Checks if a specific field or any fields will be included. The role parameter is a string.

// Checks if any fields are included
var anyFields = model.hasFields();
// Checks if any common property fields are included
var propertyFields = model.hasFields('properties');

setFields(role, names) : void​

Adds one or more fields to the response. 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 fields added, option 1
model.setFields('properties', ['parent_id', 'create_user_id']);
// Have two fields added, option 2
model.setFields('properties', 'parent_id');
model.setFields('properties', 'create_user_id');
// Have two fields added, option 3
model.setFields('properties', 'parent_id,create_user_id');

resetFields(role, names) : void​

Removes one or more fields from the response. The role parameter is a string. If nothing is specified, all roles will be removed (not returned). 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 (not returned).

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

getResourceFieldsUrlQuery() : string​

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

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

See Also​

ConnectableMixin