childManagement.js

/*
 * childManagement
 * ===============
 */
void function() {

  var childrenKey = '_children';

  /*
   * Creates a private collection for child views on the receiver if one
   * does not already exist.
   * Returns the collection.
   */
  function lazyGetChildren(/*Object*/receiver) {
    var children = receiver[childrenKey];
    if (children) return children;
    return receiver[childrenKey] = {};
  }


  /**
   * Object the can be inherited from or mixed into others providing
   * an internal collection of child Backbone views and basic methods
   * to manage them.
   *
   * If used as a mixin or inheritance type, the receiving object or
   * prototype doesn't need to derive from Backbone.View. However the
   * views it manages must.
   */
  var childManagement = tbbase.childManagement = {
    /**
     * Add one or more child views to internal collection.
     *
     *  addChildren(view1, view2, etc)
     *
     * @param {Backbone.View} One or more views, comma separated.
     * @returns {Number} Number of children added to internal collection.
     * @api public
     */
    addChildren: function addChildren() {
      var count = 0;
      if (! arguments.length) return count;
      var children = lazyGetChildren(this);
      for (var i = arguments.length; i--;) {
        var view = arguments[i];
        if (children[view.cid] == view)       continue;
        if (!(view instanceof Backbone.View)) continue;
        children[view.cid] = view;
        ++count;
      }
      return count;
    },


    /*
     * Invokes remove() on views in inernal collection and
     * then deletes them from said collection.
     *
     * Remove all children
     *   removeChildren()
     *
     * Remove specific children
     *   removeChildren(cid1, cid2, etc)
     *
     * @param {String} Optional. One or more cid's.
     * @returns {Number} Number of children removed from internal collection.
     * @api public
     */
    removeChildren: function removeChildren() {
      var children = lazyGetChildren(this);
      var cids = arguments.length
        ? arguments
        : Object.keys(children);
      var count = 0;
      for (var i = cids.length; i--;) {
        var cid = cids[i];
        if (typeof cid !== 'string') throw new TypeError('View cid expected');
        var view = children[cid];
        if (! view) continue;
        view.remove();
        children[cid] = undefined;
        ++count;
      }
      // Reset internal collection on remove all
      // to get rid of keys with emtpty values.
      if (! arguments.length) {
        this[childrenKey] = {};
      }
      return count;
    },


    /*
     * Gets a view from the internal child collection by view cid.
     *
     * @param {String} cid
     * @returns {Backbone.View|undefined}
     * @api public
     */
    getChild: function getChild(/*String*/cid) {
      var children = lazyGetChildren(this);
      return children[cid];
    },
  };

}();