Namespace: popMenu

popMenu

Methods

(static) build(el, menuopt) → {Element}

Builds a new menu pre-populated with items and groups.

This function creates a new pop-up menu (a.k.a. "drop-down"). This is a <select>...</select> element, pre-populated with items (<option>...</option> elements) and groups (<optgroup>...</optgroup> elements).

Bonus: This function also builds input type=text elements. NOTE: This function generates OPTGROUP elements for subtrees. However, note that HTML5 specifies that OPTGROUP elemnents made not nest! This function generates the markup for them but they are not rendered by most browsers, or not completely. Therefore, for now, do not specify more than one level subtrees. Future versions of HTML may support it. I also plan to add here options to avoid OPTGROUPS entirely either by indenting option text, or by creating alternate DOM nodes using <li> instead of <select>, or both.

Parameters:
Name Type Attributes Default Description
el Element | string

Must be one of (case-sensitive):

  • text box - an HTMLInputElement to use an existing element or 'INPUT' to create a new one
  • drop-down - an HTMLSelectElement to use an existing element or 'SELECT' to create a new one
  • submenu - an HTMLOptGroupElement to use an existing element or 'OPTGROUP' to create a new one (meant for internal use only)
menu Array.<menuItem> <optional>

Hierarchical list of strings to add as <option>...</option> or <optgroup>....</optgroup> elements. Omitting creates a text box.
options.prompt null | string <optional>
 ''

Adds an initial <option>...</option> element to the drop-down with this value in parentheses as its text; and empty string as its value. Default is empty string, which creates a blank prompt; null suppresses prompt altogether.
options.sort boolean <optional>

Whether to alpha sort or not. If truthy, sorts each optgroup on its label; and each select option on its text (its alias or header if given; or its name if not).
options.blacklist Array.<string> <optional>

Optional list of menu item names to be ignored.
options.breadcrumbs Array.<number> <optional>

List of option group section numbers (root is section 0). (For internal use.)
options.append boolean <optional>
 false

When el is an existing <select> Element, giving truthy value adds the new children without first removing existing children.
Returns:

Either a <select> or <optgroup> element.

Type
Element

(static) formatItem(item) → {string}

Format item name with it's alias when available.

Parameters:
Name Type Description
item string | valueItem
Returns:

The formatted name and alias.

Type
string

(static) lookup(optionsopt, value) → {undefined|menuItem}

Recursively searches the context array of menuItems for a named item.

This:
  • Array
Parameters:
Name Type Attributes Description
options object <optional>
Properties
Name Type Attributes Default Description
keys string <optional>
 [popMenu.defaultKey]

Properties to search each menuItem when it is an object.
caseSensitive boolean <optional>
 false

Ignore case while searching.
value string

Value to search for.
Returns:

The found item or undefined if not found.

Type
undefined | menuItem

(static) walk(iteratee) → {number}

Recursively walks the context array of menuItems and calls iteratee on each item therein.

iteratee is called with each item (terminal node) in the menu tree and a flat 0-based index. Recurses on member with name of popMenu.subtree.

The node will always be a valueItem object; when a string, it is boxed for you.

This:
  • Array
Parameters:
Name Type Description
iteratee function

For each item in the menu, iteratee is called with:

  • the valueItem (if the item is a primative string, it is wrapped up for you)
  • a 0-based ordinal

The iteratee return value can be used to replace the item, as follows:

  • undefined - do nothing
  • null - splice out the item; resulting empty submenus are also spliced out (see note)
  • anything else - replace the item with this value; if value is a subtree (i.e., an array) iteratee will then be called to walk it as well (see note)

Note: Returning anything (other than undefined) from iteratee will (deeply) mutate the original menu so you may want to copy it first (deeply, including all levels of array nesting but not the terminal node objects).
Returns:

Number of items (terminal nodes) in the menu tree.

Type
number