Micro Framework for Environment View

app/assets/javascripts/d3-components.js

+'use strict';
+
+/**
+ * Provides a declarative structure around interactive D3
+ * applications.
+ *
+ * @module d3-components
+ **/
+
+YUI.add('d3-components', function(Y) {
+  var ns = Y.namespace('d3'),
+      L = Y.Lang,
+      Module = Y.Base.create('Module', Y.Base, [], {
+        /**
+         * @property events
+         * @type {object}
+         **/
+        events: {
+          scene: {},
+          d3: {},
+          yui: {}
+        },
+
+        initializer: function(options) {
+          options = options || {};
+          this.events = options.events ?
+              Y.merge(this.events, options.events) :
+              this.events;
+        }
+      }, {
+        ATTRS: {
+          component: {},
+          container: {getter: function() {
+            return this.get('component').get('container');}}
+        }
+      });
+  ns.Module = Module;
+
+
+  var Component = Y.Base.create('Component', Y.Base, [], {

[thiago, 2012/11/08 13:33:35]

I like this code style. You could the same with the class above. I mean...

var Module = ...

[benjamin.saller, 2012/11/09 13:39:21]

The linter complained that I didn't combine the var decls into one set, I prefer
the other style as well. I'll see if I cna get lint to shut up.

+    /**
+     * @class Component
+     *
+     * Component collections modules implementing various portions

[matthew.scott, 2012/11/08 18:49:46]

Minor - should be 'collects', I think?  Was just confusing.

+     * of an applications functionality in a declarative way. It
+     * is designed to allow both a cleaner separation of concerns
+     * and the ability to reuse the component in different ways.
+     *
+     * Component accomplishes these goals by:
+     *    - Control how events are bound and unbound.
+     *    - Providing patterns for update data cleanly.
+     *    - Providing suggestions around updating the interactive portions

[matthew.scott, 2012/11/08 18:49:46]

Minor - 'updating'

+     *      of the application.
+     *
+     * @constructor
+     **/
+    initializer: function() {
+      this.modules = {};
+      this.events = {};
+
+      // If container is changed, rebind events.
+      // this.after('containerChange', this.bind());

[thiago, 2012/11/08 13:33:35]

You could remove the commented code.

[benjamin.saller, 2012/11/09 13:39:21]

Done.

+    },
+
+    /**
+     * @method addModule
+     * @chainable
+     * @param {Module} a Module class. Will be created and bound to Component
+     * internally.
+     *

[matthew.scott, 2012/11/08 18:49:46]

Minor - Docs don't match method signature.

[benjamin.saller, 2012/11/09 13:39:21]

Done.

+     * Add a Module to this Component. This will bind its events and set up all
+     * needed event subscriptions.
+     * Modules can return three sets of events that will be bound in
+     * different ways
+     *
+     *   - scene: {selector: event-type: handlerName} -> YUI styled event
+     *            delegation
+     *   - d3 {selector: event-type: handlerName} -> Bound using
+     *          specialized d3 event handling
+     *   - yui {event-type: handlerName} -> collection of global and custom
+     *          events the module reacts to.
+     **/
+
+    addModule: function(ModClassOrInstance, options) {
+      options = options || {};

[thiago, 2012/11/08 13:33:35]

I don't like setting a value to one function parameter.

[benjamin.saller, 2012/11/09 13:39:21]

I agree its questionable, questionable but common. Still, I can alter it.

+      var module = ModClassOrInstance;
+      if (!(ModClassOrInstance instanceof Module)) {
+        module = new ModClassOrInstance();
+      }
+      module.setAttrs({component: this,
+        options: options});
+
+                      this.modules[module.name] = module;

[thiago, 2012/11/08 13:33:35]

Funny indentation

[benjamin.saller, 2012/11/09 13:39:21]

fixjsstyle must have done this, fixed.

+
+                      var modEvents = module.events;

[thiago, 2012/11/08 13:33:35]

Usually we have only one var per closure. Maybe you can declare the variables in
the first line and then attribute values to it here.

[benjamin.saller, 2012/11/09 13:39:21]

Done.

+                      this.events[module.name] = Y.clone(modEvents);
+                      this.bind(module.name);

[matthew.scott, 2012/11/08 18:49:46]

Curious about the necessity for not doing Y.clone(module.events); here. 
Clarity?

[benjamin.saller, 2012/11/09 13:39:21]

Its not needed now I think, it was because the Module was returning its real
dict and so there was a Module level instance with shared state being used. This
could leave subscriptions bound to all instances. Module was changed to do the
shallow copy of events in its init method and this was removed.

+                      return this;
+    },
+
+    /**
+     * @method removeModule
+     * @param {String} moduleName Module name to remove.
+     * @chainable
+     **/
+    removeModule: function(moduleName) {
+      this.unbind(moduleName);
+      delete this.events[moduleName];
+      delete this.modules[moduleName];
+      return this;
+    },
+
+    /**
+     * Internal implementation of
+     * binding both
+     * Module.events.scene and
+     * Module.events.yui.
+     **/
+    _bindEvents: function(modName) {
+      var self = this,

[thiago, 2012/11/08 13:33:35]

It seems self is never used.

[benjamin.saller, 2012/11/09 13:39:21]

Done.

+          modEvents = this.events[modName],
+          module = this.modules[modName],
+          owns = Y.Object.owns,
+          phase = 'on',

[matthew.scott, 2012/11/08 18:49:46]

phase is set and carefully handled, but not used.  Is this a future
implementation thing?

[benjamin.saller, 2012/11/09 13:39:21]

It was intended to support before/after events. Of the three types  of events
this isn't handled quite properly anywhere yet. 

The scene events are based on delegate which doesn't seem to support phase
(though I could filter out those things with non-on/after (which maps to 'on'
for DOM Nodes) and call Y.on. We'll see if we need it. 

The d3 Events support before if we pass the capture flag to the handler which
maybe I should allow.

The custom events I will sort to properly support phase as this is the primary
target for this level of control.

+          subscriptions = [],
+          handlers,
+          handler;
+
+      function _bindEvent(name, handler, container, selector, context) {
+        // Adapt between d3 events and YUI delegates.
+        var d3Adaptor = function(evt) {
+          var selection = d3.select(evt.currentTarget.getDOMNode()),
+              d = selection.data()[0];
+          // This is a minor violation (extension)
+          // of the interface, but suits us well.
+          d3.event = evt;
+          return handler.call(
+              evt.currentTarget.getDOMNode(), d, context);
+        };
+
+        subscriptions.push(
+            Y.delegate(name, d3Adaptor, container, selector, context));
+      }
+
+      function _normalizeHandler(handler, module, selector) {
+        if (typeof handler === 'object') {

[thiago, 2012/11/08 13:33:35]

Null is also an object...
https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Operators/typeof

Maybe you could use "Lang" for all the cases here.

[benjamin.saller, 2012/11/09 13:39:21]

Changed it up, thanks.

+          phase = handler.phase || 'on';
+          handler = handler.callback;
+        }
+        if (typeof handler === 'string') {
+          handler = module[handler];
+        }
+        if (!handler) {
+          console.error('No Event handler for', selector, modName);
+          return;

[thiago, 2012/11/08 13:33:35]

If that is an error, you could throw the exception.

[benjamin.saller, 2012/11/09 13:39:21]

Its the sort of error I wanted a developer to notice but not one that I wanted
to stop processing of the entire component. I'm open to debate on these two
errors though.

+        }
+        if (!L.isFunction(handler)) {
+          console.error('Unable to resolve a proper callback for',
+                        selector, handler, modName);
+          return;

[thiago, 2012/11/08 13:33:35]

If that is an error, you could throw the exception.

+        }
+        return handler;
+      }
+
+      this.unbind(modName);
+
+      // Bind 'scene' events
+      if (modEvents.scene) {
+        for (var selector in modEvents.scene) {

[thiago, 2012/11/08 13:33:35]

YUI utility?

[benjamin.saller, 2012/11/09 13:39:21]

Reworked, its passing the tests.

+          if (owns(modEvents.scene, selector)) {
+            handlers = modEvents.scene[selector];
+            for (var name in handlers) {
+              if (owns(handlers, name)) {
+                handler = _normalizeHandler(handlers[name], module, selector);
+                if (!handler) {
+                  continue;
+                }
+                _bindEvent(name, handler,
+                           this.get('container'), selector, this);
+              }
+            }
+          }
+        }
+      }
+
+      // Bind 'yui' custom/global subscriptions
+      // yui: {str: str_or_function}
+      // TODO {str: str/func/obj}
+      //       where object includes phase (before, on, after)

[matthew.scott, 2012/11/08 18:49:46]

From above, assuming this is the future use of phase?

+      if (modEvents.yui) {
+        var resolvedHandler = {};

[thiago, 2012/11/08 13:33:35]

var declarations should be the first statement in the function body. I dont know
why lint didn't catch this.
http://javascript.crockford.com/code.html

[benjamin.saller, 2012/11/09 13:39:21]

Moved

+
+        // Resolve any 'string' handlers to methods on module.
+        Y.each(modEvents.yui, function(handler, name) {
+          handler = _normalizeHandler(handler, module);
+          if (!handler) {
+            return;
+          }
+          resolvedHandler[name] = handler;
+        }, this);
+        // Bind resolved event handlers as a group.
+        subscriptions.push(Y.on(resolvedHandler));
+      }
+      return subscriptions;
+    },
+
+    /**
+     * @method bind
+     *
+     * Internal. Called automatically by addModule.
+     **/
+    bind: function(moduleName) {
+      var eventSet = this.events;
+      if (moduleName) {
+        var filtered = {};

[thiago, 2012/11/08 13:33:35]

The blocks of scope in js are crazy. The filtered variable is available for use
outside this if block. Maybe you could move it to the top of the method to make
it clear.

[benjamin.saller, 2012/11/09 13:39:21]

The structure here was the result of fighting with the linter from the original
form. I'll clean this up.

+        filtered[moduleName] = eventSet[moduleName];
+        eventSet = filtered;
+      }
+
+      Y.each(Y.Object.keys(eventSet), function _bind(name) {

[thiago, 2012/11/08 13:33:35]

Do you need to name this function ("_bind")?

[benjamin.saller, 2012/11/09 13:39:21]

Anonymous now.

+        this.events[name].subscriptions = this._bindEvents(name);
+      }, this);
+      return this;
+    },
+
+    /**
+     * Specialized handling of events only found in d3.
+     * This is again an internal implementation detail.
+     *
+     * Its worth noting that d3 events don't use a delegate pattern
+     * and thus must be bound to nodes present in a selection.
+     * For this reason binding d3 events happens after render cycles.
+     *
+     * @method _bindD3Events
+     * @param {String} modName Module name.
+     **/
+    _bindD3Events: function(modName) {
+      // Walk each selector for a given module 'name', doing a
+      // d3 selection and an 'on' binding.
+      var modEvents = this.events[modName];
+
+      if (!modEvents || modEvents.d3 === undefined) {

[thiago, 2012/11/08 13:33:35]

If modEvents.d3 is null you will have a false negative. Is that what you want?
If not, you could change it to...

if (!modEvents || !modEvents.d3) 

+        return;
+      }
+
+      modEvents = modEvents.d3;
+      var module = this.modules[modName],

[thiago, 2012/11/08 13:33:35]

Usually we have one "var" per closure.

+          owns = Y.Object.owns;
+
+      var selector, kind, handler,
+          handlers, name;
+
+      for (selector in modEvents) {

[thiago, 2012/11/08 13:33:35]

What about the yui utility classes? You could use Y.Object.keys, no?

+        if (owns(modEvents, selector)) {
+          handlers = modEvents[selector];
+          for (name in handlers) {
+            if (owns(handlers, name)) {
+              handler = handlers[name];
+              if (typeof handler === 'string') {
+                handler = module[handler];
+              }
+              d3.selectAll(selector).on(name, handler);
+            }
+          }
+        }
+      }
+    },
+
+    /**
+     * @method _unbindD3Events
+     *
+     * Internal Detail. Called by unbind automatically.
+     * D3 events follow a 'slot' like system. Setting the
+     * event to null unbinds existing handlers.
+     **/
+    _unbindD3Events: function(modName) {
+      var modEvents = this.events[modName];
+
+      if (!modEvents || !modEvents.d3) {
+        return;
+      }
+      modEvents = modEvents.d3;
+      var module = this.modules[modName],
+          owns = Y.Object.owns;
+
+      var selector, kind, handler,
+          handlers, name;
+
+      for (selector in modEvents) {
+        if (owns(modEvents, selector)) {
+          handlers = modEvents[selector];
+          for (name in handlers) {
+            if (owns(handlers, name)) {
+              d3.selectAll(selector).on(name, null);

[thiago, 2012/11/08 13:33:35]

This method is really similar to the method above. Maybe you could create a
common method with a different handler for this inner "if"....

function handleD3Events(modName, handler) {
.
.
.
}

[benjamin.saller, 2012/11/09 13:39:21]

They are similar but are called at different times with different APIs (d3
events are handled post render). These methods are a bit more compact after
switching to Y.each style iteration as well. Hopefully that makes people more
comfortable.

+            }
+          }
+        }
+      }
+    },
+
+    /**
+     * @method unbind
+     * Internal. Called automatically by removeModule.
+     **/
+    unbind: function(moduleName) {
+      var eventSet = this.events;
+      function _unbind(modEvents) {
+        Y.each(modEvents.subscriptions, function(handler) {
+          if (handler) {
+            handler.detach();
+          }
+        });
+        delete modEvents.subscriptions;
+      }
+
+      if (moduleName) {
+        var filtered = {};

[thiago, 2012/11/08 13:33:35]

One var declaration per closure.

[benjamin.saller, 2012/11/09 13:39:21]

Done.

+        filtered[moduleName] = eventSet[moduleName];
+        eventSet = filtered;
+      }
+      Y.each(Y.Object.values(eventSet), _unbind, this);
+      // Remove any d3 subscriptions as well.
+      this._unbindD3Events();
+
+      return this;
+    },
+
+    /**
+     * @method render
+     * @chainable
+     *
+     * Render each module bound to the canvas
+     */
+    render: function() {
+      var self = this;

[thiago, 2012/11/08 13:33:35]

You dont need 'self'. You pass the 'this' object as parameter to the 'Render
Modules' line below.

[benjamin.saller, 2012/11/09 13:39:21]

The linter actually complained that 'this.method' to the containing scope
'might' be a violation of 'strict', thus the change.

+      function renderAndBind(module, name) {
+        if (module && module.render) {
+          module.render();
+        }
+        self._bindD3Events(name);
+      }
+
+      // If the container isn't bound to the DOM
+      // do so now.
+      this.attachContainer();
+      // Render modules.
+      Y.each(this.modules, renderAndBind, this);
+      return this;
+    },
+
+    /**
+     * @method attachContainer
+     * @chainable
+     *
+     * Called by render, conditionally attach container to the DOM if
+     * it isn't already. The framework calls this before module
+     * rendering so that d3 Events will have attached DOM elements. If
+     * your application doesn't need this behavior feel free to override.
+     **/
+    attachContainer: function() {
+      var container = this.get('container');
+      if (container && !container.inDoc()) {
+        Y.one('body').append(container);
+      }
+      return this;
+    },
+
+    /**
+     * @method detachContainer
+     *
+     * Remove container from DOM returning container. This
+     * is explicitly not chainable.
+     **/
+    detachContainer: function() {
+      var container = this.get('container');
+      if (container.inDoc()) {
+        container.remove();
+      }
+      return container;
+    },
+
+    /**
+     *
+     * @method update
+     * @chainable
+     *
+     * Update the data for each module
+     * see also the dataBinding event hookup
+     */
+    update: function() {
+      Y.each(Y.Object.values(this.modules), function(mod) {
+        mod.update();
+      });
+      return this;
+    }
+  }, {
+    ATTRS: {
+      container: {}
+    }
+
+  });
+  ns.Component = Component;
+}, '0.1', {
+  'requires': ['d3',
+    'base',
+    'array-extras',
+    'event']});