Rwt-nested-menu NPM

Open Source DOM Component

Nested Menu

Multi-column expandable dropdown

Motivation

Sometimes you need to provide your website visitors with quick access to a large quantity of pages without cluttering the main reading area of the page.

The rwt-nested-menu DOM component does this by keeping a menu collapsed at the top of the page until the user needs it.

When the menu is activated, it opens up as a multi-column panel, where the number of columns is automatically adjusted to match the space available and the number of configured items.

Activation may also be initiated through the component's toggleMenu method or through its event interface.

The component has these features:

First level menu items are shown by default. Second level menu items are shown when the user selects a first-level item.
The menu has both a keyboard and mouse interface, with no risk of loosing focus when the mouse leaves the menu area.
The actual menu items are kept separate from the DOM component, allowing the webmaster to change its contents in a single centralized place.
The menu item corresponding to the current document is highlighted when the collapsed menu is first expanded.
The menu has an event interface for showing and hiding itself.
The menu emits a custom event to close sibling menus and dialog boxes, so that only one is open at a time.
A keyboard listener is provided to allow a shortcut key to open/close the menu.

In the wild

To see an example of this component in use, visit the BLUEPHRASE website. It uses this component for the SYNTAX, SEMANTAX and STYLE buttons. To understand what's going on under the hood, use the browser's inspector to view the HTML source code and network activity, and follow along as you read this documentation.

Installation

Prerequisites

The rwt-nested-menu DOM component works in any browser that supports modern W3C standards. Templates are written using BLUE PHRASE notation, which can be compiled into HTML using the free Read Write View desktop app. It has no other prerequisites. Distribution and installation are done with either NPM or via Github.

Download

Using the DOM component

After installation, you need to add two things to your HTML page to make use of it.

Add a script tag to load the component's rwt-nested-menu.js file:

<script src='/node_modules/rwt-nested-menu/rwt-nested-menu.js' type=module></script>

Add the component tag somewhere on the page.
- For scripting purposes, apply an id attribute.
- Apply a sourceref attribute with a reference to an HTML file containing the intended menu items.
- Optionally, apply a shortcut attribute with something like F9, F10, etc. for hotkey access.
- For WAI-ARIA accessibility apply a role=navigation attribute.

<rwt-nested-menu id=nested-menu sourceref='/menu.html' shortcut=F9 role=navigation></rwt-nested-menu>

Menu template

Each intended menu element should be defined (in the file specified in the sourceref attribute) as an HTML anchor tag. There are two types of elements, distinguished by classname: group and item. Item elements should have an href attribute referencing its target document. Group elements should not include an href attribute.

All elements are siblings to each other, and there is no explicit hierarchy. Rather it is implied that any item element following a group element belongs to the preceding group element.

The text for each element will be clipped to fit on one line, so the text should be short.

Here is an example, using BLUEPHRASE notation, with two groups.

a .group ESCAPES
a .item `/syntax/escapes/escape.blue` escape
a .item `/syntax/escapes/unicode.blue` unicode

a .group NOTES
a .item `/syntax/notes/comment.blue` comment
a .item `/syntax/notes/remark.blue` remark
a .item `/syntax/notes/reply.blue` reply
a .item `/syntax/notes/placeholder.blue` placeholder

Self identification

The menu item corresponding to the current page can be highlighted if it identifies itself to the menu, so as to provide a frame of reference for the user. This is accomplished by adding meta tags to the page. So, referring to the example, if the current page is /syntax/escapes/unicode.blue the meta tags would be:

<meta name=nested-menu:group content='ESCAPES' />
<meta name=nested-menu:item content='unicode' />

Customization

Menu items

When expanded, the menu panel is positioned in a fixed location, a certain distance from the top of the page. This should be set using the --menu-top variable. Each element within the menu is sized using the --item-height and --item-width variables. Here is an example:

rwt-nested-menu {
    --menu-top: 0;
    --font-size: 0.8rem;
    --item-height: 2rem;
    --item-width: 11rem;
    --z-index: 1;
}

Menu color scheme

The default color palette for the menu uses a dark mode theme. You can use CSS to override the variables' defaults:

rwt-nested-menu {
    --color: var(--pure-white);
    --accent-color1: var(--title-blue);
    --accent-color2: var(--yellow);
    
    --menu-background: var(--medium-black);
    --group-background: var(--medium-black);
    --item-background: var(--black);
    --hover-background: var(--form-gray);
    --active-background: var(--pure-black);

    --thick-border: var(--pure-black);
    --thin-border: var(--light-black);
    --item-border: var(--white);
}