Plato - region.js

/* jshint maxcomplexity: 16, maxstatements: 45, maxlen: 120 */

// Region
// ------

// Manage the visual regions of your composite application. See
// http://lostechies.com/derickbailey/2011/12/12/composite-js-apps-regions-and-region-managers/

Marionette.Region = Marionette.Object.extend({
  constructor: function(options) {

// set options temporarily so that we can get `el`.
    // options will be overriden by Object.constructor
    this.options = options || {};
    this.el = this.getOption('el');

// Handle when this.el is passed in as a $ wrapped element.
    this.el = this.el instanceof Backbone.$ ? this.el[0] : this.el;

if (!this.el) {
      throw new Marionette.Error({
        name: 'NoElError',
        message: 'An "el" must be specified for a region.'
      });
    }

this.$el = this.getEl(this.el);
    Marionette.Object.call(this, options);
  },

// Displays a backbone view instance inside of the region.
  // Handles calling the `render` method for you. Reads content
  // directly from the `el` attribute. Also calls an optional
  // `onShow` and `onDestroy` method on your view, just after showing
  // or just before destroying the view, respectively.
  // The `preventDestroy` option can be used to prevent a view from
  // the old view being destroyed on show.
  // The `forceShow` option can be used to force a view to be
  // re-rendered if it's already shown in the region.
  show: function(view, options) {
    if (!this._ensureElement()) {
      return;
    }

this._ensureViewIsIntact(view);
    Marionette.MonitorDOMRefresh(view);

var showOptions     = options || {};
    var isDifferentView = view !== this.currentView;
    var preventDestroy  = !!showOptions.preventDestroy;
    var forceShow       = !!showOptions.forceShow;

// We are only changing the view if there is a current view to change to begin with
    var isChangingView = !!this.currentView;

// Only destroy the current view if we don't want to `preventDestroy` and if
    // the view given in the first argument is different than `currentView`
    var _shouldDestroyView = isDifferentView && !preventDestroy;

// Only show the view given in the first argument if it is different than
    // the current view or if we want to re-show the view. Note that if
    // `_shouldDestroyView` is true, then `_shouldShowView` is also necessarily true.
    var _shouldShowView = isDifferentView || forceShow;

if (isChangingView) {
      this.triggerMethod('before:swapOut', this.currentView, this, options);
    }

if (this.currentView && isDifferentView) {
      delete this.currentView._parent;
    }

if (_shouldDestroyView) {
      this.empty();

// A `destroy` event is attached to the clean up manually removed views.
    // We need to detach this event when a new view is going to be shown as it
    // is no longer relevant.
    } else if (isChangingView && _shouldShowView) {
      this.currentView.off('destroy', this.empty, this);
    }

if (_shouldShowView) {

// We need to listen for if a view is destroyed
      // in a way other than through the region.
      // If this happens we need to remove the reference
      // to the currentView since once a view has been destroyed
      // we can not reuse it.
      view.once('destroy', this.empty, this);

// make this region the view's parent,
      // It's important that this parent binding happens before rendering
      // so that any events the child may trigger during render can also be
      // triggered on the child's ancestor views
      view._parent = this;
      this._renderView(view);

if (isChangingView) {
        this.triggerMethod('before:swap', view, this, options);
      }

this.triggerMethod('before:show', view, this, options);
      Marionette.triggerMethodOn(view, 'before:show', view, this, options);

if (isChangingView) {
        this.triggerMethod('swapOut', this.currentView, this, options);
      }

// An array of views that we're about to display
      var attachedRegion = Marionette.isNodeAttached(this.el);

// The views that we're about to attach to the document
      // It's important that we prevent _getNestedViews from being executed unnecessarily
      // as it's a potentially-slow method
      var displayedViews = [];

var attachOptions = _.extend({
        triggerBeforeAttach: this.triggerBeforeAttach,
        triggerAttach: this.triggerAttach
      }, showOptions);

if (attachedRegion && attachOptions.triggerBeforeAttach) {
        displayedViews = this._displayedViews(view);
        this._triggerAttach(displayedViews, 'before:');
      }

this.attachHtml(view);
      this.currentView = view;

if (attachedRegion && attachOptions.triggerAttach) {
        displayedViews = this._displayedViews(view);
        this._triggerAttach(displayedViews);
      }

if (isChangingView) {
        this.triggerMethod('swap', view, this, options);
      }

this.triggerMethod('show', view, this, options);
      Marionette.triggerMethodOn(view, 'show', view, this, options);

return this;
    }

return this;
  },

triggerBeforeAttach: true,
  triggerAttach: true,

_triggerAttach: function(views, prefix) {
    var eventName = (prefix || '') + 'attach';
    _.each(views, function(view) {
      Marionette.triggerMethodOn(view, eventName, view, this);
    }, this);
  },

_displayedViews: function(view) {
    return _.union([view], _.result(view, '_getNestedViews') || []);
  },

_renderView: function(view) {
    if (!view.supportsRenderLifecycle) {
      Marionette.triggerMethodOn(view, 'before:render', view);
    }
    view.render();
    if (!view.supportsRenderLifecycle) {
      Marionette.triggerMethodOn(view, 'render', view);
    }
  },

_ensureElement: function() {
    if (!_.isObject(this.el)) {
      this.$el = this.getEl(this.el);
      this.el = this.$el[0];
    }

if (!this.$el || this.$el.length === 0) {
      if (this.getOption('allowMissingEl')) {
        return false;
      } else {
        throw new Marionette.Error('An "el" ' + this.$el.selector + ' must exist in DOM');
      }
    }
    return true;
  },

_ensureViewIsIntact: function(view) {
    if (!view) {
      throw new Marionette.Error({
        name: 'ViewNotValid',
        message: 'The view passed is undefined and therefore invalid. You must pass a view instance to show.'
      });
    }

if (view.isDestroyed) {
      throw new Marionette.Error({
        name: 'ViewDestroyedError',
        message: 'View (cid: "' + view.cid + '") has already been destroyed and cannot be used.'
      });
    }
  },

// Override this method to change how the region finds the DOM
  // element that it manages. Return a jQuery selector object scoped
  // to a provided parent el or the document if none exists.
  getEl: function(el) {
    return Backbone.$(el, Marionette._getValue(this.options.parentEl, this));
  },

// Override this method to change how the new view is
  // appended to the `$el` that the region is managing
  attachHtml: function(view) {
    this.$el.contents().detach();

this.el.appendChild(view.el);
  },

// Destroy the current view, if there is one. If there is no
  // current view, it does nothing and returns immediately.
  empty: function(options) {
    var view = this.currentView;

var emptyOptions = options || {};
    var preventDestroy  = !!emptyOptions.preventDestroy;
    // If there is no view in the region
    // we should not remove anything
    if (!view) { return this; }

view.off('destroy', this.empty, this);
    this.triggerMethod('before:empty', view);
    if (!preventDestroy) {
      this._destroyView();
    }
    this.triggerMethod('empty', view);

// Remove region pointer to the currentView
    delete this.currentView;

if (preventDestroy) {
      this.$el.contents().detach();
    }

return this;
  },

// call 'destroy' or 'remove', depending on which is found
  // on the view (if showing a raw Backbone view or a Marionette View)
  _destroyView: function() {
    var view = this.currentView;
    if (view.isDestroyed) { return; }

if (!view.supportsDestroyLifecycle) {
      Marionette.triggerMethodOn(view, 'before:destroy', view);
    }
    if (view.destroy) {
      view.destroy();
    } else {
      view.remove();

// appending isDestroyed to raw Backbone View allows regions
      // to throw a ViewDestroyedError for this view
      view.isDestroyed = true;
    }
    if (!view.supportsDestroyLifecycle) {
      Marionette.triggerMethodOn(view, 'destroy', view);
    }
  },

// Attach an existing view to the region. This
  // will not call `render` or `onShow` for the new view,
  // and will not replace the current HTML for the `el`
  // of the region.
  attachView: function(view) {
    if (this.currentView) {
      delete this.currentView._parent;
    }
    view._parent = this;
    this.currentView = view;
    return this;
  },

// Checks whether a view is currently present within
  // the region. Returns `true` if there is and `false` if
  // no view is present.
  hasView: function() {
    return !!this.currentView;
  },

// Reset the region by destroying any existing view and
  // clearing out the cached `$el`. The next time a view
  // is shown via this region, the region will re-query the
  // DOM for the region's `el`.
  reset: function() {
    this.empty();

if (this.$el) {
      this.el = this.$el.selector;
    }

delete this.$el;
    return this;
  }

// Static Methods
{

// Build an instance of a region by passing in a configuration object
  // and a default region class to use if none is specified in the config.
  //
  // The config object should either be a string as a jQuery DOM selector,
  // a Region class directly, or an object literal that specifies a selector,
  // a custom regionClass, and any options to be supplied to the region:
  //
  // ```js
  // {
  //   selector: "#foo",
  //   regionClass: MyCustomRegion,
  //   allowMissingEl: false
  // }
  // ```
  //
  buildRegion: function(regionConfig, DefaultRegionClass) {
    if (_.isString(regionConfig)) {
      return this._buildRegionFromSelector(regionConfig, DefaultRegionClass);
    }

if (regionConfig.selector || regionConfig.el || regionConfig.regionClass) {
      return this._buildRegionFromObject(regionConfig, DefaultRegionClass);
    }

if (_.isFunction(regionConfig)) {
      return this._buildRegionFromRegionClass(regionConfig);
    }

throw new Marionette.Error({
      message: 'Improper region configuration type.',
      url: 'marionette.region.html#region-configuration-types'
    });
  },

// Build the region from a string selector like '#foo-region'
  _buildRegionFromSelector: function(selector, DefaultRegionClass) {
    return new DefaultRegionClass({el: selector});
  },

// Build the region from a configuration object
  // ```js
  // { selector: '#foo', regionClass: FooRegion, allowMissingEl: false }
  // ```
  _buildRegionFromObject: function(regionConfig, DefaultRegionClass) {
    var RegionClass = regionConfig.regionClass || DefaultRegionClass;
    var options = _.omit(regionConfig, 'selector', 'regionClass');

if (regionConfig.selector && !options.el) {
      options.el = regionConfig.selector;
    }

return new RegionClass(options);
  },

// Build the region directly from a given `RegionClass`
  _buildRegionFromRegionClass: function(RegionClass) {
    return new RegionClass();
  }
});

region.js

Maintainability

Lines of code

Difficulty

Estimated Errors

Function weight

By Complexity

By SLOC