5.0.0-beta.1 · Published beta · b06750c5. Published on npm. Match your installed version.

Marionette.MnObject#

Use MnObject for objects that need Marionette events and cleanup without a DOM element. It provides initialize, options, the Events API, a unique cid, and extend, with no Backbone dependency.

MnObject includes:

• Common Marionette Functionality
• Class Events
• Radio API
• State ownership

Documentation Index#

• Instantiating a MnObject
• Unique Client ID
• Destroying a MnObject
• Basic Use
• v4 Migration

Instantiating a MnObject#

Constructor options are shallow-copied into this.options. Own enumerable channelName, radioEvents, radioRequests, and stateEvents options with values other than undefined are also attached directly to the instance. Other options remain available through this.options and getOption unless explicitly merged. The channel options use Marionette's built-in Radio; see that guide for the separate backbone.radio migration boundary.

A supplied state source is borrowed. A source returned by createState(options) is owned and created lazily; getState() returns the exact source. Configured stateEvents subscribe after initialize. Destruction removes those subscriptions and disposes owned State through the selected StateApi. See State before enabling observable State events.

import { MnObject } from 'marionette';

const myObject = new MnObject({ channelName: 'tasks' });

myObject.channelName; // 'tasks'

Unique Client ID#

The cid or client id is a unique identifier automatically assigned to MnObjects when they're first created and by default is prefixed with mno. You can modify the prefix for MnObjects you extend by setting the cidPrefix, which should be a non-empty string when customized. IDs generated with the same prefix by one loaded copy of Marionette are unique, including when different Marionette types use that prefix. Treat the complete cid as opaque: its numeric suffix and allocation order are not API, and its sequence is not coordinated with IDs generated by Underscore or Backbone. The v4-to-v5 migration ledger records the sequence-ownership rationale.

import { MnObject } from 'marionette';

const MyFoo = MnObject.extend({
  cidPrefix: 'foo'
});

const foo = new MyFoo();

foo.cid.startsWith('foo'); // true

Destroying a MnObject#

destroy#

On successful completion of its lifecycle, destroy removes subscriptions the instance made with listenTo, releases its owned Radio event subscriptions and replies, cleans up State, and returns the MnObject synchronously. Returned Promises from destruction hooks are not awaited. It does not reset the shared Radio channel or remove unrelated channel handlers. Listeners registered directly on the instance with on are not removed automatically. If a lifecycle callback throws, cleanup that has not yet run may be skipped; the failure boundaries are described below.

Invoking destroy triggers before:destroy and destroy events and their corresponding onBeforeDestroy and onDestroy methods. Each receives the MnObject followed by the options passed to destroy.

While a destroy() call is in progress, nested calls from either lifecycle event return the same MnObject without restarting teardown. Calls after destruction also return the same MnObject without repeating the lifecycle. Application has an asynchronous destruction lifecycle; see its reference. isDestroyed() is false during before:destroy and true during destroy. If a lifecycle handler throws, the error propagates and stops destruction. The destruction guard remains set; later destroy() calls do not restart hooks or resume cleanup.

A custom override that mutates owned state before calling the base destroy method is outside this guard. See the v4-to-v5 compatibility ledger for the override boundary.

import { MnObject } from 'marionette';

// define a mnobject with an onBeforeDestroy method
const MyObject = MnObject.extend({

  onBeforeDestroy(currentObject, options) {
    // put other custom clean-up code here
  }
});

// create new MnObject instances
const obj = new MyObject();
const source = new MnObject();

// add some event handlers
obj.on('before:destroy', function(currentObject, options) {
  console.log(options.foo);
});
obj.listenTo(source, 'bar', function() {});

// trigger the lifecycle and stop listening to source
obj.destroy({ foo: 'bar' });

isDestroyed#

This method will return a boolean indicating if the mnobject has been destroyed.

import { MnObject } from 'marionette';

const obj = new MnObject();
obj.isDestroyed(); // false
obj.destroy();
obj.isDestroyed(); // true

Basic Use#

Selections is a simple MnObject that manages a selection of things. Because Selections extends from MnObject, it inherits initialize and the Events API.

import { MnObject } from 'marionette';

const Selections = MnObject.extend({

  initialize() {
    this.selections = {};
  },

  select(key, selection) {
    this.selections[key] = selection;
    this.triggerMethod('select', key, selection);
  },

  deselect(key, selection) {
    delete this.selections[key];
    this.triggerMethod('deselect', key, selection);
  }

});

const selections = new Selections();
const truck = { name: 'Dump truck' };

// use the inherited Events API
selections.on('select', function(key, selection) {
  console.log(selection);
});

selections.select('toy', truck);

v4 Migration#

v5 exports MnObject by name from marionette. The historical Object alias and v4 default namespace export are removed. See the v4-to-v5 migration ledger for the replacement paths.