Open Source Monorail

appengine/monorail/static/js/framework/framework-menu.js

+/* Copyright 2016 The Chromium Authors. All Rights Reserved.
+ *
+ * Use of this source code is governed by a BSD-style
+ * license that can be found in the LICENSE file or at
+ * https://developers.google.com/open-source/licenses/bsd
+ */
+
+/**
+ * @fileoverview This file represents a standalone, reusable drop down menu
+ * widget that can be attached to any element on a given page. It supports
+ * multiple instances of the widget on a page. It has no dependencies. Usage
+ * is as simple as creating a new Menu object and supplying it with a target
+ * element.
+ */
+
+/**
+ * The entry point and constructor for the Menu object. Creating
+ * a valid instance of this object will insert a drop down menu
+ * near the element supplied as the target, attach all the necessary
+ * events and insert the necessary elements on the page.
+ *
+ * @param {Element} target the target element on the page to which
+ *     the drop down menu will be placed near.
+ * @param {Function=} opt_onShow function to execute every time the
+ *     menu is made visible, most likely through a click on the target.
+ * @constructor
+ */
+var Menu = function(target, opt_onShow) {
+  this.iid = Menu.instance.length;
+  Menu.instance[this.iid] = this;
+  this.target = target;
+  this.onShow = opt_onShow || null;
+
+  // An optional trigger element on the page that can be used to trigger
+  // the drop-down. Currently hard-coded to be the same as the target element.
+  this.trigger = target;
+  this.items = [];
+  this.onOpenEvents = [];
+  this.menu = this.createElement('div', 'menuDiv instance' + this.iid);
+  this.targetId = this.target.getAttribute('id');
+  var menuId = (this.targetId != null) ?
+      'menuDiv-' + this.targetId : 'menuDiv-instance' + this.iid;
+  this.menu.setAttribute('id', menuId);
+  this.menu.role = 'listbox';
+  this.hide();
+  this.addCategory('default');
+  this.addEvent(this.trigger, 'click', this.wrap(this.toggle));
+  this.addEvent(window, 'resize', this.wrap(this.adjustSizeAndLocation));
+
+  // Hide the menu if a user clicks outside the menu widget
+  this.addEvent(document, 'click', this.wrap(this.hide));
+  this.addEvent(this.menu, 'click', this.stopPropagation());
+  this.addEvent(this.trigger, 'click', this.stopPropagation());
+};
+
+// A reference to the element or node that the drop down
+// will appear next to
+Menu.prototype.target = null;
+
+// Element ID of the target. ID will be assigned to the newly created
+// menu div based on the target ID. A default ID will be
+// assigned If there is no ID on the target.
+Menu.prototype.targetId = null;
+
+/**
+ * A reference to the element or node that will trigger
+ * the drop down to appear. If not specified, this value
+ * will be the same as <Menu Instance>.target
+ * @type {Element}
+ */
+Menu.prototype.trigger = null;
+
+// A reference to the event type that will "open" the
+// menu div. By default this is the (on)click method.
+Menu.prototype.triggerType = null;
+
+// A reference to the element that will appear when the
+// trigger is clicked.
+Menu.prototype.menu = null;
+
+/**
+ * Function to execute every time the menu is made shown.
+ * @type {Function}
+ */
+Menu.prototype.onShow = null;
+
+// A list of category divs. By default these categories
+// are set to display none until at least one element
+// is placed within them.
+Menu.prototype.categories = null;
+
+// An id used to track timed intervals
+Menu.prototype.thread = -1;
+
+// The static instance id (iid) denoting which menu in the
+// list of Menu.instance items is this instantiated object.
+Menu.prototype.iid = -1;
+
+// A counter to indicate the number of items added with
+// addItem(). After 5 items, a height is set on the menu
+// and a scroll bar will appear.
+Menu.prototype.items = null;
+
+// A flag to detect whether or not a scroll bar has been added
+Menu.prototype.scrolls = false;
+
+// onOpen event handlers; each function in this list will
+// be executed and passed the executing instance as a
+// parameter before the menu is to be displayed.
+Menu.prototype.onOpenEvents = null;
+
+/**
+ * An extended short-cut for document.createElement(); this
+ * method allows the creation of an element, the assignment
+ * of one or more class names and the ability to set the
+ * content of the created element all with one function call.
+ * @param {string} element name of the element to create. Examples would
+ *     be 'div' or 'a'.
+ * @param {string} opt_className an optional string to assign to the
+ *     newly created element's className property.
+ * @param {string|Element} opt_content either a snippet of HTML or a HTML
+ *     element that is to be appended to the newly created element.
+ * @return {Element} a reference to the newly created element.
+ */
+Menu.prototype.createElement = function(element, opt_className, opt_content) {
+  var div = document.createElement(element);
+  div.className = opt_className;
+  if (opt_content) {
+    this.append(opt_content, div);
+  }
+  return div;
+};
+
+/**
+ * Uses a fairly browser agnostic approach to applying a callback to
+ * an element on the page.
+ *
+ * @param {Element|EventTarget} element a reference to an element on the page to
+ *     which to attach and event.
+ * @param {string} eventType a browser compatible event type as a string
+ *     without the sometimes assumed on- prefix. Examples: 'click',
+ *     'mousedown', 'mouseover', etc...
+ * @param {Function} callback a function reference to invoke when the
+ *     the event occurs.
+ */
+Menu.prototype.addEvent = function(element, eventType, callback) {
+  if (element.addEventListener) {
+    element.addEventListener(eventType, callback, false);
+  } else {
+    try {
+      element.attachEvent('on' + eventType, callback);
+    } catch (e) {
+      element['on' + eventType] = callback;
+    }
+  }
+};
+
+/**
+ * Similar to addEvent, this provides a specialied handler for onOpen
+ * events that apply to this instance of the Menu class. The supplied
+ * callbacks are appended to an internal array and called in order
+ * every time the menu is opened. The array can be accessed via
+ * menuInstance.onOpenEvents.
+ */
+Menu.prototype.addOnOpen = function(eventCallback) {
+  var eventIndex = this.onOpenEvents.length;
+  this.onOpenEvents.push(eventCallback);
+  return eventIndex;
+};
+
+/**
+ * Used throughout the code, this method wraps any supplied function
+ * in a closure that calls the supplied function in the context of either
+ * the optional thisObj parameter or instance of the menu this function
+ * is called from.
+ * @param {Function} callback the function to wrap and embed context
+ *     within.
+ * @param {Object} opt_thisObj an alternate 'this' object to use instead
+ *     of this instance of Menu.
+ */
+Menu.prototype.wrap = function(callback, opt_thisObj) {
+  var closured_callback = callback;
+  var this_object = opt_thisObj || this;
+  return (function() {
+    closured_callback.apply(this_object);
+  });
+};
+
+/**
+ * This method will create a div with the classes .menuCategory and the
+ * name of the category as supplied in the first parameter. It then, if
+ * a title is supplied, creates a title div and appends it as well. The
+ * optional title is styled with the .categoryTitle and category name
+ * class.
+ *
+ * Categories are stored within the menu object instance for programmatic
+ * manipulation in the array, menuInstance.categories. Note also that this
+ * array is doubly linked insofar as that the category div can be accessed
+ * via it's index in the array as well as by instance.categories[category]
+ * where category is the string name supplied when creating the category.
+ *
+ * @param {string} category the string name used to create the category;
+ *     used as both a class name and a key into the internal array. It
+ *     must be a valid JavaScript variable name.
+ * @param {string|Element} opt_title this optional field is used to visibly
+ *     denote the category title. It can be either HTML or an element.
+ * @return {Element} the newly created div.
+ */
+Menu.prototype.addCategory = function(category, opt_title) {
+  this.categories = this.categories || [];
+  var categoryDiv = this.createElement('div', 'menuCategory ' + category);
+  categoryDiv._categoryName = category;
+  if (opt_title) {
+    var categoryTitle = this.createElement('b', 'categoryTitle ' +
+          category, opt_title);
+    categoryTitle.style.display = 'block';
+    this.append(categoryTitle);
+    categoryDiv._categoryTitle = categoryTitle;
+  }
+  this.append(categoryDiv);
+  this.categories[this.categories.length] = this.categories[category] =
+      categoryDiv;
+
+  return categoryDiv;
+};
+
+/**
+ * This method removes the contents of a given category but does not
+ * remove the category itself.
+ */
+Menu.prototype.emptyCategory = function(category) {
+  if (!this.categories[category]) {
+    return;
+  }
+  var div = this.categories[category];
+  for (var i = div.childNodes.length - 1; i >= 0; i--) {
+    div.removeChild(div.childNodes[i]);
+  }
+};
+
+/**
+ * This function is the most drastic of the cleansing functions; it removes
+ * all categories and all menu items and all HTML snippets that have been
+ * added to this instance of the Menu class.
+ */
+Menu.prototype.clear = function() {
+  for (var i = 0; i < this.categories.length; i++) {
+    // Prevent memory leaks
+    this.categories[this.categories[i]._categoryName] = null;
+  }
+  this.items.splice(0, this.items.length);
+  this.categories.splice(0, this.categories.length);
+  this.categories = [];
+  this.items = [];
+  for (var i = this.menu.childNodes.length - 1; i >= 0; i--) {
+    this.menu.removeChild(this.menu.childNodes[i]);
+  }
+};
+
+/**
+ * Passed an instance of a menu item, it will be removed from the menu
+ * object, including any residual array links and possible memory leaks.
+ * @param {Element} item a reference to the menu item to remove.
+ * @return {Element} returns the item removed.
+ */
+Menu.prototype.removeItem = function(item) {
+  var result = null;
+  for (var i = 0; i < this.items.length; i++) {
+    if (this.items[i] == item) {
+      result = this.items[i];
+      this.items.splice(i, 1);
+    }
+    // Renumber
+    this.items[i].item._index = i;
+  }
+  return result;
+};
+
+/**
+ * Removes a category from the menu element and all of its children thus
+ * allowing the Element to be collected by the browsers VM.
+ * @param {string} category the name of the category to retrieve and remove.
+ */
+Menu.prototype.removeCategory = function(category) {
+  var div = this.categories[category];
+  if (!div || !div.parentNode) {
+    return;
+  }
+  if (div._categoryTitle) {
+    div._categoryTitle.parentNode.removeChild(div._categoryTitle);
+  }
+  div.parentNode.removeChild(div);
+  for (var i = 0; i < this.categories.length; i++) {
+    if (this.categories[i] === div) {
+      this.categories[this.categories[i]._categoryName] = null;
+      this.categories.splice(i, 1);
+      return;
+    }
+  }
+  for (var i = 0; i < div.childNodes.length; i++) {
+    if (div.childNodes[i]._index) {
+      this.items.splice(div.childNodes[i]._index, 1);
+    } else {
+      this.removeItem(div.childNodes[i]);
+    }
+  }
+};
+
+/**
+ * This heart of the menu population scheme, the addItem function creates
+ * a combination of elements that visually form up a menu item. If no
+ * category is supplied, the default category is used. The menu item is
+ * an <a> tag with the class .menuItem. The menu item is directly styled
+ * as a block element. Other than that, all styling should be done via a
+ * external CSS definition.
+ *
+ * @param {string|Element} html_or_element a string of HTML text or a
+ *     HTML element denoting the contents of the menu item.
+ * @param {string} opt_href the href of the menu item link. This is
+ *     the most direct way of defining the menu items function.
+ *     [Default: '#'].
+ * @param {string} opt_category the category string name of the category
+ *     to append the menu item to. If the category doesn't exist, one will
+ *     be created. [Default: 'default'].
+ * @param {string} opt_title used when creating a new category and is
+ *     otherwise ignored completely. It is also ignored when supplied if
+ *     the named category already exists.
+ * @return {Element} returns the element that was created.
+ */
+Menu.prototype.addItem = function(html_or_element, opt_href, opt_category,
+                                  opt_title) {
+  var category = opt_category ? (this.categories[opt_category] ||
+                                 this.addCategory(opt_category, opt_title)) :
+      this.categories['default'];
+  var menuHref = (opt_href == undefined ? '#' : opt_href);
+  var menuItem = undefined;
+  if (menuHref) {
+    menuItem = this.createElement('a', 'menuItem', html_or_element);
+  } else {
+    menuItem = this.createElement('span', 'menuText', html_or_element);
+  }
+  var itemText = typeof html_or_element == 'string' ? html_or_element :
+      html_or_element.innerText || 'ERROR';
+
+  menuItem.style.display = 'block';
+  if (menuHref) {
+    menuItem.setAttribute('href', menuHref);
+  }
+  menuItem._index = this.items.length;
+  menuItem.role = 'option';
+  this.append(menuItem, category);
+  this.items[this.items.length] = {item: menuItem, text: itemText};
+
+  return menuItem;
+};
+
+/**
+ * Adds a visual HTML separator to the menu, optionally creating a
+ * category as per addItem(). See above.
+ * @param {string} opt_category the category string name of the category
+ *     to append the menu item to. If the category doesn't exist, one will
+ *     be created. [Default: 'default'].
+ * @param {string} opt_title used when creating a new category and is
+ *     otherwise ignored completely. It is also ignored when supplied if
+ *     the named category already exists.
+ */
+Menu.prototype.addSeparator = function(opt_category, opt_title) {
+  var category = opt_category ? (this.categories[opt_category] ||
+                                 this.addCategory(opt_category, opt_title)) :
+      this.categories['default'];
+  var hr = this.createElement('hr', 'menuSeparator');
+  this.append(hr, category);
+};
+
+/**
+ * This method performs all the dirty work of positioning the menu. It is
+ * responsible for dynamic sizing, insertion and deletion of scroll bars
+ * and calculation of offscreen width considerations.
+ */
+Menu.prototype.adjustSizeAndLocation = function() {
+  var style = this.menu.style;
+  style.position = 'absolute';
+
+  var firstCategory = null;
+  for (var i = 0; i < this.categories.length; i++) {
+    this.categories[i].className = this.categories[i].className.
+        replace(/ first/, '');
+    if (this.categories[i].childNodes.length == 0) {
+      this.categories[i].style.display = 'none';
+    } else {
+      this.categories[i].style.display = '';
+      if (!firstCategory) {
+        firstCategory = this.categories[i];
+        firstCategory.className += ' first';
+      }
+    }
+  }
+
+  var alreadyVisible = style.display != 'none' &&
+      style.visibility != 'hidden';
+  var docElemWidth = document.documentElement.clientWidth;
+  var docElemHeight = document.documentElement.clientHeight;
+  var pageSize = {
+    w: (window.innerWidth || docElemWidth && docElemWidth > 0 ?
+        docElemWidth : document.body.clientWidth) || 1,
+    h: (window.innerHeight || docElemHeight && docElemHeight > 0 ?
+        docElemHeight : document.body.clientHeight) || 1
+  };
+  var targetPos = this.find(this.target);
+  var targetSize = {w: this.target.offsetWidth,
+                    h: this.target.offsetHeight};
+  var menuSize = {w: this.menu.offsetWidth, h: this.menu.offsetHeight};
+
+  if (!alreadyVisible) {
+    var oldVisibility = style.visibility;
+    var oldDisplay = style.display;
+    style.visibility = 'hidden';
+    style.display = '';
+    style.height = '';
+    style.width = '';
+    menuSize = {w: this.menu.offsetWidth, h: this.menu.offsetHeight};
+    style.display = oldDisplay;
+    style.visibility = oldVisibility;
+  }
+
+  var addScroll = (this.menu.offsetHeight / pageSize.h) > 0.8;
+  if (addScroll) {
+    menuSize.h = parseInt((pageSize.h * 0.8), 10);
+    style.height = menuSize.h + 'px';
+    style.overflowX = 'hidden';
+    style.overflowY = 'auto';
+  } else {
+    style.height = style.overflowY = style.overflowX = '';
+  }
+
+  style.top = (targetPos.y + targetSize.h) + 'px';
+  style.left = targetPos.x + 'px';
+
+  if (menuSize.w < 175) {
+    style.width = '175px';
+  }
+
+  if (addScroll) {
+    style.width = parseInt(style.width, 10) + 13 + 'px';
+  }
+
+  if ((targetPos.x + menuSize.w) > pageSize.w) {
+    style.left = targetPos.x - (menuSize.w - targetSize.w) + 'px';
+  }
+};
+
+
+/**
+ * This function is used heavily, internally. It appends text
+ * or the supplied element via appendChild(). If
+ * the opt_target variable is present, the supplied element will be
+ * the container rather than the menu div for this instance.
+ *
+ * @param {string|Element} text_or_element the html or element to insert
+ *     into opt_target.
+ * @param {Element} opt_target the target element it should be appended to.
+ *
+ */
+Menu.prototype.append = function(text_or_element, opt_target) {
+  var element = opt_target || this.menu;
+  if (typeof opt_target == 'string' && this.categories[opt_target]) {
+    element = this.categories[opt_target];
+  }
+  if (typeof text_or_element == 'string') {
+    element.innerText += text_or_element;
+  } else {
+    element.appendChild(text_or_element);
+  }
+};
+
+/**
+ * Displays the menu (such as upon mouseover).
+ */
+Menu.prototype.over = function() {
+  if (this.menu.style.display != 'none') {
+    this.show();
+  }
+  if (this.thread != -1) {
+    clearTimeout(this.thread);
+    this.thread = -1;
+  }
+};
+
+/**
+ * Hides the menu (such as upon mouseout).
+ */
+Menu.prototype.out = function() {
+  if (this.thread != -1) {
+    clearTimeout(this.thread);
+    this.thread = -1;
+  }
+  this.thread = setTimeout(this.wrap(this.hide), 400);
+};
+
+/**
+ * Stops event propagation.
+ */
+Menu.prototype.stopPropagation = function() {
+  return (function(e) {
+    if (!e) {
+      e = window.event;
+    }
+    e.cancelBubble = true;
+    if (e.stopPropagation) {
+      e.stopPropagation();
+    }
+  });
+};
+
+/**
+ * Toggles the menu between hide/show.
+ */
+Menu.prototype.toggle = function() {
+  if (this.menu.style.display == 'none') {
+    this.show();
+  } else {
+    this.hide();
+  }
+};
+
+/**
+ * Makes the menu visible, then calls the user-supplied onShow callback.
+ */
+Menu.prototype.show = function() {
+  if (this.menu.style.display != '') {
+    for (var i = 0; i < this.onOpenEvents.length; i++) {
+      this.onOpenEvents[i].call(null, this);
+    }
+
+    // Invisibly show it first
+    this.menu.style.visibility = 'hidden';
+    this.menu.style.display = '';
+    this.adjustSizeAndLocation();
+    if (this.trigger.nodeName && this.trigger.nodeName == 'A') {
+      this.trigger.blur();
+    }
+    this.menu.style.visibility = 'visible';
+
+    // Hide other menus
+    for (var i = 0; i < Menu.instance.length; i++) {
+      var menuInstance = Menu.instance[i];
+      if (menuInstance != this) {
+        menuInstance.hide();
+      }
+    }
+
+    if (this.onShow) {
+      this.onShow();
+    }
+  }
+};
+
+/**
+ * Makes the menu invisible.
+ */
+Menu.prototype.hide = function() {
+  this.menu.style.display = 'none';
+};
+
+Menu.prototype.find = function(element) {
+  var curleft = 0, curtop = 0;
+  if (element.offsetParent) {
+    do {
+      curleft += element.offsetLeft;
+      curtop += element.offsetTop;
+    }
+    while ((element = element.offsetParent) && (element.style &&
+          element.style.position != 'relative' &&
+          element.style.position != 'absolute'));
+    }
+  return {x: curleft, y: curtop};
+};
+
+/**
+ * A static array of object instances for global reference.
+ * @type {Array.<Menu>}
+ */
+Menu.instance = [];