web/gui/src/main/webapp/onos2.js - onos - Gitiles

 /*
  * Copyright 2014 Open Networking Laboratory
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 /*
  ONOS GUI -- Base Framework

  @author Simon Hunt
  */

 (function ($) {
     'use strict';
     var tsI = new Date().getTime(),         // initialize time stamp
         tsB,                                // build time stamp
         mastHeight = 36,                    // see mast2.css
         defaultVid = 'sample';


     // attach our main function to the jQuery object
     $.onos = function (options) {
         var uiApi,
             viewApi,
             navApi,
             libApi;

         var defaultOptions = {
             trace: false,
             theme: 'light',
             startVid: defaultVid
         };

         // compute runtime settings
         var settings = $.extend({}, defaultOptions, options);

         // set the selected theme
         d3.select('body').classed(settings.theme, true);

         // internal state
         var views = {},
             current = {
                 view: null,
                 ctx: '',
                 flags: {},
                 theme: settings.theme
             },
             built = false,
             errorCount = 0,
             keyHandler = {
                 globalKeys: {},
                 maskedKeys: {},
                 viewKeys: {},
                 viewFn: null
             },
             alerts = {
                 open: false,
                 count: 0
             };

         // DOM elements etc.
         var $view,
             $mastRadio;


         function whatKey(code) {
             switch (code) {
                 case 13: return 'enter';
                 case 16: return 'shift';
                 case 17: return 'ctrl';
                 case 18: return 'alt';
                 case 27: return 'esc';
                 case 32: return 'space';
                 case 37: return 'leftArrow';
                 case 38: return 'upArrow';
                 case 39: return 'rightArrow';
                 case 40: return 'downArrow';
                 case 91: return 'cmdLeft';
                 case 93: return 'cmdRight';
                 default:
                     if ((code >= 48 && code <= 57) ||
                         (code >= 65 && code <= 90)) {
                         return String.fromCharCode(code);
                     } else if (code >= 112 && code <= 123) {
                         return 'F' + (code - 111);
                     }
                     return '.';
             }
         }


         // ..........................................................
         // Internal functions

         // throw an error
         function throwError(msg) {
             // separate function, as we might add tracing here too, later
             throw new Error(msg);
         }

         function doError(msg) {
             errorCount++;
             console.error(msg);
             doAlert(msg);
         }

         function trace(msg) {
             if (settings.trace) {
                 console.log(msg);
             }
         }

         function traceFn(fn, params) {
             if (settings.trace) {
                 console.log('*FN* ' + fn + '(...): ' + params);
             }
         }

         // hash navigation
         function hash() {
             var hash = window.location.hash,
                 redo = false,
                 view,
                 t;

             traceFn('hash', hash);

             if (!hash) {
                 hash = settings.startVid;
                 redo = true;
             }

             t = parseHash(hash);
             if (!t || !t.vid) {
                 doError('Unable to parse target hash: "' + hash + '"');
             }

             view = views[t.vid];
             if (!view) {
                 doError('No view defined with id: ' + t.vid);
             }

             if (redo) {
                 window.location.hash = makeHash(t);
                 // the above will result in a hashchange event, invoking
                 // this function again
             } else {
                 // hash was not modified... navigate to where we need to be
                 navigate(hash, view, t);
             }
         }

         function parseHash(s) {
             // extract navigation coordinates from the supplied string
             // "vid,ctx?flag1,flag2" --> { vid:vid, ctx:ctx, flags:{...} }
             traceFn('parseHash', s);

             // look for use of flags, first
             var vidctx,
                 vid,
                 ctx,
                 flags,
                 flagMap,
                 m;

             // RE that includes flags ('?flag1,flag2')
             m = /^[#]{0,1}(.+)\?(.+)$/.exec(s);
             if (m) {
                 vidctx = m[1];
                 flags = m[2];
                 flagMap = {};
             } else {
                 // no flags
                 m = /^[#]{0,1}((.+)(,.+)*)$/.exec(s);
                 if (m) {
                     vidctx = m[1];
                 } else {
                     // bad hash
                     return null;
                 }
             }

             vidctx = vidctx.split(',');
             vid = vidctx[0];
             ctx = vidctx[1];
             if (flags) {
                 flags.split(',').forEach(function (f) {
                     flagMap[f.trim()] = true;
                 });
             }

             return {
                 vid: vid.trim(),
                 ctx: ctx ? ctx.trim() : '',
                 flags: flagMap
             };

         }

         function makeHash(t, ctx, flags) {
             traceFn('makeHash');
             // make a hash string from the given navigation coordinates,
             // and optional flags map.
             // if t is not an object, then it is a vid
             var h = t,
                 c = ctx || '',
                 f = $.isPlainObject(flags) ? flags : null;

             if ($.isPlainObject(t)) {
                 h = t.vid;
                 c = t.ctx || '';
                 f = t.flags || null;
             }

             if (c) {
                 h += ',' + c;
             }
             if (f) {
                 h += '?' + d3.map(f).keys().join(',');
             }
             trace('hash = "' + h + '"');
             return h;
         }

         function navigate(hash, view, t) {
             traceFn('navigate', view.vid);
             // closePanes()     // flyouts etc.
             // updateNav()      // accordion / selected nav item etc.
             createView(view);
             setView(view, hash, t);
         }

         function reportBuildErrors() {
             traceFn('reportBuildErrors');
             // TODO: validate registered views / nav-item linkage etc.
             console.log('(no build errors)');
         }

         // returns the reference if it is a function, null otherwise
         function isF(f) {
             return $.isFunction(f) ? f : null;
         }

         // ..........................................................
         // View life-cycle functions

         function setViewDimensions(sel) {
             var w = window.innerWidth,
                 h = window.innerHeight - mastHeight;
             sel.each(function () {
                 $(this)
                     .css('width', w + 'px')
                     .css('height', h + 'px')
             });
         }

         function createView(view) {
             var $d;

             // lazy initialization of the view
             if (view && !view.$div) {
                 trace('creating view for ' + view.vid);
                 $d = $view.append('div')
                         .attr({
                             id: view.vid,
                             class: 'onosView'
                          });
                 setViewDimensions($d);
                 view.$div = $d;   // cache a reference to the D3 selection
             }
         }

         function setView(view, hash, t) {
             traceFn('setView', view.vid);
             // set the specified view as current, while invoking the
             // appropriate life-cycle callbacks

             // first, we'll start by closing the alerts pane, if open
             closeAlerts();

             // if there is a current view, and it is not the same as
             // the incoming view, then unload it...
             if (current.view && (current.view.vid !== view.vid)) {
                 current.view.unload();

                 // detach radio buttons, key handlers, etc.
                 $('#mastRadio').children().detach();
                 keyHandler.viewKeys = {};
                 keyHandler.viewFn = null;
             }

             // cache new view and context
             current.view = view;
             current.ctx = t.ctx || '';
             current.flags = t.flags || {};

             // preload is called only once, after the view is in the DOM
             if (!view.preloaded) {
                 view.preload(current.ctx, current.flags);
                 view.preloaded = true;
             }

             // clear the view of stale data
             view.reset();

             // load the view
             view.load(current.ctx, current.flags);
         }

         // generate 'unique' id by prefixing view id
         function makeUid(view, id) {
             return view.vid + '-' + id;
         }

         // restore id by removing view id prefix
         function unmakeUid(view, uid) {
             var re = new RegExp('^' + view.vid + '-');
             return uid.replace(re, '');
         }

         function setRadioButtons(vid, btnSet) {
             var view = views[vid],
                 btnG;

             // lazily create the buttons...
             if (!(btnG = view.radioButtons)) {
                 btnG = d3.select(document.createElement('div'));
                 btnG.buttonDef = {};

                 btnSet.forEach(function (btn, i) {
                     var bid = btn.id || 'b' + i,
                         txt = btn.text || 'Button #' + i,
                         uid = makeUid(view, bid),
                         button = btnG.append('span')
                         .attr({
                             id: uid,
                             class: 'radio'
                         })
                         .text(txt);

                     btnG.buttonDef[uid] = btn;

                     if (i === 0) {
                         button.classed('active', true);
                     }
                 });

                 btnG.selectAll('span')
                     .on('click', function (d) {
                         var button = d3.select(this),
                             uid = button.attr('id'),
                             btn = btnG.buttonDef[uid],
                             act = button.classed('active');

                         if (!act) {
                             btnG.selectAll('span').classed('active', false);
                             button.classed('active', true);
                             if (isF(btn.cb)) {
                                 btn.cb(view.token(), btn);
                             }
                         }
                     });

                 view.radioButtons = btnG;
             }

             // attach the buttons to the masthead
             $mastRadio.node().appendChild(btnG.node());
         }

         function setupGlobalKeys() {
             keyHandler.globalKeys = {
                 esc: escapeKey,
                 T: toggleTheme
             };
             // Masked keys are global key handlers that always return true.
             // That is, the view will never see the event for that key.
             keyHandler.maskedKeys = {
                 T: true
             };
         }

         function escapeKey(view, key, code, ev) {
             if (alerts.open) {
                 closeAlerts();
                 return true;
             }
             return false;
         }

         function toggleTheme(view, key, code, ev) {
             var body = d3.select('body');
             current.theme = (current.theme === 'light') ? 'dark' : 'light';
             body.classed('light dark', false);
             body.classed(current.theme, true);
             return true;
         }

         function setKeyBindings(keyArg) {
             var viewKeys,
                 masked = [];

             if ($.isFunction(keyArg)) {
                 // set general key handler callback
                 keyHandler.viewFn = keyArg;
             } else {
                 // set specific key filter map
                 viewKeys = d3.map(keyArg).keys();
                 viewKeys.forEach(function (key) {
                     if (keyHandler.maskedKeys[key]) {
                         masked.push('  Key "' + key + '" is reserved');
                     }
                 });

                 if (masked.length) {
                     doAlert('WARNING...\n\nsetKeys():\n' + masked.join('\n'));
                 }
                 keyHandler.viewKeys = keyArg;
             }
         }

         function keyIn() {
             var event = d3.event,
                 keyCode = event.keyCode,
                 key = whatKey(keyCode),
                 gcb = isF(keyHandler.globalKeys[key]),
                 vcb = isF(keyHandler.viewKeys[key]) || isF(keyHandler.viewFn);

             // global callback?
             if (gcb && gcb(current.view.token(), key, keyCode, event)) {
                 // if the event was 'handled', we are done
                 return;
             }
             // otherwise, let the view callback have a shot
             if (vcb) {
                 vcb(current.view.token(), key, keyCode, event);
             }
         }

         function createAlerts() {
             var al = d3.select('#alerts')
                 .style('display', 'block');
             al.append('span')
                 .attr('class', 'close')
                 .text('X')
                 .on('click', closeAlerts);
             al.append('pre');
             al.append('p').attr('class', 'footnote')
                 .text('Press ESCAPE to close');
             alerts.open = true;
             alerts.count = 0;
         }

         function closeAlerts() {
             d3.select('#alerts')
                 .style('display', 'none')
                 .html('');
             alerts.open = false;
         }

         function addAlert(msg) {
             var lines,
                 oldContent;

             if (alerts.count) {
                 oldContent = d3.select('#alerts pre').html();
             }

             lines = msg.split('\n');
             lines[0] += '  '; // spacing so we don't crowd 'X'
             lines = lines.join('\n');

             if (oldContent) {
                 lines += '\n----\n' + oldContent;
             }

             d3.select('#alerts pre').html(lines);
             alerts.count++;
         }

         function doAlert(msg) {
             if (!alerts.open) {
                 createAlerts();
             }
             addAlert(msg);
         }

         function resize(e) {
             d3.selectAll('.onosView').call(setViewDimensions);
             // allow current view to react to resize event...
             if (current.view) {
                 current.view.resize(current.ctx, current.flags);
             }
         }

         // ..........................................................
         // View class
         //   Captures state information about a view.

         // Constructor
         //      vid : view id
         //      nid : id of associated nav-item (optional)
         //      cb  : callbacks (preload, reset, load, unload, resize, error)
         function View(vid) {
             var av = 'addView(): ',
                 args = Array.prototype.slice.call(arguments),
                 nid,
                 cb;

             args.shift();   // first arg is always vid
             if (typeof args[0] === 'string') {  // nid specified
                 nid = args.shift();
             }
             cb = args.shift();

             this.vid = vid;

             if (validateViewArgs(vid)) {
                 this.nid = nid;     // explicit navitem id (can be null)
                 this.cb = $.isPlainObject(cb) ? cb : {};    // callbacks
                 this.$div = null;               // view not yet added to DOM
                 this.radioButtons = null;       // no radio buttons yet
                 this.ok = true;                 // valid view
             }
         }

         function validateViewArgs(vid) {
             var av = "ui.addView(...): ",
                 ok = false;
             if (typeof vid !== 'string' || !vid) {
                 doError(av + 'vid required');
             } else if (views[vid]) {
                 doError(av + 'View ID "' + vid + '" already exists');
             } else {
                 ok = true;
             }
             return ok;
         }

         var viewInstanceMethods = {
             token: function () {
                 return {
                     // attributes
                     vid: this.vid,
                     nid: this.nid,
                     $div: this.$div,

                     // functions
                     width: this.width,
                     height: this.height,
                     uid: this.uid,
                     setRadio: this.setRadio,
                     setKeys: this.setKeys,
                     dataLoadError: this.dataLoadError,
                     alert: this.alert
                 }
             },

             preload: function (ctx, flags) {
                 var c = ctx || '',
                     fn = isF(this.cb.preload);
                 traceFn('View.preload', this.vid + ', ' + c);
                 if (fn) {
                     trace('PRELOAD cb for ' + this.vid);
                     fn(this.token(), c, flags);
                 }
             },

             reset: function () {
                 var fn = isF(this.cb.reset);
                 traceFn('View.reset', this.vid);
                 if (fn) {
                     trace('RESET cb for ' + this.vid);
                     fn(this.token());
                 } else if (this.cb.reset === true) {
                     // boolean true signifies "clear view"
                     trace('  [true] cleaing view...');
                     viewApi.empty();
                 }
             },

             load: function (ctx, flags) {
                 var c = ctx || '',
                     fn = isF(this.cb.load);
                 traceFn('View.load', this.vid + ', ' + c);
                 this.$div.classed('currentView', true);
                 if (fn) {
                     trace('LOAD cb for ' + this.vid);
                     fn(this.token(), c, flags);
                 }
             },

             unload: function () {
                 var fn = isF(this.cb.unload);
                 traceFn('View.unload', this.vid);
                 this.$div.classed('currentView', false);
                 if (fn) {
                     trace('UNLOAD cb for ' + this.vid);
                     fn(this.token());
                 }
             },

             resize: function (ctx, flags) {
                 var c = ctx || '',
                     fn = isF(this.cb.resize),
                     w = this.width(),
                     h = this.height();
                 traceFn('View.resize', this.vid + '/' + c +
                         ' [' + w + 'x' + h + ']');
                 if (fn) {
                     trace('RESIZE cb for ' + this.vid);
                     fn(this.token(), c, flags);
                 }
             },

             error: function (ctx) {
                 var c = ctx || '',
                     fn = isF(this.cb.error);
                 traceFn('View.error', this.vid + ', ' + c);
                 if (fn) {
                     trace('ERROR cb for ' + this.vid);
                     fn(this.token(), c);
                 }
             },

             width: function () {
                 return $(this.$div.node()).width();
             },

             height: function () {
                 return $(this.$div.node()).height();
             },

             setRadio: function (btnSet) {
                 setRadioButtons(this.vid, btnSet);
             },

             setKeys: function (keyArg) {
                 setKeyBindings(keyArg);
             },

             uid: function (id) {
                 return makeUid(this, id);
             },

             // TODO : implement custom dialogs

             // Consider enhancing alert mechanism to handle multiples
             // as individually closable.
             alert: function (msg) {
                 doAlert(msg);
             },

             dataLoadError: function (err, url) {
                 var msg = 'Data Load Error\n\n' +
                     err.status + ' -- ' + err.statusText + '\n\n' +
                     'relative-url: "' + url + '"\n\n' +
                     'complete-url: "' + err.responseURL + '"';
                 this.alert(msg);
             }

             // TODO: consider schedule, clearTimer, etc.
         };

         // attach instance methods to the view prototype
         $.extend(View.prototype, viewInstanceMethods);

         // ..........................................................
         // UI API

         uiApi = {
             addLib: function (libName, api) {
                 // TODO: validation of args
                 libApi[libName] = api;
             },

             // TODO: it remains to be seen whether we keep this style of docs
             /** @api ui addView( vid, nid, cb )
              * Adds a view to the UI.
              * <p>
              * Views are loaded/unloaded into the view content pane at
              * appropriate times, by the navigation framework. This method
              * adds a view to the UI and returns a token object representing
              * the view. A view's token is always passed as the first
              * argument to each of the view's life-cycle callback functions.
              * <p>
              * Note that if the view is directly referenced by a nav-item,
              * or in a group of views with one of those views referenced by
              * a nav-item, then the <i>nid</i> argument can be omitted as
              * the framework can infer it.
              * <p>
              * <i>cb</i> is a plain object containing callback functions:
              * "preload", "reset", "load", "unload", "resize", "error".
              * <pre>
              *     function myLoad(view, ctx) { ... }
              *     ...
              *     // short form...
              *     onos.ui.addView('viewId', {
              *         load: myLoad
              *     });
              * </pre>
              *
              * @param vid (string) [*] view ID (a unique DOM element id)
              * @param nid (string) nav-item ID (a unique DOM element id)
              * @param cb (object) [*] callbacks object
              * @return the view token
              */
             addView: function (vid, nid, cb) {
                 traceFn('addView', vid);
                 var view = new View(vid, nid, cb),
                     token;
                 if (view.ok) {
                     views[vid] = view;
                     token = view.token();
                 } else {
                     token = { vid: view.vid, bad: true };
                 }
                 return token;
             }
         };

         // ..........................................................
         // View API

         viewApi = {
             /** @api view empty( )
              * Empties the current view.
              * <p>
              * More specifically, removes all DOM elements from the
              * current view's display div.
              */
             empty: function () {
                 if (!current.view) {
                     return;
                 }
                 current.view.$div.html('');
             }
         };

         // ..........................................................
         // Nav API
         navApi = {

         };

         // ..........................................................
         // Library API
         libApi = {

         };

         // ..........................................................
         // Exported API

         // function to be called from index.html to build the ONOS UI
         function buildOnosUi() {
             tsB = new Date().getTime();
             tsI = tsB - tsI; // initialization duration

             console.log('ONOS UI initialized in ' + tsI + 'ms');

             if (built) {
                 throwError("ONOS UI already built!");
             }
             built = true;

             $view = d3.select('#view');
             $mastRadio = d3.select('#mastRadio');

             $(window).on('hashchange', hash);
             $(window).on('resize', resize);

             d3.select('body').on('keydown', keyIn);
             setupGlobalKeys();

             // Invoke hashchange callback to navigate to content
             // indicated by the window location hash.
             hash();

             // If there were any build errors, report them
             reportBuildErrors();
         }

         // export the api and build-UI function
         return {
             ui: uiApi,
             lib: libApi,
             //view: viewApi,
             nav: navApi,
             buildUi: buildOnosUi
         };
     };

 }(jQuery));
	/*
	* Copyright 2014 Open Networking Laboratory
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	/*
	ONOS GUI -- Base Framework

	@author Simon Hunt
	*/

	(function ($) {
	'use strict';
	var tsI = new Date().getTime(), // initialize time stamp
	tsB, // build time stamp
	mastHeight = 36, // see mast2.css
	defaultVid = 'sample';


	// attach our main function to the jQuery object
	$.onos = function (options) {
	var uiApi,
	viewApi,
	navApi,
	libApi;

	var defaultOptions = {
	trace: false,
	theme: 'light',
	startVid: defaultVid
	};

	// compute runtime settings
	var settings = $.extend({}, defaultOptions, options);

	// set the selected theme
	d3.select('body').classed(settings.theme, true);

	// internal state
	var views = {},
	current = {
	view: null,
	ctx: '',
	flags: {},
	theme: settings.theme
	},
	built = false,
	errorCount = 0,
	keyHandler = {
	globalKeys: {},
	maskedKeys: {},
	viewKeys: {},
	viewFn: null
	},
	alerts = {
	open: false,
	count: 0
	};

	// DOM elements etc.
	var $view,
	$mastRadio;


	function whatKey(code) {
	switch (code) {
	case 13: return 'enter';
	case 16: return 'shift';
	case 17: return 'ctrl';
	case 18: return 'alt';
	case 27: return 'esc';
	case 32: return 'space';
	case 37: return 'leftArrow';
	case 38: return 'upArrow';
	case 39: return 'rightArrow';
	case 40: return 'downArrow';
	case 91: return 'cmdLeft';
	case 93: return 'cmdRight';
	default:
	if ((code >= 48 && code <= 57) \|\|
	(code >= 65 && code <= 90)) {
	return String.fromCharCode(code);
	} else if (code >= 112 && code <= 123) {
	return 'F' + (code - 111);
	}
	return '.';
	}
	}


	// ..........................................................
	// Internal functions

	// throw an error
	function throwError(msg) {
	// separate function, as we might add tracing here too, later
	throw new Error(msg);
	}

	function doError(msg) {
	errorCount++;
	console.error(msg);
	doAlert(msg);
	}

	function trace(msg) {
	if (settings.trace) {
	console.log(msg);
	}
	}

	function traceFn(fn, params) {
	if (settings.trace) {
	console.log('FN ' + fn + '(...): ' + params);
	}
	}

	// hash navigation
	function hash() {
	var hash = window.location.hash,
	redo = false,
	view,
	t;

	traceFn('hash', hash);

	if (!hash) {
	hash = settings.startVid;
	redo = true;
	}

	t = parseHash(hash);
	if (!t \|\| !t.vid) {
	doError('Unable to parse target hash: "' + hash + '"');
	}

	view = views[t.vid];
	if (!view) {
	doError('No view defined with id: ' + t.vid);
	}

	if (redo) {
	window.location.hash = makeHash(t);
	// the above will result in a hashchange event, invoking
	// this function again
	} else {
	// hash was not modified... navigate to where we need to be
	navigate(hash, view, t);
	}
	}

	function parseHash(s) {
	// extract navigation coordinates from the supplied string
	// "vid,ctx?flag1,flag2" --> { vid:vid, ctx:ctx, flags:{...} }
	traceFn('parseHash', s);

	// look for use of flags, first
	var vidctx,
	vid,
	ctx,
	flags,
	flagMap,
	m;

	// RE that includes flags ('?flag1,flag2')
	m = /^[#]{0,1}(.+)\?(.+)$/.exec(s);
	if (m) {
	vidctx = m[1];
	flags = m[2];
	flagMap = {};
	} else {
	// no flags
	m = /^[#]{0,1}((.+)(,.+)*)$/.exec(s);
	if (m) {
	vidctx = m[1];
	} else {
	// bad hash
	return null;
	}
	}

	vidctx = vidctx.split(',');
	vid = vidctx[0];
	ctx = vidctx[1];
	if (flags) {
	flags.split(',').forEach(function (f) {
	flagMap[f.trim()] = true;
	});
	}

	return {
	vid: vid.trim(),
	ctx: ctx ? ctx.trim() : '',
	flags: flagMap
	};

	}

	function makeHash(t, ctx, flags) {
	traceFn('makeHash');
	// make a hash string from the given navigation coordinates,
	// and optional flags map.
	// if t is not an object, then it is a vid
	var h = t,
	c = ctx \|\| '',
	f = $.isPlainObject(flags) ? flags : null;

	if ($.isPlainObject(t)) {
	h = t.vid;
	c = t.ctx \|\| '';
	f = t.flags \|\| null;
	}

	if (c) {
	h += ',' + c;
	}
	if (f) {
	h += '?' + d3.map(f).keys().join(',');
	}
	trace('hash = "' + h + '"');
	return h;
	}

	function navigate(hash, view, t) {
	traceFn('navigate', view.vid);
	// closePanes() // flyouts etc.
	// updateNav() // accordion / selected nav item etc.
	createView(view);
	setView(view, hash, t);
	}

	function reportBuildErrors() {
	traceFn('reportBuildErrors');
	// TODO: validate registered views / nav-item linkage etc.
	console.log('(no build errors)');
	}

	// returns the reference if it is a function, null otherwise
	function isF(f) {
	return $.isFunction(f) ? f : null;
	}

	// ..........................................................
	// View life-cycle functions

	function setViewDimensions(sel) {
	var w = window.innerWidth,
	h = window.innerHeight - mastHeight;
	sel.each(function () {
	$(this)
	.css('width', w + 'px')
	.css('height', h + 'px')
	});
	}

	function createView(view) {
	var $d;

	// lazy initialization of the view
	if (view && !view.$div) {
	trace('creating view for ' + view.vid);
	$d = $view.append('div')
	.attr({
	id: view.vid,
	class: 'onosView'
	});
	setViewDimensions($d);
	view.$div = $d; // cache a reference to the D3 selection
	}
	}

	function setView(view, hash, t) {
	traceFn('setView', view.vid);
	// set the specified view as current, while invoking the
	// appropriate life-cycle callbacks

	// first, we'll start by closing the alerts pane, if open
	closeAlerts();

	// if there is a current view, and it is not the same as
	// the incoming view, then unload it...
	if (current.view && (current.view.vid !== view.vid)) {
	current.view.unload();

	// detach radio buttons, key handlers, etc.
	$('#mastRadio').children().detach();
	keyHandler.viewKeys = {};
	keyHandler.viewFn = null;
	}

	// cache new view and context
	current.view = view;
	current.ctx = t.ctx \|\| '';
	current.flags = t.flags \|\| {};

	// preload is called only once, after the view is in the DOM
	if (!view.preloaded) {
	view.preload(current.ctx, current.flags);
	view.preloaded = true;
	}

	// clear the view of stale data
	view.reset();

	// load the view
	view.load(current.ctx, current.flags);
	}

	// generate 'unique' id by prefixing view id
	function makeUid(view, id) {
	return view.vid + '-' + id;
	}

	// restore id by removing view id prefix
	function unmakeUid(view, uid) {
	var re = new RegExp('^' + view.vid + '-');
	return uid.replace(re, '');
	}

	function setRadioButtons(vid, btnSet) {
	var view = views[vid],
	btnG;

	// lazily create the buttons...
	if (!(btnG = view.radioButtons)) {
	btnG = d3.select(document.createElement('div'));
	btnG.buttonDef = {};

	btnSet.forEach(function (btn, i) {
	var bid = btn.id \|\| 'b' + i,
	txt = btn.text \|\| 'Button #' + i,
	uid = makeUid(view, bid),
	button = btnG.append('span')
	.attr({
	id: uid,
	class: 'radio'
	})
	.text(txt);

	btnG.buttonDef[uid] = btn;

	if (i === 0) {
	button.classed('active', true);
	}
	});

	btnG.selectAll('span')
	.on('click', function (d) {
	var button = d3.select(this),
	uid = button.attr('id'),
	btn = btnG.buttonDef[uid],
	act = button.classed('active');

	if (!act) {
	btnG.selectAll('span').classed('active', false);
	button.classed('active', true);
	if (isF(btn.cb)) {
	btn.cb(view.token(), btn);
	}
	}
	});

	view.radioButtons = btnG;
	}

	// attach the buttons to the masthead
	$mastRadio.node().appendChild(btnG.node());
	}

	function setupGlobalKeys() {
	keyHandler.globalKeys = {
	esc: escapeKey,
	T: toggleTheme
	};
	// Masked keys are global key handlers that always return true.
	// That is, the view will never see the event for that key.
	keyHandler.maskedKeys = {
	T: true
	};
	}

	function escapeKey(view, key, code, ev) {
	if (alerts.open) {
	closeAlerts();
	return true;
	}
	return false;
	}

	function toggleTheme(view, key, code, ev) {
	var body = d3.select('body');
	current.theme = (current.theme === 'light') ? 'dark' : 'light';
	body.classed('light dark', false);
	body.classed(current.theme, true);
	return true;
	}

	function setKeyBindings(keyArg) {
	var viewKeys,
	masked = [];

	if ($.isFunction(keyArg)) {
	// set general key handler callback
	keyHandler.viewFn = keyArg;
	} else {
	// set specific key filter map
	viewKeys = d3.map(keyArg).keys();
	viewKeys.forEach(function (key) {
	if (keyHandler.maskedKeys[key]) {
	masked.push(' Key "' + key + '" is reserved');
	}
	});

	if (masked.length) {
	doAlert('WARNING...\n\nsetKeys():\n' + masked.join('\n'));
	}
	keyHandler.viewKeys = keyArg;
	}
	}

	function keyIn() {
	var event = d3.event,
	keyCode = event.keyCode,
	key = whatKey(keyCode),
	gcb = isF(keyHandler.globalKeys[key]),
	vcb = isF(keyHandler.viewKeys[key]) \|\| isF(keyHandler.viewFn);

	// global callback?
	if (gcb && gcb(current.view.token(), key, keyCode, event)) {
	// if the event was 'handled', we are done
	return;
	}
	// otherwise, let the view callback have a shot
	if (vcb) {
	vcb(current.view.token(), key, keyCode, event);
	}
	}

	function createAlerts() {
	var al = d3.select('#alerts')
	.style('display', 'block');
	al.append('span')
	.attr('class', 'close')
	.text('X')
	.on('click', closeAlerts);
	al.append('pre');
	al.append('p').attr('class', 'footnote')
	.text('Press ESCAPE to close');
	alerts.open = true;
	alerts.count = 0;
	}

	function closeAlerts() {
	d3.select('#alerts')
	.style('display', 'none')
	.html('');
	alerts.open = false;
	}

	function addAlert(msg) {
	var lines,
	oldContent;

	if (alerts.count) {
	oldContent = d3.select('#alerts pre').html();
	}

	lines = msg.split('\n');
	lines[0] += ' '; // spacing so we don't crowd 'X'
	lines = lines.join('\n');

	if (oldContent) {
	lines += '\n----\n' + oldContent;
	}

	d3.select('#alerts pre').html(lines);
	alerts.count++;
	}

	function doAlert(msg) {
	if (!alerts.open) {
	createAlerts();
	}
	addAlert(msg);
	}

	function resize(e) {
	d3.selectAll('.onosView').call(setViewDimensions);
	// allow current view to react to resize event...
	if (current.view) {
	current.view.resize(current.ctx, current.flags);
	}
	}

	// ..........................................................
	// View class
	// Captures state information about a view.

	// Constructor
	// vid : view id
	// nid : id of associated nav-item (optional)
	// cb : callbacks (preload, reset, load, unload, resize, error)
	function View(vid) {
	var av = 'addView(): ',
	args = Array.prototype.slice.call(arguments),
	nid,
	cb;

	args.shift(); // first arg is always vid
	if (typeof args[0] === 'string') { // nid specified
	nid = args.shift();
	}
	cb = args.shift();

	this.vid = vid;

	if (validateViewArgs(vid)) {
	this.nid = nid; // explicit navitem id (can be null)
	this.cb = $.isPlainObject(cb) ? cb : {}; // callbacks
	this.$div = null; // view not yet added to DOM
	this.radioButtons = null; // no radio buttons yet
	this.ok = true; // valid view
	}
	}

	function validateViewArgs(vid) {
	var av = "ui.addView(...): ",
	ok = false;
	if (typeof vid !== 'string' \|\| !vid) {
	doError(av + 'vid required');
	} else if (views[vid]) {
	doError(av + 'View ID "' + vid + '" already exists');
	} else {
	ok = true;
	}
	return ok;
	}

	var viewInstanceMethods = {
	token: function () {
	return {
	// attributes
	vid: this.vid,
	nid: this.nid,
	$div: this.$div,

	// functions
	width: this.width,
	height: this.height,
	uid: this.uid,
	setRadio: this.setRadio,
	setKeys: this.setKeys,
	dataLoadError: this.dataLoadError,
	alert: this.alert
	}
	},

	preload: function (ctx, flags) {
	var c = ctx \|\| '',
	fn = isF(this.cb.preload);
	traceFn('View.preload', this.vid + ', ' + c);
	if (fn) {
	trace('PRELOAD cb for ' + this.vid);
	fn(this.token(), c, flags);
	}
	},

	reset: function () {
	var fn = isF(this.cb.reset);
	traceFn('View.reset', this.vid);
	if (fn) {
	trace('RESET cb for ' + this.vid);
	fn(this.token());
	} else if (this.cb.reset === true) {
	// boolean true signifies "clear view"
	trace(' [true] cleaing view...');
	viewApi.empty();
	}
	},

	load: function (ctx, flags) {
	var c = ctx \|\| '',
	fn = isF(this.cb.load);
	traceFn('View.load', this.vid + ', ' + c);
	this.$div.classed('currentView', true);
	if (fn) {
	trace('LOAD cb for ' + this.vid);
	fn(this.token(), c, flags);
	}
	},

	unload: function () {
	var fn = isF(this.cb.unload);
	traceFn('View.unload', this.vid);
	this.$div.classed('currentView', false);
	if (fn) {
	trace('UNLOAD cb for ' + this.vid);
	fn(this.token());
	}
	},

	resize: function (ctx, flags) {
	var c = ctx \|\| '',
	fn = isF(this.cb.resize),
	w = this.width(),
	h = this.height();
	traceFn('View.resize', this.vid + '/' + c +
	' [' + w + 'x' + h + ']');
	if (fn) {
	trace('RESIZE cb for ' + this.vid);
	fn(this.token(), c, flags);
	}
	},

	error: function (ctx) {
	var c = ctx \|\| '',
	fn = isF(this.cb.error);
	traceFn('View.error', this.vid + ', ' + c);
	if (fn) {
	trace('ERROR cb for ' + this.vid);
	fn(this.token(), c);
	}
	},

	width: function () {
	return $(this.$div.node()).width();
	},

	height: function () {
	return $(this.$div.node()).height();
	},

	setRadio: function (btnSet) {
	setRadioButtons(this.vid, btnSet);
	},

	setKeys: function (keyArg) {
	setKeyBindings(keyArg);
	},

	uid: function (id) {
	return makeUid(this, id);
	},

	// TODO : implement custom dialogs

	// Consider enhancing alert mechanism to handle multiples
	// as individually closable.
	alert: function (msg) {
	doAlert(msg);
	},

	dataLoadError: function (err, url) {
	var msg = 'Data Load Error\n\n' +
	err.status + ' -- ' + err.statusText + '\n\n' +
	'relative-url: "' + url + '"\n\n' +
	'complete-url: "' + err.responseURL + '"';
	this.alert(msg);
	}

	// TODO: consider schedule, clearTimer, etc.
	};

	// attach instance methods to the view prototype
	$.extend(View.prototype, viewInstanceMethods);

	// ..........................................................
	// UI API

	uiApi = {
	addLib: function (libName, api) {
	// TODO: validation of args
	libApi[libName] = api;
	},

	// TODO: it remains to be seen whether we keep this style of docs
	/** @api ui addView( vid, nid, cb )
	* Adds a view to the UI.
	* <p>
	* Views are loaded/unloaded into the view content pane at
	* appropriate times, by the navigation framework. This method
	* adds a view to the UI and returns a token object representing
	* the view. A view's token is always passed as the first
	* argument to each of the view's life-cycle callback functions.
	* <p>
	* Note that if the view is directly referenced by a nav-item,
	* or in a group of views with one of those views referenced by
	* a nav-item, then the <i>nid</i> argument can be omitted as
	* the framework can infer it.
	* <p>
	* <i>cb</i> is a plain object containing callback functions:
	* "preload", "reset", "load", "unload", "resize", "error".
	* <pre>
	* function myLoad(view, ctx) { ... }
	* ...
	* // short form...
	* onos.ui.addView('viewId', {
	* load: myLoad
	* });
	* </pre>
	*
	* @param vid (string) [*] view ID (a unique DOM element id)
	* @param nid (string) nav-item ID (a unique DOM element id)
	* @param cb (object) [*] callbacks object
	* @return the view token
	*/
	addView: function (vid, nid, cb) {
	traceFn('addView', vid);
	var view = new View(vid, nid, cb),
	token;
	if (view.ok) {
	views[vid] = view;
	token = view.token();
	} else {
	token = { vid: view.vid, bad: true };
	}
	return token;
	}
	};

	// ..........................................................
	// View API

	viewApi = {
	/** @api view empty( )
	* Empties the current view.
	* <p>
	* More specifically, removes all DOM elements from the
	* current view's display div.
	*/
	empty: function () {
	if (!current.view) {
	return;
	}
	current.view.$div.html('');
	}
	};

	// ..........................................................
	// Nav API
	navApi = {

	};

	// ..........................................................
	// Library API
	libApi = {

	};

	// ..........................................................
	// Exported API

	// function to be called from index.html to build the ONOS UI
	function buildOnosUi() {
	tsB = new Date().getTime();
	tsI = tsB - tsI; // initialization duration

	console.log('ONOS UI initialized in ' + tsI + 'ms');

	if (built) {
	throwError("ONOS UI already built!");
	}
	built = true;

	$view = d3.select('#view');
	$mastRadio = d3.select('#mastRadio');

	$(window).on('hashchange', hash);
	$(window).on('resize', resize);

	d3.select('body').on('keydown', keyIn);
	setupGlobalKeys();

	// Invoke hashchange callback to navigate to content
	// indicated by the window location hash.
	hash();

	// If there were any build errors, report them
	reportBuildErrors();
	}

	// export the api and build-UI function
	return {
	ui: uiApi,
	lib: libApi,
	//view: viewApi,
	nav: navApi,
	buildUi: buildOnosUi
	};
	};

	}(jQuery));